# Feature Specification: Agentic Harness Foundation

> For the complete documentation index, see [llms.txt](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/llms.txt).

**Feature Branch**: `003-agentic-harness-foundation`  
**Created**: 2026-04-10  
**Status**: Implemented  
**Input**: Transition delta from `002-edge-proxy-uncontainerized`

## User Stories

*   As a developer, I want each generated codebase to include clear agent guidance so local AI-assisted edits are safe and consistent.
*   As a contributor, I want generated codebases to state that upstream enhancements must be made in spec packs, not directly in generated snapshots.
*   As a maintainer, I want the harness contract to be inherited by later states without per-state duplication.

## Functional Requirements

*   FR-00301: Generating this state must produce `AGENTS.md` in the generated codebase root.
*   FR-00302: Generating this state must produce `ARCHITECTURE.md` in the generated codebase root.
*   FR-00303: Generating this state must produce `CONTRIBUTING.md` in the generated codebase root.
*   FR-00304: `CONTRIBUTING.md` must explicitly state that enhancement contributions belong in upstream specs/state packs, not in generated snapshot branches.
*   FR-00305: Runtime behavior and smoke-test behavior from state `002-edge-proxy-uncontainerized` remain unchanged.

## Non-Functional Requirements

*   NFR-00301: Harness artifact generation is deterministic and idempotent for repeated state generation runs.
*   NFR-00302: Harness files must be concise and avoid duplicating existing generated runbook content.
*   NFR-00303: States from `003` onward inherit the harness contract unless explicitly overridden.
*   NFR-00304: State generation MUST run sequentially when using the default shared output root (`generated/**`) to avoid race conditions; parallel generation is only permitted when each run uses an isolated `TRADERX_GENERATED_ROOT`.
*   NFR-00305: Node dependency lockfiles (`package-lock.json`) in generated outputs MUST remain synchronized with each module's current `package.json`; generation should refresh lockfiles only when manifests change or lockfiles are missing/invalid.
*   NFR-00306: Gradle wrapper assets (`gradlew`, `gradlew.bat`, `gradle/wrapper/**`) MUST be template-owned baseline artifacts and must not be maintained in state patchsets.
*   NFR-00307: State patchsets MUST exclude build/restored byproducts (`.gradle/**`, `build/**`, `target/**`, `bin/**`, `obj/**`, `dist/**`, `coverage/**`, `node_modules/**`) so patches remain authored deltas only.
*   NFR-00308: Default generated-branch build/test CI MUST be hermetic and runnable without external runtime services; database-backed tests in default test suites MUST use in-memory/embedded databases (or equivalent local isolated test engines). External-database validation is permitted only in explicitly named integration profiles/jobs separate from default build/test gates.
*   NFR-00309: Generated-state publish flows MUST run module compilation preflight across generated Node.js, Gradle, and .NET modules and MUST fail before commit/push when preflight fails. Any bypass MUST be explicit and operator-invoked.

## Success Criteria

*   SC-00301: `bash pipeline/generate-state.sh 003-agentic-harness-foundation` produces a runnable output with the three harness files in target root.
*   SC-00302: `scripts/test-state-003-agentic-harness-foundation.sh` passes and confirms parity with state `002` behavior.
*   SC-00303: `pipeline/install-generated-runtime-harness.sh` applies harness files for `003+` states.
*   SC-00304: A second concurrent invocation of `pipeline/generate-state.sh` against the same shared output root fails fast with a lock error instead of writing partial output.
*   SC-00305: Publishing a generated state branch fails before commit/push when generated module compilation preflight fails.