<!-- specsmith:generated -- do not edit; regenerated by specsmith sync -->
# Requirements

## REQ-001. Specsmith Must Govern Itself
- **ID:** REQ-001
- **Title:** Specsmith Must Govern Itself
- **Description:** Specsmith must govern its own governance layer and use it for all changes.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-001']

## REQ-002. Governance Files Must Be Owned by Specsmith
- **ID:** REQ-002
- **Title:** Governance Files Must Be Owned by Specsmith
- **Description:** Only Specsmith may create, update, or delete the human‑readable governance files `ARCHITECTURE.md`, `REQUIREMENTS.md`, `TESTS.md`, and `LEDGER.md`.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-002']

## REQ-003. Machine State Must Reflect Governance State
- **ID:** REQ-003
- **Title:** Machine State Must Reflect Governance State
- **Description:** Every machine‑readable state file under `.specsmith/` must be derived from its corresponding human‑readable governance file and remain in sync.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-003']

## REQ-004. Requirements Must Be Derived from Architecture
- **ID:** REQ-004
- **Title:** Requirements Must Be Derived from Architecture
- **Description:** Specsmith must parse `ARCHITECTURE.md` to produce initial requirements.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-004']

## REQ-005. Requirement IDs Must Be Stable
- **ID:** REQ-005
- **Title:** Requirement IDs Must Be Stable
- **Description:** Once assigned, a requirement ID must never change or be reused.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-005']

## REQ-006. Preflight Validation Must Be Performed
- **ID:** REQ-006
- **Title:** Preflight Validation Must Be Performed
- **Description:** Before any governance action, the system must validate inputs and produce structured output with required fields.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-006']

## REQ-007. Test Cases Must Be Generated from Requirements
- **ID:** REQ-007
- **Title:** Test Cases Must Be Generated from Requirements
- **Description:** For each requirement, Specsmith must create or link a test case that can prove the requirement.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-007']

## REQ-008. Each Requirement Must Link to At Least One Test
- **ID:** REQ-008
- **Title:** Each Requirement Must Link to At Least One Test
- **Description:** Each requirement must be traceable to at least one test case.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-008']

## REQ-009. Work Items Must Be Created for Accepted Requirements
- **ID:** REQ-009
- **Title:** Work Items Must Be Created for Accepted Requirements
- **Description:** When a requirement is accepted, a unique work item must be created.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-009']

## REQ-010. Requirements Must Include Priority and Status
- **ID:** REQ-010
- **Title:** Requirements Must Include Priority and Status
- **Description:** Each requirement record must contain `priority` and `status` attributes.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-010']

## REQ-011. Verification Must Include Confidence Scoring
- **ID:** REQ-011
- **Title:** Verification Must Include Confidence Scoring
- **Description:** Every verification run must produce a numeric confidence score along with pass/fail.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-011']

## REQ-012. Equilibrium Must Be Reached Before Finalizing
- **ID:** REQ-012
- **Title:** Equilibrium Must Be Reached Before Finalizing
- **Description:** A work item may be marked finished only when its verification confidence meets or exceeds the configured threshold and no contradictions remain.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-012']

## REQ-013. Retry Recommendations Must Be Provided
- **ID:** REQ-013
- **Title:** Retry Recommendations Must Be Provided
- **Description:** Specsmith must output retry recommendations when verification fails.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-013']

## REQ-014. Retries Must Be Bounded
- **ID:** REQ-014
- **Title:** Retries Must Be Bounded
- **Description:** Each retry mechanism may not exceed a fixed maximum number of attempts.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-014']

## REQ-015. Every Governance Action Must Record a Ledger Event
- **ID:** REQ-015
- **Title:** Every Governance Action Must Record a Ledger Event
- **Description:** All changes are logged to `LEDGER.md` and `.specsmith/ledger.jsonl` with timestamp and type.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-015']

## REQ-016. Trace Chain Must Be Tamper‑Evident
- **ID:** REQ-016
- **Title:** Trace Chain Must Be Tamper‑Evident
- **Description:** The trace chain must use chained cryptographic hashes to provide tamper evidence.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-016']

## REQ-017. OpenCode Must Own Execution and Tools
- **ID:** REQ-017
- **Title:** OpenCode Must Own Execution and Tools
- **Description:** All filesystem operations and tool executions are performed by OpenCode, not Specsmith directly.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-017']

## REQ-018. Specsmith Core Must Be Integration‑Agnostic
- **ID:** REQ-018
- **Title:** Specsmith Core Must Be Integration‑Agnostic
- **Description:** The core logic must run without dependency on any particular integration implementation.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-018']

## REQ-019. Verification Must Evaluate Changed Files
- **ID:** REQ-019
- **Title:** Verification Must Evaluate Changed Files
- **Description:** Verification must analyze which files were changed and only evaluate affected test cases.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-019']

## REQ-020. Verification Must Evaluate Diff Relevance
- **ID:** REQ-020
- **Title:** Verification Must Evaluate Diff Relevance
- **Description:** Verification must determine whether a diff impacts any requirement or test case and ignore irrelevant changes.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-020']

## REQ-021. Verification Must Evaluate Test Results
- **ID:** REQ-021
- **Title:** Verification Must Evaluate Test Results
- **Description:** Verification must compare actual output against expected and quantify failures.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-021']

## REQ-022. Verification Must Evaluate Contradictions and Uncertainty
- **ID:** REQ-022
- **Title:** Verification Must Evaluate Contradictions and Uncertainty
- **Description:** Verification must identify logical contradictions and uncertainty metrics.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-022']

## REQ-023. Requirement Schema Must Include Source Location, Type, Priority, Confidence, Status, and Timestamps
- **ID:** REQ-023
- **Title:** Requirement Schema Must Include Source Location, Type, Priority, Confidence, Status, and Timestamps
- **Description:** Each requirement record must contain these schema fields.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-023']

## REQ-024. Test Case Model Must Include Required Fields
- **ID:** REQ-024
- **Title:** Test Case Model Must Include Required Fields
- **Description:** All test case records must contain all required fields.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-024']

## REQ-025. Work Item Model Must Include Required Fields
- **ID:** REQ-025
- **Title:** Work Item Model Must Include Required Fields
- **Description:** Each work item record must contain required fields such as id, status, priority.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-025']

## REQ-026. Preflight Output Schema Must Include Decision, Work Item ID, Priority, Requirement IDs, Test Case IDs, Confidence Target
- **ID:** REQ-026
- **Title:** Preflight Output Schema Must Include Decision, Work Item ID, Priority, Requirement IDs, Test Case IDs, Confidence Target
- **Description:** Structured preflight output must list these fields.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-026']

## REQ-027. Verification Input Must Include Diffs, Tests, Logs, and Changed Files
- **ID:** REQ-027
- **Title:** Verification Input Must Include Diffs, Tests, Logs, and Changed Files
- **Description:** Verification input must contain file diffs, test results, execution logs, and list of changed files.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-027']

## REQ-028. Retry Strategy Mapping Must Be Defined
- **ID:** REQ-028
- **Title:** Retry Strategy Mapping Must Be Defined
- **Description:** Retries map failures to strategies such as narrow_scope, expand_scope, fix_tests, rollback, and stop.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-028']

## REQ-029. Integration Adapter Interface Must Provide Required Capabilities
- **ID:** REQ-029
- **Title:** Integration Adapter Interface Must Provide Required Capabilities
- **Description:** Specsmith must provide filesystem and shell execution functions via the integration adapter.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-029']

## REQ-030. Specsmith CLI Commands Must Be Explicitly Defined
- **ID:** REQ-030
- **Title:** Specsmith CLI Commands Must Be Explicitly Defined
- **Description:** Specsmith CLI must expose commands such as preflight, verify, requirements list/show/accept/reject, tests generate/list, status, and ledger list.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-030']

## REQ-031. Sequencing Rules Must Enforce Valid States
- **ID:** REQ-031
- **Title:** Sequencing Rules Must Enforce Valid States
- **Description:** Bootstrap and sequence transitions must follow the defined order.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-031']

## REQ-032. Configuration Settings for Optional Features
- **ID:** REQ-032
- **Title:** Configuration Settings for Optional Features
- **Description:** Specsmith must read optional feature flags from .specsmith/config.yml.
- **Status:** implemented
- **Source:** .specsmith/config.yml, ARCHITECTURE.md
- **Test_Ids:** ['TEST-032']

## REQ-033. Default Enablement of Optional Features
- **ID:** REQ-033
- **Title:** Default Enablement of Optional Features
- **Description:** All optional Specsmith features must be enabled by default unless overridden.
- **Status:** implemented
- **Source:** .specsmith/config.yml, ARCHITECTURE.md
- **Test_Ids:** ['TEST-033']

## REQ-034. Evidence ZIP Archive Generation
- **ID:** REQ-034
- **Title:** Evidence ZIP Archive Generation
- **Description:** Specsmith must generate evidence ZIP archive for selected artifacts.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-034']

## REQ-035. Evidence Manifest Generation
- **ID:** REQ-035
- **Title:** Evidence Manifest Generation
- **Description:** Manifest must list artifacts and metadata in evidence archive.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-035']

## REQ-036. Per‑File SHA‑256 Hashing in Evidence
- **ID:** REQ-036
- **Title:** Per‑File SHA‑256 Hashing in Evidence
- **Description:** Every file in evidence archive must have a SHA‑256 hash.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-036']

## REQ-037. Final Evidence ZIP SHA‑256 Hash
- **ID:** REQ-037
- **Title:** Final Evidence ZIP SHA‑256 Hash
- **Description:** The final evidence ZIP archive must have a computed SHA‑256 hash.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-037']

## REQ-038. Author/Owner Metadata Capture
- **ID:** REQ-038
- **Title:** Author/Owner Metadata Capture
- **Description:** Evidence archive must record author/owner information for each artifact.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-038']

## REQ-039. Git Commit Metadata Inclusion
- **ID:** REQ-039
- **Title:** Git Commit Metadata Inclusion
- **Description:** Evidence archive must incorporate current git commit hash when available.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-039']

## REQ-040. Ledger Reference Inclusion
- **ID:** REQ-040
- **Title:** Ledger Reference Inclusion
- **Description:** Evidence archive must reference relevant ledger entries for traceability.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-040']

## REQ-041. Trusted Timestamp Token Support
- **ID:** REQ-041
- **Title:** Trusted Timestamp Token Support
- **Description:** Evidence archive may include an RFC 3161 trusted timestamp token if enabled.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-041']

## REQ-042. Legal/IP Disclaimer Requirement
- **ID:** REQ-042
- **Title:** Legal/IP Disclaimer Requirement
- **Description:** Specsmith must provide a disclaimer that evidence does not guarantee legal ownership.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-042']

## REQ-043. Ledger Event Hash Chaining
- **ID:** REQ-043
- **Title:** Ledger Event Hash Chaining
- **Description:** Each ledger event must be hashed and chained to previous event for tamper evidence.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-043']

## REQ-044. Ledger Event on Work Proposal
- **ID:** REQ-044
- **Title:** Ledger Event on Work Proposal
- **Description:** Specsmith must create ledger event when a work item is proposed.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-044']

## REQ-045. Ledger Event on Work Completion
- **ID:** REQ-045
- **Title:** Ledger Event on Work Completion
- **Description:** Specsmith must create ledger event upon completion of each work item or batch.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-045']

## REQ-046. README.md Generation and Synchronization
- **ID:** REQ-046
- **Title:** README.md Generation and Synchronization
- **Description:** Specsmith must generate README.md if missing and keep it synchronized.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-046']

## REQ-047. CHANGELOG.md Generation and Synchronization
- **ID:** REQ-047
- **Title:** CHANGELOG.md Generation and Synchronization
- **Description:** Specsmith must generate CHANGELOG.md following Keep a Changelog and keep it updated.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-047']

## REQ-048. Keep a Changelog Compliance
- **ID:** REQ-048
- **Title:** Keep a Changelog Compliance
- **Description:** CHANGELOG.md must follow Keep a Changelog format.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-048']

## REQ-049. Semantic Versioning Support
- **ID:** REQ-049
- **Title:** Semantic Versioning Support
- **Description:** Specsmith must understand and support Semantic Versioning for releases.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-049']

## REQ-050. Guided Version Bump Workflow
- **ID:** REQ-050
- **Title:** Guided Version Bump Workflow
- **Description:** Specsmith must provide a guided workflow for bumping version numbers.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-050']

## REQ-051. Guided Release Strategy Workflow
- **ID:** REQ-051
- **Title:** Guided Release Strategy Workflow
- **Description:** Specsmith must offer a guided workflow to determine release strategy.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-051']

## REQ-052. Guided Branching Strategy Workflow
- **ID:** REQ-052
- **Title:** Guided Branching Strategy Workflow
- **Description:** Specsmith must offer a guided workflow for selecting a branching strategy.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-052']

## REQ-053. Default GitFlow Branching Model
- **ID:** REQ-053
- **Title:** Default GitFlow Branching Model
- **Description:** Specsmith’s default branching model is GitFlow unless overridden.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-053']

## REQ-054. Guided Branching Modification
- **ID:** REQ-054
- **Title:** Guided Branching Modification
- **Description:** Specsmith must allow guided modifications to the branching model.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-054']

## REQ-055. GitHub License Generation
- **ID:** REQ-055
- **Title:** GitHub License Generation
- **Description:** Specsmith must generate license files compatible with GitHub/choosealicense.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-055']

## REQ-056. Commercial License Drafting Guidance
- **ID:** REQ-056
- **Title:** Commercial License Drafting Guidance
- **Description:** Specsmith must provide guidance for drafting commercial licenses, including disclaimer.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-056']

## REQ-057. Local Git Commit After Work
- **ID:** REQ-057
- **Title:** Local Git Commit After Work
- **Description:** Specsmith should commit local changes after each completed work item or batch.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-057']

## REQ-058. Confidence Threshold Configuration
- **ID:** REQ-058
- **Title:** Confidence Threshold Configuration
- **Description:** Specsmith must allow configuring epistemic confidence threshold via config file.
- **Status:** implemented
- **Source:** .specsmith/config.yml, ARCHITECTURE.md
- **Test_Ids:** ['TEST-058']

## REQ-059. Iteration Continuation Until Threshold
- **ID:** REQ-059
- **Title:** Iteration Continuation Until Threshold
- **Description:** Work iterations continue until epistemic confidence reaches threshold.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-059']

## REQ-060. Indefinite Iteration Default
- **ID:** REQ-060
- **Title:** Indefinite Iteration Default
- **Description:** Specsmith defaults to indefinite iteration unless user sets limits.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-060']

## REQ-061. Max Iterations Configuration
- **ID:** REQ-061
- **Title:** Max Iterations Configuration
- **Description:** Specsmith must allow configuring maximum iterations.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-061']

## REQ-062. Token/Cost/Time Limits Configuration
- **ID:** REQ-062
- **Title:** Token/Cost/Time Limits Configuration
- **Description:** Specsmith must allow configuring token spend, session cost, and elapsed time limits.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-062']

## REQ-063. Stop‑and‑Align Behavior
- **ID:** REQ-063
- **Title:** Stop‑and‑Align Behavior
- **Description:** Specsmith must stop when confidence cannot improve and engage user for alignment.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-063']

## REQ-064. Interactive Correction Workflow
- **ID:** REQ-064
- **Title:** Interactive Correction Workflow
- **Description:** After stopping, Specsmith should provide an interactive correction workflow.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-064']

## REQ-065. Nexus Runtime Must Not Own Governance
- **ID:** REQ-065
- **Title:** Nexus Runtime Must Not Own Governance
- **Description:** The Nexus agent runtime must defer preflight, requirement mapping, verification, retry decisions, and ledger writing to Specsmith.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-065']

## REQ-066. Nexus Must Provide Required Agent Roles
- **ID:** REQ-066
- **Title:** Nexus Must Provide Required Agent Roles
- **Description:** Nexus must instantiate PlannerAgent, ShellAgent, CodeAgent, ReviewerAgent, MemoryAgent, GitAgent, HumanProxyAgent, and an Executor node.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-066']

## REQ-067. Nexus Tool Layer Must Expose Required Tools
- **ID:** REQ-067
- **Title:** Nexus Tool Layer Must Expose Required Tools
- **Description:** Nexus must expose run_shell, read_file, write_file, patch_file, list_files, grep, git_diff, git_status, run_tests, open_url, search_docs, and remember_project_fact.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-067']

## REQ-068. Nexus Safety Middleware Must Block Unsafe Commands
- **ID:** REQ-068
- **Title:** Nexus Safety Middleware Must Block Unsafe Commands
- **Description:** The safety middleware must block or require explicit approval for unsafe shell patterns including rm -rf, git push, docker compose down -v, database migrations, deploy commands, and secret reads.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-068']

## REQ-069. Nexus Tool Arguments Must Be JSON Validated
- **ID:** REQ-069
- **Title:** Nexus Tool Arguments Must Be JSON Validated
- **Description:** All Nexus tool calls must validate that arguments are JSON-serializable before execution.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-069']

## REQ-070. Nexus Must Normalize File Paths
- **ID:** REQ-070
- **Title:** Nexus Must Normalize File Paths
- **Description:** All file paths supplied to Nexus tools must be normalized to absolute, resolved paths before access.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-070']

## REQ-071. Nexus Must Index the Repository
- **ID:** REQ-071
- **Title:** Nexus Must Index the Repository
- **Description:** Nexus must populate .repo-index/ with files.json, tags, test_commands.json, architecture.md, and conventions.md as available.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-071']

## REQ-072. Nexus REPL Must Support Slash Commands
- **ID:** REQ-072
- **Title:** Nexus REPL Must Support Slash Commands
- **Description:** The Nexus REPL must support /plan, /ask, /fix, /test, /commit, /pr, /undo, /context, /exit.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-072']

## REQ-073. Nexus Output Contract
- **ID:** REQ-073
- **Title:** Nexus Output Contract
- **Description:** Each Nexus task response must include sections Plan, Commands to run, Files changed, Diff, Test results, and Next action.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-073']

## REQ-074. vLLM Image Must Be Pinned
- **ID:** REQ-074
- **Title:** vLLM Image Must Be Pinned
- **Description:** The Nexus docker-compose.yml must pin the vLLM image to a specific tag (vllm/vllm-openai:v0.8.5) and not use latest.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-074']

## REQ-075. vLLM Must Serve l1-nexus Model
- **ID:** REQ-075
- **Title:** vLLM Must Serve l1-nexus Model
- **Description:** The Nexus docker-compose.yml must publish the served model as l1-nexus and use the Hermes tool-call parser.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-075']

## REQ-076. Nexus Tool Executor Registration Must Be Unique
- **ID:** REQ-076
- **Title:** Nexus Tool Executor Registration Must Be Unique
- **Description:** Each Nexus tool must be registered with the AG2 executor exactly once; LLM-side tool signatures may be attached to multiple caller agents but the execution function must not be re-registered to avoid AG2 override warnings.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-076']

## REQ-077. Safe Cleanup Must Default to Dry-Run
- **ID:** REQ-077
- **Title:** Safe Cleanup Must Default to Dry-Run
- **Description:** The Specsmith safe-cleanup capability must default to dry-run mode and only delete files when an explicit apply flag is provided.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-077']

## REQ-078. Safe Cleanup Must Use a Hard-Coded Target List
- **ID:** REQ-078
- **Title:** Safe Cleanup Must Use a Hard-Coded Target List
- **Description:** Safe cleanup must only consider the canonical built-in target list and must reject user-supplied arbitrary paths.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-078']

## REQ-079. Safe Cleanup Must Protect Governance and Source
- **ID:** REQ-079
- **Title:** Safe Cleanup Must Protect Governance and Source
- **Description:** Safe cleanup must refuse to delete .git, .specsmith, governance markdown files, pyproject.toml, README.md, LICENSE, CHANGELOG.md, src/, tests/, docs/, scripts/, .repo-index/, .github/, .vscode/, third-party agent integration directories (such as .agents/), and project configuration dotfiles.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-079']

## REQ-080. Safe Cleanup Must Emit a Structured Report
- **ID:** REQ-080
- **Title:** Safe Cleanup Must Emit a Structured Report
- **Description:** Safe cleanup must return a report containing the lists of removed paths, skipped paths with reasons, and total bytes reclaimed, suitable for inclusion as ledger evidence.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-080']

## REQ-081. Safe Cleanup Must Be Exposed via Specsmith CLI
- **ID:** REQ-081
- **Title:** Safe Cleanup Must Be Exposed via Specsmith CLI
- **Description:** The Specsmith CLI must expose the safe cleanup capability as `specsmith clean`, supporting `--apply`, `--json`, and `--project-dir`. When `--apply` is used and `LEDGER.md` exists, the run must be recorded as a `cleanup` ledger event tagged with REQ-077..REQ-080.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-081']

## REQ-082. CLI Console Must Be UTF-8 Safe Across Platforms
- **ID:** REQ-082
- **Title:** CLI Console Must Be UTF-8 Safe Across Platforms
- **Description:** All Specsmith CLI output (rich Console) must render UTF-8 glyphs (such as warning, arrow, check, cross) without raising UnicodeEncodeError on Windows code pages such as cp1252. The console factory must reconfigure stdout/stderr to UTF-8 and disable rich's legacy_windows renderer.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-082']

## REQ-083. Canonical Test Specification File Is TESTS.md
- **ID:** REQ-083
- **Title:** Canonical Test Specification File Is TESTS.md
- **Description:** The canonical test specification file is named `TESTS.md` (replacing the legacy names `TESTS.md`, `TEST-SPEC.md`, and `TEST-SPECS.md`). Specsmith code, governance documents, templates, scaffolder output, importer overlay, auditor checks, retrieval index, exporter, validator, REPL skill files, ReadTheDocs site, and CLI help must all reference `TESTS.md`. Legacy filenames must not be created by new scaffolds, must be auto-renamed by `specsmith migrate-project`, and must not be referenced in user-facing docs.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-083']

## REQ-084. Natural-Language Governance Broker
- **ID:** REQ-084
- **Title:** Natural-Language Governance Broker
- **Description:** Specsmith must expose a Nexus broker module (`specsmith.agent.broker`) that translates plain-language user utterances into Specsmith-governed work without the user reasoning about REQ IDs, TEST IDs, or work items. The broker must classify intent (read-only ask vs change vs release), infer affected scope from the local `.repo-index` and existing requirements, invoke `specsmith preflight` and `specsmith verify` as the only sources of governance decisions, render plain-language plans and outcomes, hide REQ/TEST/work-item IDs by default (revealed only on `/why`, `/show-governance`, or `--verbose`), bound retries per REQ-014, escalate to a single user clarification on stop-and-align (REQ-063), and never invent governance content (REQ/TEST drafting requires explicit user confirmation).
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-084']

## REQ-085. specsmith preflight CLI Subcommand
- **ID:** REQ-085
- **Title:** specsmith preflight CLI Subcommand
- **Description:** The Specsmith CLI must expose a `specsmith preflight <utterance>` subcommand that reads `REQUIREMENTS.md` and `.specsmith/` state, classifies intent and infers scope, and emits a JSON object with at least the keys `decision` (one of `accepted`, `needs_clarification`, `blocked`, `rejected`), `work_item_id`, `requirement_ids`, `test_case_ids`, `confidence_target`, and `instruction`. Read-only asks accept by default, destructive intents require clarification, and changes with no matching scope return `needs_clarification` with a one-sentence question. The CLI must support `--project-dir`, `--json`, and `--verbose`.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-085']

## REQ-086. Nexus REPL Must Gate Execution on Preflight Acceptance
- **ID:** REQ-086
- **Title:** Nexus REPL Must Gate Execution on Preflight Acceptance
- **Description:** When a non-slash utterance flows through the broker, the Nexus REPL must only invoke the AG2 orchestrator's `run_task` if the preflight decision is `accepted`. For any other decision (`needs_clarification`, `blocked`, `rejected`), the REPL must print the broker's plain-language clarification or rejection and return to the prompt without executing.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-086']

## REQ-087. Nexus REPL Must Drive Execution Through the Bounded-Retry Harness
- **ID:** REQ-087
- **Title:** Nexus REPL Must Drive Execution Through the Bounded-Retry Harness
- **Description:** When the preflight decision is `accepted`, the Nexus REPL must drive the AG2 orchestrator through `specsmith.agent.broker.execute_with_governance`, supplying an executor that wraps `orchestrator.run_task` and synthesizes a result dict (`equilibrium`, `confidence`, `summary`). The harness must honor `DEFAULT_RETRY_BUDGET` (REQ-014), surface the single clarifying question on stop-and-align (REQ-063), and never call `run_task` directly outside the harness.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-087']

## REQ-088. specsmith preflight Must Resolve Test Case IDs From Machine State
- **ID:** REQ-088
- **Title:** specsmith preflight Must Resolve Test Case IDs From Machine State
- **Description:** The `specsmith preflight` CLI must populate `test_case_ids` in its JSON payload by joining the matched `requirement_ids` against `.specsmith/testcases.json` (or `TESTS.md` when the JSON is unavailable). When the resolved set is non-empty the CLI must include every matching `TEST-NNN` id and must never invent ids not present in machine state.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-088']

## REQ-089. Nexus Live l1-nexus Smoke Test
- **ID:** REQ-089
- **Title:** Nexus Live l1-nexus Smoke Test
- **Description:** Specsmith must ship a `scripts/nexus_smoke.py` script that POSTs a minimal chat-completions request to a running vLLM `l1-nexus` container at `http://localhost:8000/v1/chat/completions` and reports whether the model responded with a well-formed `choices[0].message.content`. A pytest integration test must invoke the script and skip unless the environment variable `NEXUS_LIVE=1` is set, so the suite stays green offline but is verifiable when the container is up.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-089']

## REQ-090. Nexus Documentation Must Describe Broker, Preflight, and Gated Execution
- **ID:** REQ-090
- **Title:** Nexus Documentation Must Describe Broker, Preflight, and Gated Execution
- **Description:** `ARCHITECTURE.md`, `README.md`, and `docs/` must describe the natural-language broker (REQ-084), the `specsmith preflight` CLI (REQ-085), the REPL execution gate (REQ-086), and the bounded-retry harness (REQ-087), including the `/why` toggle and an end-to-end example flow. Documentation must not surface REQ/TEST/WI tokens to the user except inside the explicit `/why` block.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-090']

## REQ-091. Orchestrator Must Return a Structured TaskResult
- **ID:** REQ-091
- **Title:** Orchestrator Must Return a Structured TaskResult
- **Description:** `orchestrator.run_task` must return a `TaskResult` dataclass with at least the fields `equilibrium: bool`, `confidence: float`, `summary: str`, `files_changed: list[str]`, and `test_results: dict`. The Nexus REPL's broker branch must consume this dataclass directly when feeding `execute_with_governance` (REQ-087); the broker must not synthesize `equilibrium` from a boolean cast of the summary string.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-091']

## REQ-092. specsmith preflight CLI Must Use Decision-Specific Exit Codes
- **ID:** REQ-092
- **Title:** specsmith preflight CLI Must Use Decision-Specific Exit Codes
- **Description:** The `specsmith preflight` CLI must exit `0` for `accepted`, `2` for `needs_clarification`, and `3` for `blocked` or `rejected` decisions, so CI pipelines and shell wrappers can branch on intent without parsing the JSON payload. The JSON payload must continue to print on stdout for both success and non-zero exits.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-092']

## REQ-093. Accepted preflight Must Record a Ledger Event
- **ID:** REQ-093
- **Title:** Accepted preflight Must Record a Ledger Event
- **Description:** When `specsmith preflight` produces an `accepted` decision and `LEDGER.md` exists in the project root, the CLI must append a `preflight` ledger event tagged with `REQ-085` plus the resolved `requirement_ids`. The event must record the utterance, the assigned `work_item_id`, and the `confidence_target`, so every accepted preflight is traceable end-to-end.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-093']

## REQ-094. /why Must Surface Post-Run Governance in the REPL
- **ID:** REQ-094
- **Title:** /why Must Surface Post-Run Governance in the REPL
- **Description:** When `verbose_governance` is on (toggled by `/why` or `/show-governance`), after the REPL drives `execute_with_governance` for an accepted utterance it must print a single `[/why]` block summarizing the assigned `work_item_id`, the matched `requirement_ids` and `test_case_ids`, the post-run confidence, and whether the bounded-retry harness reached equilibrium. When verbose mode is off, the post-run governance block must not be emitted.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-094']

## REQ-095. Nexus Live Smoke Run Must Be Reproducible Evidence
- **ID:** REQ-095
- **Title:** Nexus Live Smoke Run Must Be Reproducible Evidence
- **Description:** A live or honestly-skipped invocation of `scripts/nexus_smoke.py` must be captured under `.specsmith/runs/WI-NEXUS-011/logs.txt` so the project ledger preserves at least one reproducible record of the broker -> preflight -> orchestrator -> vLLM end-to-end path (or a documented reason the live container could not be reached in the current environment).
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-095']

## REQ-096. Bounded-Retry Harness Must Map Failures to Retry Strategies
- **ID:** REQ-096
- **Title:** Bounded-Retry Harness Must Map Failures to Retry Strategies
- **Description:** When `execute_with_governance` exhausts its retry budget (REQ-014), it must classify the last executor report against the canonical retry strategy mapping (REQ-028): `narrow_scope`, `expand_scope`, `fix_tests`, `rollback`, or `stop`. The classification must be exposed on `RunResult.strategy` and surfaced in the clarifying question (REQ-063) so the user gets one concrete next-action label rather than only a free-form sentence.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-096']

## REQ-097. specsmith verify CLI Subcommand
- **ID:** REQ-097
- **Title:** specsmith verify CLI Subcommand
- **Description:** The Specsmith CLI must expose a `specsmith verify` subcommand that consumes the verification input contract (REQ-027): file diffs, test results, execution logs, and changed files (paths or `--stdin` JSON). The subcommand must emit a JSON object with at least `equilibrium`, `confidence`, `summary`, `files_changed`, `test_results`, and `retry_strategy`. Exit code 0 on equilibrium with confidence ≥ the configured threshold, 2 when retry is recommended, and 3 when stop-and-align is required.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-097']

## REQ-098. Confidence Threshold Must Be Read From .specsmith/config.yml
- **ID:** REQ-098
- **Title:** Confidence Threshold Must Be Read From .specsmith/config.yml
- **Description:** Both `specsmith preflight` and the broker's `run_preflight` helper must consult `.specsmith/config.yml` for the `epistemic.confidence_threshold` value (REQ-058) and use it as the floor for the JSON `confidence_target` field whenever it is greater than the heuristic default. When the config file is absent or unparseable, the existing heuristic defaults must continue to apply.
- **Status:** implemented
- **Source:** .specsmith/config.yml, ARCHITECTURE.md
- **Test_Ids:** ['TEST-098']

## REQ-099. Accepted Preflight Must Record a Distinct work_proposal Event
- **ID:** REQ-099
- **Title:** Accepted Preflight Must Record a Distinct work_proposal Event
- **Description:** When `specsmith preflight` produces an `accepted` decision and assigns a brand-new `work_item_id`, the CLI must append a `work_proposal` ledger event in addition to the existing `preflight` event (REQ-044). The `work_proposal` entry must reference REQ-044 and REQ-085, include the `work_item_id` and matched `requirement_ids`, and must NOT be emitted when the underlying `work_item_id` already appears in `LEDGER.md` (no duplicate proposals).
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-099']

## REQ-100. Broker Scope Inference May Surface Stress-Test Critical Failures
- **ID:** REQ-100
- **Title:** Broker Scope Inference May Surface Stress-Test Critical Failures
- **Description:** When the user passes `--stress` to `specsmith preflight` and the matched requirements set is non-empty, the CLI must invoke the existing AEE `StressTester` against those belief artifacts and surface any critical failures in the JSON payload as a `stress_warnings` list. The narration (verbose mode) must include a one-sentence plain-English warning when at least one critical failure is found. The flag must default off so unrelated tests continue to pass.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-100']

## REQ-101. Lint Baseline Must Be Clean
- **ID:** REQ-101
- **Title:** Lint Baseline Must Be Clean
- **Description:** `ruff check src/ tests/` and `ruff format --check src/ tests/` must both exit zero on `develop`. The lint job in `.github/workflows/ci.yml` enforces this contract. Per-file ignores in `pyproject.toml` are reserved for documentation modules whose long lines are intentional (e.g. `toolrules.py`, `tool_installer.py`).
- **Status:** implemented
- **Source:** .github/workflows/ci.yml, pyproject.toml
- **Test_Ids:** ['TEST-101']

## REQ-102. Type-Check Baseline Must Be Clean
- **ID:** REQ-102
- **Title:** Type-Check Baseline Must Be Clean
- **Description:** `mypy src/specsmith/` must exit zero on `develop`. Strict-mypy is preserved for the historically-typed modules; dynamically-typed modules in `specsmith.agent.*`, `specsmith.console_utils`, `specsmith.serve`, and the agent-orchestrator surface are explicitly enumerated in the `[[tool.mypy.overrides]]` `ignore_errors=true` block of `pyproject.toml` until they are individually annotated.
- **Status:** implemented
- **Source:** .github/workflows/ci.yml, pyproject.toml
- **Test_Ids:** ['TEST-102']

## REQ-103. Security Baseline Tolerates Unfixed pip Advisory
- **ID:** REQ-103
- **Title:** Security Baseline Tolerates Unfixed pip Advisory
- **Description:** The CI security job must upgrade pip to the latest release before invoking `pip-audit`, and must pass the `--ignore-vuln CVE-2026-3219` flag for the unfixed pip advisory so the runner's own pip version does not block PRs. Specsmith's actual runtime dependencies (click, jinja2, pyyaml, pydantic, rich) must remain pip-audit clean; any new advisory against them must trigger a dependency bump rather than another ignore-flag.
- **Status:** implemented
- **Source:** .github/workflows/ci.yml
- **Test_Ids:** ['TEST-103']

## REQ-104. Work Items Must Mirror Implemented REQs
- **ID:** REQ-104
- **Title:** Work Items Must Mirror Implemented REQs
- **Description:** `.specsmith/workitems.json` must derive from `.specsmith/requirements.json` and `.specsmith/testcases.json`. For each REQ-N there must be a matching WORK-N entry with `requirement_id=REQ-N`, `test_case_ids` listing every TEST joined by `requirement_id`, and `status=complete` when the REQ is implemented in source. The `scripts/sync_workitems.py` helper is the canonical sync.
- **Status:** implemented
- **Source:** scripts/sync_workitems.py, .specsmith/workitems.json
- **Test_Ids:** ['TEST-104']

## REQ-105. Live Smoke Evidence Must Be Reproducible Or Honestly Skipped
- **ID:** REQ-105
- **Title:** Live Smoke Evidence Must Be Reproducible Or Honestly Skipped
- **Description:** A live or honestly-skipped invocation of `scripts/nexus_smoke.py` against the configured `l1-nexus` model must be captured under `.specsmith/runs/WI-NEXUS-011/logs.txt`. The skip note must include a fresh probe attempt, a timestamp, and the hardware/environment reason the live container could not be reached.
- **Status:** implemented
- **Source:** .specsmith/runs/WI-NEXUS-011/logs.txt, scripts/nexus_smoke.py
- **Test_Ids:** ['TEST-105']

## REQ-106. Kairos Must Surface Governance Commands
- **ID:** REQ-106
- **Title:** Kairos Must Surface Governance Commands
- **Description:** The Kairos terminal client must provide UI access to the three primary governance operations: preflight gate, verify, and governance trace (`/why`). These are surfaced via the Governance settings page and the BYOE proxy at `http://127.0.0.1:7700`.
- **Status:** implemented
- **Source:** app/src/settings_view/governance_page.rs, kairos_governance crate
- **Test_Ids:** ['TEST-106']

## REQ-107. ARCHITECTURE.md Must Reflect Current State
- **ID:** REQ-107
- **Title:** ARCHITECTURE.md Must Reflect Current State
- **Description:** `ARCHITECTURE.md` must contain a 'Current State' section listing the realized broker, harness, retry strategies, CI baseline, Kairos governance integration, live-smoke evidence note, and documentation surface. The section is the source of truth for 'the system as built' and must be updated each time a release is cut.
- **Status:** implemented
- **Source:** ARCHITECTURE.md
- **Test_Ids:** ['TEST-107']

## REQ-108. Real Verifier Signal Must Drive Confidence
- **ID:** REQ-108
- **Title:** Real Verifier Signal Must Drive Confidence
- **Description:** `Orchestrator._build_task_result` must derive `TaskResult.confidence` and `equilibrium` from a real verifier (`src/specsmith/agent/verifier.py`) that inspects test results, ruff output, and mypy output for the changed files. The hardcoded 0.85 / 0.4 / 0.0 placeholder must be removed.
- **Status:** implemented
- **Source:** src/specsmith/agent/verifier.py, src/specsmith/agent/orchestrator.py
- **Test_Ids:** ['TEST-108']

## REQ-109. Live `l1-nexus` Smoke Overlay Must Produce ok=true on 7B Hardware
- **ID:** REQ-109
- **Title:** Live `l1-nexus` Smoke Overlay Must Produce ok=true on 7B Hardware
- **Description:** Specsmith ships a `docker-compose.smoke.yml` overlay that swaps `l1-nexus` to a 7B GPTQ-Int4 model fitting <=8 GB VRAM, and `.specsmith/runs/WI-NEXUS-029/logs.txt` documents how to capture an `ok: true` smoke result with `NEXUS_LIVE=1` against that overlay.
- **Status:** implemented
- **Source:** docker-compose.smoke.yml, .specsmith/runs/WI-NEXUS-029/logs.txt
- **Test_Ids:** ['TEST-109']

## REQ-110. End-to-End Nexus Path Must Be Integration-Tested
- **ID:** REQ-110
- **Title:** End-to-End Nexus Path Must Be Integration-Tested
- **Description:** `tests/test_e2e_nexus.py` exercises the broker -> preflight -> harness -> orchestrator -> verifier path with a `FakeOrchestrator` and asserts ledger events, `RunResult.success`, and retry-strategy classification on a scripted failure-then-recovery sequence.
- **Status:** implemented
- **Source:** tests/test_e2e_nexus.py
- **Test_Ids:** ['TEST-110']

## REQ-111. Mypy Strict Carveout Must Shrink Toward Zero
- **ID:** REQ-111
- **Title:** Mypy Strict Carveout Must Shrink Toward Zero
- **Description:** At least the four newly-annotated dynamic agent modules (`broker`, `safety`, `console_utils`, `indexer`) are fully type-annotated and removed from the `[[tool.mypy.overrides]] ignore_errors=true` block in `pyproject.toml`. The remaining carveout (orchestrator, repl, tools, cleanup, serve) is documented as a 1.x cleanup target.
- **Status:** implemented
- **Source:** pyproject.toml, src/specsmith/agent/*.py, src/specsmith/console_utils.py
- **Test_Ids:** ['TEST-111']

## REQ-112. Streaming Token Bridge Must Emit JSONL Events
- **ID:** REQ-112
- **Title:** Streaming Token Bridge Must Emit JSONL Events
- **Description:** A new `specsmith chat <utterance> --json-events` CLI subcommand drives the broker + harness end-to-end and emits a JSONL event stream on stdout with at least the event types `block_start`, `token`, `tool_call`, `tool_result`, `block_complete`, and `task_complete`. Each event is a single JSON object on its own line.
- **Status:** implemented
- **Source:** src/specsmith/cli.py, src/specsmith/agent/events.py
- **Test_Ids:** ['TEST-112']

## REQ-113. Block-Based Output Schema
- **ID:** REQ-113
- **Title:** Block-Based Output Schema
- **Description:** Every `block_start` event carries a `block_id`, `kind` (one of `plan`, `message`, `tool_call`, `tool_result`, `diff`, `test_results`, `verdict`), `agent`, and `timestamp`. The corresponding `block_complete` reuses the same `block_id`. Schema is documented in `docs/site/chat-events.md`.
- **Status:** implemented
- **Source:** src/specsmith/agent/events.py, docs/site/chat-events.md
- **Test_Ids:** ['TEST-113']

## REQ-114. Plan Block Must Surface Steps
- **ID:** REQ-114
- **Title:** Plan Block Must Surface Steps
- **Description:** When the broker classifies an utterance as a `change` and preflight is `accepted`, the chat stream must emit a `plan` block whose payload is a list of `{step_id, title, status}` items. Status transitions (`pending` -> `running` -> `done` / `failed`) are emitted as `plan_step` events keyed by `step_id`.
- **Status:** implemented
- **Source:** src/specsmith/agent/events.py
- **Test_Ids:** ['TEST-114']

## REQ-115. Permission/Autonomy Tier Must Be Honored End-to-End
- **ID:** REQ-115
- **Title:** Permission/Autonomy Tier Must Be Honored End-to-End
- **Description:** `specsmith chat` accepts `--profile {safe,standard,open,admin}` (default reads `scaffold.yml`). Under `safe`, every tool call emits a `tool_request` event and waits for an inbound `tool_decision` line on stdin (`{decision: 'approve'|'deny'}`). Under `standard` / `open` the harness proceeds without prompting. The selected profile is recorded in the ledger entry.
- **Status:** implemented
- **Source:** src/specsmith/cli.py, src/specsmith/profiles.py
- **Test_Ids:** ['TEST-115']

## REQ-116. Inline Diff Review Must Round-Trip Comments
- **ID:** REQ-116
- **Title:** Inline Diff Review Must Round-Trip Comments
- **Description:** `specsmith chat` emits a `diff` block per file changed by the orchestrator; subsequent stdin lines of the form `{type: 'comment', block_id, path, line, body}` are stored in the session memory and surfaced to the bounded-retry harness as additional context on the next attempt. `--comment` flag on `specsmith verify` does the equivalent for non-streaming use.
- **Status:** implemented
- **Source:** src/specsmith/agent/events.py, src/specsmith/cli.py
- **Test_Ids:** ['TEST-116']

## REQ-117. Predict-Only Preflight Must Not Allocate a Work Item
- **ID:** REQ-117
- **Title:** Predict-Only Preflight Must Not Allocate a Work Item
- **Description:** `specsmith preflight <utterance> --predict-only --json` returns the same JSON shape as the canonical `preflight` (intent, requirement_ids, instruction, etc.) but with `work_item_id == ''`, no ledger event written, and a new `predicted_refinement` field that suggests a tightened utterance. Used by IDE autocomplete.
- **Status:** implemented
- **Source:** src/specsmith/cli.py
- **Test_Ids:** ['TEST-117']

## REQ-118. Kairos Must Surface specsmith chat Stream
- **ID:** REQ-118
- **Title:** Kairos Must Surface specsmith chat Stream
- **Description:** The Kairos governance proxy (`/v1/chat/completions`) consumes the `specsmith chat --json-events` JSONL stream and exposes it to the agent session.
- **Status:** implemented
- **Source:** app/src/settings_view/governance_page.rs, kairos_governance crate
- **Test_Ids:** ['TEST-118']

## REQ-119. Project Rules Must Auto-Inject Into the System Prompt
- **ID:** REQ-119
- **Title:** Project Rules Must Auto-Inject Into the System Prompt
- **Description:** `src/specsmith/agent/rules.py:load_rules(project_dir)` reads `docs/governance/*_RULES.md` and the H-rules from `AGENTS.md`, returning a single deterministic system-prompt prefix string. The orchestrator prepends this string to every AG2 agent's `system_message` at construction time.
- **Status:** implemented
- **Source:** src/specsmith/agent/rules.py, src/specsmith/agent/orchestrator.py
- **Test_Ids:** ['TEST-119']

## REQ-120. Persistent Session Memory Must Be Token-Budgeted
- **ID:** REQ-120
- **Title:** Persistent Session Memory Must Be Token-Budgeted
- **Description:** `src/specsmith/agent/memory.py` provides `append_turn(session_id, turn)` and `recent_turns(session_id, max_chars)` that read/write `.specsmith/sessions/<session_id>/turns.jsonl`. `specsmith chat --session-id <id>` injects the most recent N turns (within `max_chars`) into the orchestrator's first message.
- **Status:** implemented
- **Source:** src/specsmith/agent/memory.py
- **Test_Ids:** ['TEST-120']

## REQ-121. MCP Tool Consumption Must Be Configuration-Driven
- **ID:** REQ-121
- **Title:** MCP Tool Consumption Must Be Configuration-Driven
- **Description:** `src/specsmith/agent/mcp.py:load_mcp_tools(project_dir)` reads `.specsmith/mcp.yml` (a list of `{name, command, args, env}` entries) and returns Nexus-tool wrappers that proxy to each external MCP server via stdio. The Specsmith safety middleware wraps every MCP tool call.
- **Status:** implemented
- **Source:** src/specsmith/agent/mcp.py, .specsmith/mcp.yml
- **Test_Ids:** ['TEST-121']

## REQ-122. Dynamic Agent/Model Routing Must Be Pluggable
- **ID:** REQ-122
- **Title:** Dynamic Agent/Model Routing Must Be Pluggable
- **Description:** `src/specsmith/agent/router.py:choose_tier(intent, scope, retry_count)` returns one of `{coder, heavy, fast}` based on `.specsmith/config.yml routing:` overrides. The orchestrator builds a model-config map keyed by tier and selects the appropriate `llm_config` per agent.
- **Status:** implemented
- **Source:** src/specsmith/agent/router.py, .specsmith/config.yml
- **Test_Ids:** ['TEST-122']

## REQ-123. Notebook Capture and Replay
- **ID:** REQ-123
- **Title:** Notebook Capture and Replay
- **Description:** `specsmith notebook record --session-id <id> --slug <name>` writes `docs/notebooks/<slug>.md` with the captured turns; `specsmith notebook replay <slug>` re-runs each utterance through `specsmith chat` (using the recorded `--profile`), re-checking governance gates.
- **Status:** implemented
- **Source:** src/specsmith/cli.py, docs/notebooks/
- **Test_Ids:** ['TEST-123']

## REQ-124. Performance Baseline Must Be Measured and Tracked
- **ID:** REQ-124
- **Title:** Performance Baseline Must Be Measured and Tracked
- **Description:** `scripts/perf_smoke.py` synthesizes a 1000-REQ `REQUIREMENTS.md` in tmp_path, runs `specsmith preflight` 50 times, and writes p50 / p95 / p99 to `.specsmith/perf/baseline.json`. CI reports the deltas vs the committed baseline as a non-blocking warning.
- **Status:** implemented
- **Source:** scripts/perf_smoke.py, .specsmith/perf/baseline.json
- **Test_Ids:** ['TEST-124']

## REQ-125. Multi-Session Parallel Agents
- **ID:** REQ-125
- **Title:** Multi-Session Parallel Agents
- **Description:** `specsmith chat` accepts `--parent-session <id>`. When set, the spawned session's `task_complete` event also writes a `sub_session_complete` event into the parent's session log so the parent's plan-block can surface child outcomes.
- **Status:** implemented
- **Source:** src/specsmith/cli.py, src/specsmith/agent/memory.py
- **Test_Ids:** ['TEST-125']

## REQ-127. Onboarding Path Must Be Verified
- **ID:** REQ-127
- **Title:** Onboarding Path Must Be Verified
- **Description:** `specsmith doctor --onboarding` prints a checklist (CLI installed, env activated, scaffold.yml present, REQUIREMENTS.md present, vLLM endpoint reachable, ledger present) and exits non-zero if any required item is missing. `docs/site/getting-started.md` walks a fresh user from install to first accepted preflight.
- **Status:** implemented
- **Source:** src/specsmith/doctor.py, src/specsmith/cli.py, docs/site/getting-started.md
- **Test_Ids:** ['TEST-127']

## REQ-128. Cross-Repo Security Sweep
- **ID:** REQ-128
- **Title:** Cross-Repo Security Sweep
- **Description:** The specsmith and kairos repos both run `pip-audit` / `cargo audit` in CI and fail on high-or-critical findings. Dependabot manifests in both repos are reviewed and any open alert at 1.0 release time is documented.
- **Status:** implemented
- **Source:** .github/workflows/ci.yml, BitConcepts/kairos/.github/workflows/ci.yml
- **Test_Ids:** ['TEST-128']

## REQ-129. 1.0 API Stability Commitment
- **ID:** REQ-129
- **Title:** 1.0 API Stability Commitment
- **Description:** `docs/site/api-stability.md` enumerates the public surfaces frozen at 1.0 (CLI subcommands and exit codes, JSON payload schemas for preflight / verify / chat events, broker module API, ledger event schemas, Kairos CLI API surface). The PyPI classifier is bumped to `Development Status :: 5 - Production/Stable` and `pyproject.toml` to `1.0.0`.
- **Status:** implemented
- **Source:** docs/site/api-stability.md, pyproject.toml
- **Test_Ids:** ['TEST-129']

## REQ-130. Typed ProjectOperations Layer
- **ID:** REQ-130
- **Title:** Typed ProjectOperations Layer
- **Description:** All tool handlers MUST use a typed `ProjectOperations` class for file, git/VCS, and search operations. Direct raw shell string assembly in tool handlers is prohibited.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (OPS-001)
- **Test_Ids:** ['TEST-130']

## REQ-131. ProjectOperations File Operations via pathlib
- **ID:** REQ-131
- **Title:** ProjectOperations File Operations via pathlib
- **Description:** `ProjectOperations` MUST expose file operations (`read_file`, `write_file`, `list_dir`, `glob`, `search`) implemented via Python `pathlib`/`stdlib` — no subprocess calls.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (OPS-002)
- **Test_Ids:** ['TEST-131']

## REQ-132. ProjectOperations Git/VCS Operations
- **ID:** REQ-132
- **Title:** ProjectOperations Git/VCS Operations
- **Description:** `ProjectOperations` MUST expose git/VCS operations (`status`, `log`, `diff`, `add`, `commit`, `push`, `create_branch`, `create_pr`) returning structured result objects.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (OPS-003)
- **Test_Ids:** ['TEST-132']

## REQ-133. ProjectOperations Typed Result Objects
- **ID:** REQ-133
- **Title:** ProjectOperations Typed Result Objects
- **Description:** All `ProjectOperations` methods MUST return a typed result containing at minimum `exit_code`, `stdout`, `stderr`, and `elapsed_ms`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (OPS-004)
- **Test_Ids:** ['TEST-133']

## REQ-134. executor.py run_tracked Preserved as Narrow Fallback
- **ID:** REQ-134
- **Title:** executor.py run_tracked Preserved as Narrow Fallback
- **Description:** The existing `executor.py` `run_tracked()` function MUST be preserved as a narrow fallback for commands that have no Python equivalent.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (OPS-005)
- **Test_Ids:** ['TEST-134']

## REQ-135. ProjectOperations Cross-Platform
- **ID:** REQ-135
- **Title:** ProjectOperations Cross-Platform
- **Description:** `ProjectOperations` MUST be cross-platform (Windows, Linux, macOS) without platform-specific code branches in call sites.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (OPS-006)
- **Test_Ids:** ['TEST-135']

## REQ-136. Harness Slash Commands Package
- **ID:** REQ-136
- **Title:** Harness Slash Commands Package
- **Description:** The `commands/` package MUST implement all priority harness slash commands available inside `specsmith run`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (CMD-001)
- **Test_Ids:** ['TEST-136']

## REQ-137. Session Management Slash Commands
- **ID:** REQ-137
- **Title:** Session Management Slash Commands
- **Description:** Session management commands MUST include: `/model`, `/provider`, `/tier`, `/status`, `/save`, `/clear`, `/compact`, `/export`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (CMD-002)
- **Test_Ids:** ['TEST-137']

## REQ-138. Multi-Agent Slash Commands
- **ID:** REQ-138
- **Title:** Multi-Agent Slash Commands
- **Description:** Multi-agent commands MUST include: `/spawn`, `/team`, `/team-status`, `/worktree`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (CMD-003)
- **Test_Ids:** ['TEST-138']

## REQ-139. Continuous Learning Slash Commands
- **ID:** REQ-139
- **Title:** Continuous Learning Slash Commands
- **Description:** Continuous learning commands MUST include: `/learn`, `/learn-eval`, `/instinct-status`, `/instinct-import`, `/instinct-export`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (CMD-004)
- **Test_Ids:** ['TEST-139']

## REQ-140. Evaluation Slash Commands
- **ID:** REQ-140
- **Title:** Evaluation Slash Commands
- **Description:** Evaluation commands MUST include: `/eval define`, `/eval run`, `/eval report`, `/eval compare`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (CMD-005)
- **Test_Ids:** ['TEST-140']

## REQ-141. Orchestration Slash Commands
- **ID:** REQ-141
- **Title:** Orchestration Slash Commands
- **Description:** Orchestration commands MUST include: `/multi-plan`, `/multi-execute`, `/route`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (CMD-006)
- **Test_Ids:** ['TEST-141']

## REQ-142. Hook Control Slash Commands
- **ID:** REQ-142
- **Title:** Hook Control Slash Commands
- **Description:** Hook control commands MUST include: `/hooks-enable`, `/hooks-disable`, `/hook-profile`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (CMD-007)
- **Test_Ids:** ['TEST-142']

## REQ-143. MCP Slash Commands
- **ID:** REQ-143
- **Title:** MCP Slash Commands
- **Description:** MCP commands MUST include: `/mcp-list`, `/mcp-add`, `/mcp-configure`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (CMD-008)
- **Test_Ids:** ['TEST-143']

## REQ-144. Security Slash Commands
- **ID:** REQ-144
- **Title:** Security Slash Commands
- **Description:** Security commands MUST include: `/security-scan`, `/audit-prompt`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (CMD-009)
- **Test_Ids:** ['TEST-144']

## REQ-145. AgentTool for Subagent Spawning
- **ID:** REQ-145
- **Title:** AgentTool for Subagent Spawning
- **Description:** The runner MUST provide an `AgentTool` (TaskTool) as a native LLM-callable tool that spawns subagent instances.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MAS-001)
- **Test_Ids:** ['TEST-145']

## REQ-146. Hub-and-Spoke and Agent-Teams Coordination
- **ID:** REQ-146
- **Title:** Hub-and-Spoke and Agent-Teams Coordination
- **Description:** Subagent spawning MUST support hub-and-spoke and agent-teams (peer-to-peer via filesystem mailbox) coordination modes.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MAS-002)
- **Test_Ids:** ['TEST-146']

## REQ-147. Filesystem Mailbox for Agent Teams
- **ID:** REQ-147
- **Title:** Filesystem Mailbox for Agent Teams
- **Description:** The filesystem mailbox for agent teams MUST be stored at `.specsmith/teams/{team}/mailbox/{agent}.json`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MAS-003)
- **Test_Ids:** ['TEST-147']

## REQ-148. Git Worktree Isolation for Subagents
- **ID:** REQ-148
- **Title:** Git Worktree Isolation for Subagents
- **Description:** When `isolation=worktree`, the spawner MUST create a git worktree at `.specsmith/worktrees/{agent_id}/`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MAS-004)
- **Test_Ids:** ['TEST-148']

## REQ-149. No Recursive Subagent Nesting
- **ID:** REQ-149
- **Title:** No Recursive Subagent Nesting
- **Description:** Subagents MUST NOT be able to spawn further subagents (no recursive nesting).
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MAS-005)
- **Test_Ids:** ['TEST-149']

## REQ-150. Distilled Summary from Subagents
- **ID:** REQ-150
- **Title:** Distilled Summary from Subagents
- **Description:** The parent agent MUST receive a distilled summary from each subagent on completion, not the full transcript.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MAS-006)
- **Test_Ids:** ['TEST-150']

## REQ-151. Agent Teams Feature Flag Gated
- **ID:** REQ-151
- **Title:** Agent Teams Feature Flag Gated
- **Description:** Agent team mode MUST be gated behind a feature flag (`SPECSMITH_AGENT_TEAMS=1`).
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MAS-007)
- **Test_Ids:** ['TEST-151']

## REQ-152. Orchestrator Meta-Agent for Routing
- **ID:** REQ-152
- **Title:** Orchestrator Meta-Agent for Routing
- **Description:** specsmith MUST provide an orchestrator meta-agent for task classification, routing, and optimization — not execution.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (ORC-001)
- **Test_Ids:** ['TEST-152']

## REQ-153. Orchestrator Defaults to Local Ollama
- **ID:** REQ-153
- **Title:** Orchestrator Defaults to Local Ollama
- **Description:** The orchestrator MUST default to a small local Ollama model so orchestration incurs zero cloud API cost.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (ORC-002)
- **Test_Ids:** ['TEST-153']

## REQ-154. Agent Registry with Capability Metadata
- **ID:** REQ-154
- **Title:** Agent Registry with Capability Metadata
- **Description:** The orchestrator MUST maintain an agent registry with type, model, provider, cost_tier, capabilities, avg_latency_ms, confidence.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (ORC-003)
- **Test_Ids:** ['TEST-154']

## REQ-155. Orchestrator Emits One Structured Next-Action
- **ID:** REQ-155
- **Title:** Orchestrator Emits One Structured Next-Action
- **Description:** The orchestrator MUST emit exactly one structured next-action per task.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (ORC-004)
- **Test_Ids:** ['TEST-155']

## REQ-156. Cost-Aware Routing
- **ID:** REQ-156
- **Title:** Cost-Aware Routing
- **Description:** The orchestrator MUST route cheap tasks to Ollama workers and complex tasks to cloud providers.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (ORC-005)
- **Test_Ids:** ['TEST-156']

## REQ-157. Post-Session Self-Evaluation for Routing Thresholds
- **ID:** REQ-157
- **Title:** Post-Session Self-Evaluation for Routing Thresholds
- **Description:** The orchestrator MUST run a post-session self-evaluation to update routing thresholds.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (ORC-006)
- **Test_Ids:** ['TEST-157']

## REQ-158. Feature Flag System for Tool Schema Visibility
- **ID:** REQ-158
- **Title:** Feature Flag System for Tool Schema Visibility
- **Description:** specsmith MUST implement a feature-flag system controlling which tool schemas are sent to the LLM.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (FLG-001)
- **Test_Ids:** ['TEST-158']

## REQ-159. Feature Flags via Environment and scaffold.yml
- **ID:** REQ-159
- **Title:** Feature Flags via Environment and scaffold.yml
- **Description:** Feature flags MUST be configurable via environment variables and `scaffold.yml` under `agent.flags`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (FLG-002)
- **Test_Ids:** ['TEST-159']

## REQ-160. Agent Teams and Advanced Features Flag-Gated
- **ID:** REQ-160
- **Title:** Agent Teams and Advanced Features Flag-Gated
- **Description:** Agent teams, worktree isolation, KAIROS daemon mode, security scanner, and MCP tools MUST be flag-gated.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (FLG-003)
- **Test_Ids:** ['TEST-160']

## REQ-161. Instinct Persistence System
- **ID:** REQ-161
- **Title:** Instinct Persistence System
- **Description:** specsmith MUST implement an instinct persistence system in `src/specsmith/instinct.py`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (LRN-001)
- **Test_Ids:** ['TEST-161']

## REQ-162. Instinct Record Schema
- **ID:** REQ-162
- **Title:** Instinct Record Schema
- **Description:** Each instinct record MUST contain: id, trigger_pattern, content, confidence, project_scope, created, last_used, use_count.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (LRN-002)
- **Test_Ids:** ['TEST-162']

## REQ-163. SESSION_END Hook Extracts Candidate Instincts
- **ID:** REQ-163
- **Title:** SESSION_END Hook Extracts Candidate Instincts
- **Description:** The `SESSION_END` hook MUST extract candidate instincts for user review.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (LRN-003)
- **Test_Ids:** ['TEST-163']

## REQ-164. /learn Command Promotes Pattern to Instinct
- **ID:** REQ-164
- **Title:** /learn Command Promotes Pattern to Instinct
- **Description:** The `/learn` command MUST promote a pattern to an instinct with an initial confidence score.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (LRN-004)
- **Test_Ids:** ['TEST-164']

## REQ-165. Instinct Confidence Updated on Application
- **ID:** REQ-165
- **Title:** Instinct Confidence Updated on Application
- **Description:** Instinct confidence MUST be updated based on application success/rejection.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (LRN-005)
- **Test_Ids:** ['TEST-165']

## REQ-166. Instincts Importable and Exportable as Markdown
- **ID:** REQ-166
- **Title:** Instincts Importable and Exportable as Markdown
- **Description:** Instincts MUST be importable and exportable as `.md` files.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (LRN-006)
- **Test_Ids:** ['TEST-166']

## REQ-167. /instinct-status Displays Active Instincts
- **ID:** REQ-167
- **Title:** /instinct-status Displays Active Instincts
- **Description:** `/instinct-status` MUST display all active instincts sorted by confidence.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (LRN-007)
- **Test_Ids:** ['TEST-167']

## REQ-168. Eval Harness Module
- **ID:** REQ-168
- **Title:** Eval Harness Module
- **Description:** specsmith MUST implement an eval harness in `src/specsmith/eval/`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (EDD-001)
- **Test_Ids:** ['TEST-168']

## REQ-169. Eval Data Model
- **ID:** REQ-169
- **Title:** Eval Data Model
- **Description:** The eval model MUST define: Task, Trial, Grader, Transcript, Outcome.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (EDD-002)
- **Test_Ids:** ['TEST-169']

## REQ-170. Eval Tasks Stored as Markdown
- **ID:** REQ-170
- **Title:** Eval Tasks Stored as Markdown
- **Description:** Tasks MUST be stored as Markdown at `.specsmith/evals/{feature}.md` with YAML frontmatter.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (EDD-003)
- **Test_Ids:** ['TEST-170']

## REQ-171. Three Grader Types
- **ID:** REQ-171
- **Title:** Three Grader Types
- **Description:** The harness MUST support CodeGrader, ModelGrader, and HumanFlag grader types.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (EDD-004)
- **Test_Ids:** ['TEST-171']

## REQ-172. pass@k and pass^k Metrics
- **ID:** REQ-172
- **Title:** pass@k and pass^k Metrics
- **Description:** The harness MUST compute `pass@k` and `pass^k` metrics.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (EDD-005)
- **Test_Ids:** ['TEST-172']

## REQ-173. Git-Based Outcome Grading by Default
- **ID:** REQ-173
- **Title:** Git-Based Outcome Grading by Default
- **Description:** Default grading MUST be git-based outcome grading, not execution-path assertion.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (EDD-006)
- **Test_Ids:** ['TEST-173']

## REQ-174. /eval run --trials k
- **ID:** REQ-174
- **Title:** /eval run --trials k
- **Description:** `/eval run --trials k` MUST run k independent trials and report results.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (EDD-007)
- **Test_Ids:** ['TEST-174']

## REQ-175. Capability vs Regression Eval Distinction
- **ID:** REQ-175
- **Title:** Capability vs Regression Eval Distinction
- **Description:** The harness MUST distinguish capability evals from regression evals.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (EDD-008)
- **Test_Ids:** ['TEST-175']

## REQ-176. Cross-Session Agent Memory
- **ID:** REQ-176
- **Title:** Cross-Session Agent Memory
- **Description:** specsmith MUST implement cross-session agent memory in `src/specsmith/memory.py`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MEM-001)
- **Test_Ids:** ['TEST-176']

## REQ-177. Agent Memory Structured JSON
- **ID:** REQ-177
- **Title:** Agent Memory Structured JSON
- **Description:** Agent memory MUST be structured JSON with accumulated patterns, preferred approaches, known project facts, and failure history.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MEM-002)
- **Test_Ids:** ['TEST-177']

## REQ-178. SESSION_START Hook Injects Memories into System Prompt
- **ID:** REQ-178
- **Title:** SESSION_START Hook Injects Memories into System Prompt
- **Description:** The `SESSION_START` hook MUST inject relevant memories into the system prompt (token-budget-aware).
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MEM-003)
- **Test_Ids:** ['TEST-178']

## REQ-179. Agent Memory Compatible with Theia AI Convention
- **ID:** REQ-179
- **Title:** Agent Memory Compatible with Theia AI Convention
- **Description:** Agent memory layout MUST be compatible with Theia AI's `~/.theia/agent-memory/` convention.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MEM-004)
- **Test_Ids:** ['TEST-179']

## REQ-180. Runtime Hook Enable/Disable
- **ID:** REQ-180
- **Title:** Runtime Hook Enable/Disable
- **Description:** Hooks MUST be enable/disable-able at runtime without restarting the session.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (HRK-001)
- **Test_Ids:** ['TEST-180']

## REQ-181. Hook Profiles via /hook-profile
- **ID:** REQ-181
- **Title:** Hook Profiles via /hook-profile
- **Description:** Hook profiles MUST be loadable via `/hook-profile`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (HRK-002)
- **Test_Ids:** ['TEST-181']

## REQ-182. New Hook Trigger Events
- **ID:** REQ-182
- **Title:** New Hook Trigger Events
- **Description:** New triggers: `SUBAGENT_START`, `SUBAGENT_STOP`, `CONTEXT_COMPACT`, `EVAL_PASS`, `EVAL_FAIL`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (HRK-003)
- **Test_Ids:** ['TEST-182']

## REQ-183. SUBAGENT_START Hook Can Block Spawn
- **ID:** REQ-183
- **Title:** SUBAGENT_START Hook Can Block Spawn
- **Description:** `SUBAGENT_START` MUST fire before spawning; a hook MAY block the spawn.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (HRK-004)
- **Test_Ids:** ['TEST-183']

## REQ-184. SUBAGENT_STOP Hook on Completion
- **ID:** REQ-184
- **Title:** SUBAGENT_STOP Hook on Completion
- **Description:** `SUBAGENT_STOP` MUST fire when a subagent completes.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (HRK-005)
- **Test_Ids:** ['TEST-184']

## REQ-185. CONTEXT_COMPACT Hook Before Trimming
- **ID:** REQ-185
- **Title:** CONTEXT_COMPACT Hook Before Trimming
- **Description:** `CONTEXT_COMPACT` MUST fire before context trimming.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (HRK-006)
- **Test_Ids:** ['TEST-185']

## REQ-186. specsmith serve Command
- **ID:** REQ-186
- **Title:** specsmith serve Command
- **Description:** specsmith MUST provide a `specsmith serve` command (already shipped in v0.7.0).
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (SRV-001)
- **Test_Ids:** ['TEST-186']

## REQ-187. REST Endpoints for Session and Agent Management
- **ID:** REQ-187
- **Title:** REST Endpoints for Session and Agent Management
- **Description:** REST endpoints: `GET/POST /sessions`, `GET /agents`, `GET /instincts`, `GET /evals`, `POST /index`, `GET /health`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (SRV-002)
- **Test_Ids:** ['TEST-187']

## REQ-188. WebSocket Endpoint for Live Session I/O
- **ID:** REQ-188
- **Title:** WebSocket Endpoint for Live Session I/O
- **Description:** WebSocket endpoint at `/ws/session/{id}` for live session I/O using the existing JSONL event schema.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (SRV-003)
- **Test_Ids:** ['TEST-188']

## REQ-189. EventSink Protocol for Stdout and WebSocket
- **ID:** REQ-189
- **Title:** EventSink Protocol for Stdout and WebSocket
- **Description:** `AgentRunner._emit_event()` MUST use an `EventSink` protocol (`StdoutSink` / `WebSocketSink`).
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (SRV-004)
- **Test_Ids:** ['TEST-189']

## REQ-190. Kairos Terminal Connects via HTTP/WebSocket
- **ID:** REQ-190
- **Title:** Kairos Terminal Connects via HTTP/WebSocket
- **Description:** The Kairos terminal MUST connect to `specsmith serve` over HTTP/WebSocket for all governance operations.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (SRV-005)
- **Test_Ids:** ['TEST-190']

## REQ-191. BM25 Retrieval Ranking
- **ID:** REQ-191
- **Title:** BM25 Retrieval Ranking
- **Description:** `retrieval.py` MUST be upgraded from term-frequency to BM25 ranking using `rank_bm25`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (RTR-001)
- **Test_Ids:** ['TEST-191']

## REQ-192. File-Watcher Based Index Refresh
- **ID:** REQ-192
- **Title:** File-Watcher Based Index Refresh
- **Description:** The retrieval index MUST support file-watcher-based refresh.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (RTR-002)
- **Test_Ids:** ['TEST-192']

## REQ-193. Token-Counted Retrieval Results
- **ID:** REQ-193
- **Title:** Token-Counted Retrieval Results
- **Description:** Retrieval results MUST be token-counted before injection to prevent context budget overruns.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (RTR-003)
- **Test_Ids:** ['TEST-193']

## REQ-194. MCP Server Configuration Templates
- **ID:** REQ-194
- **Title:** MCP Server Configuration Templates
- **Description:** specsmith MUST provide MCP server configuration templates via `/mcp-add` or `specsmith mcp add`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MCP-001)
- **Test_Ids:** ['TEST-194']

## REQ-195. MCP Server Registry with Status
- **ID:** REQ-195
- **Title:** MCP Server Registry with Status
- **Description:** The MCP server registry MUST list configured servers with status and tool surfaces.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MCP-002)
- **Test_Ids:** ['TEST-195']

## REQ-196. MCP Configuration in scaffold.yml
- **ID:** REQ-196
- **Title:** MCP Configuration in scaffold.yml
- **Description:** MCP configuration MUST be storable in `scaffold.yml` under `agent.mcp_servers`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (MCP-003)
- **Test_Ids:** ['TEST-196']

## REQ-197. /security-scan Command
- **ID:** REQ-197
- **Title:** /security-scan Command
- **Description:** specsmith MUST provide a `/security-scan` command running a dedicated security analysis agent.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (SEC-001)
- **Test_Ids:** ['TEST-197']

## REQ-198. Security Scan Coverage
- **ID:** REQ-198
- **Title:** Security Scan Coverage
- **Description:** The security scan MUST check dependency vulnerabilities, OWASP-style code patterns, and exposed secrets.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (SEC-002)
- **Test_Ids:** ['TEST-198']

## REQ-199. /audit-prompt for Injection Analysis
- **ID:** REQ-199
- **Title:** /audit-prompt for Injection Analysis
- **Description:** `/audit-prompt` MUST analyze a prompt string for injection vectors.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (SEC-003)
- **Test_Ids:** ['TEST-199']

## REQ-200. Security Scan Results Stored Structurally
- **ID:** REQ-200
- **Title:** Security Scan Results Stored Structurally
- **Description:** Security scan results MUST be structured and stored at `.specsmith/security-reports/`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (SEC-004)
- **Test_Ids:** ['TEST-200']

## REQ-201. specsmith-ide Theia Application
- **ID:** REQ-201
- **Title:** specsmith-ide Theia Application
- **Description:** A `specsmith-ide` application MUST be created on Eclipse Theia with `@theia/ai-core`, `@theia/ai-chat`, `@theia/ai-ide`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (IDE-001)
- **Test_Ids:** ['TEST-201']

## REQ-202. specsmith-ide Extension Packages
- **ID:** REQ-202
- **Title:** specsmith-ide Extension Packages
- **Description:** specsmith-ide MUST ship: `@specsmith/ai-agents`, `@specsmith/epistemic-ui`, `@specsmith/eval-ui`, `@specsmith/service-client`.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (IDE-002)
- **Test_Ids:** ['TEST-202']

## REQ-203. specsmith-ide WebSocket Connection to specsmith serve
- **ID:** REQ-203
- **Title:** specsmith-ide WebSocket Connection to specsmith serve
- **Description:** specsmith-ide MUST connect to `specsmith serve` over WebSocket.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (IDE-003)
- **Test_Ids:** ['TEST-203']

## REQ-204. specsmith-ide Leverages Theia AI Native Tooling
- **ID:** REQ-204
- **Title:** specsmith-ide Leverages Theia AI Native Tooling
- **Description:** specsmith-ide MUST leverage Theia AI's existing MCP support, ShellExecutionTool, and agent skills system.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (IDE-004)
- **Test_Ids:** ['TEST-204']

## REQ-205. specsmith-ide Electron Desktop Packaging
- **ID:** REQ-205
- **Title:** specsmith-ide Electron Desktop Packaging
- **Description:** specsmith-ide MUST be packageable as an Electron desktop application.
- **Status:** implemented
- **Source:** docs/PLANNED-REQUIREMENTS.md (IDE-005)
- **Test_Ids:** ['TEST-205']

## REQ-206. Tamper-Evident Agent Action Log
- **ID:** REQ-206
- **Title:** Tamper-Evident Agent Action Log
- **Description:** specsmith MUST maintain a tamper-evident, append-only agent action log capturing every governance decision, tool invocation, input, and output. The log chain MUST use SHA-256 chaining so any modification is detectable. Satisfies EU AI Act Art. 12 (logging obligations) and NIST AI RMF (GO-6).
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-001]
- **Test_Ids:** ['TEST-206']

## REQ-207. Explanation Artifacts for Governance Decisions
- **ID:** REQ-207
- **Title:** Explanation Artifacts for Governance Decisions
- **Description:** Every governance decision (preflight, verify, classify) MUST produce an 'explanation artifact' recording: what data was used, which requirements were matched, why the decision was reached, and the confidence score. Satisfies EU AI Act Art. 13 (transparency), CFPB adverse-action requirements.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-002]
- **Test_Ids:** ['TEST-207']

## REQ-208. Action Log Replay and Export
- **ID:** REQ-208
- **Title:** Action Log Replay and Export
- **Description:** specsmith MUST support structured replay and export of agent action logs for external audit, regulatory submission, or incident investigation. Export format MUST be machine-readable (JSONL) and human-readable (Markdown). Satisfies OMB M-24-10 (AI use case inventories) and EU AI Act post-market monitoring.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-003]
- **Test_Ids:** ['TEST-208']

## REQ-209. Human Escalation Threshold
- **ID:** REQ-209
- **Title:** Human Escalation Threshold
- **Description:** specsmith MUST provide a configurable human-escalation threshold. When preflight confidence is below the threshold, or when a destructive/release intent is detected, execution MUST pause and route to human review. Satisfies NIST AI RMF (GO-4), OMB M-24-10 human-in-the-loop requirements.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-004]
- **Test_Ids:** ['TEST-209']

## REQ-210. Emergency Kill-Switch and Circuit-Breaker
- **ID:** REQ-210
- **Title:** Emergency Kill-Switch and Circuit-Breaker
- **Description:** specsmith MUST implement an emergency kill-switch that immediately halts agent activity when: (a) the user invokes a stop command, (b) an anomaly detector triggers, or (c) the retry budget is exhausted. The kill-switch MUST be reachable from both the CLI and the REST API. Satisfies EU AI Act Art. 14 (human oversight), NIST AI RMF.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-005]
- **Test_Ids:** ['TEST-210']

## REQ-211. Post-Market Behavioral Monitoring and Alerting
- **ID:** REQ-211
- **Title:** Post-Market Behavioral Monitoring and Alerting
- **Description:** specsmith MUST monitor agent behavior across sessions and alert when anomalous patterns are detected: unexpected confidence regression, unusual tool usage rates, or systematic requirement mismatches. Satisfies EU AI Act Art. 72 (post-market monitoring) and OMB M-24-10.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-006]
- **Test_Ids:** ['TEST-211']

## REQ-212. One-Click Rollback for File-Modifying Actions
- **ID:** REQ-212
- **Title:** One-Click Rollback for File-Modifying Actions
- **Description:** Every agent action that modifies governance files MUST create a timestamped backup before overwriting, and MUST expose a rollback command that restores the pre-action state. Satisfies NIST AI GenAI Profile (rollback and compensation), CFPB.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-007]
- **Test_Ids:** ['TEST-212']

## REQ-213. Safe Append-Only Write for New Governance Entries
- **ID:** REQ-213
- **Title:** Safe Append-Only Write for New Governance Entries
- **Description:** All new entries appended to governance files (LEDGER.md, REQUIREMENTS.md, TESTS.md) MUST use append-only mode — never truncating or overwriting existing content. Protects against data loss from agent errors. Satisfies EU AI Act technical controls and data integrity requirements.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-008]
- **Test_Ids:** ['TEST-213']

## REQ-214. AI Disclosure Metadata in Agent Outputs
- **ID:** REQ-214
- **Title:** AI Disclosure Metadata in Agent Outputs
- **Description:** Outputs generated by specsmith agents MUST include AI disclosure metadata when surfaced to end-users: which model was used, provider, confidence level, and whether the output was governance-gated. Satisfies FTC Operation AI Comply, Utah SB149 (2024) disclosure requirements.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-009]
- **Test_Ids:** ['TEST-214']

## REQ-215. Regulatory Compliance Export Report
- **ID:** REQ-215
- **Title:** Regulatory Compliance Export Report
- **Description:** specsmith MUST generate a structured compliance export report covering: AI system inventory, risk classification, human oversight controls, audit log summary, and incident history. Satisfies OMB M-24-10, Colorado SB24-205 impact assessments, EU AI Act technical docs.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-010]
- **Test_Ids:** ['TEST-215']

## REQ-216. Agent Risk Classification Before Deployment
- **ID:** REQ-216
- **Title:** Agent Risk Classification Before Deployment
- **Description:** Before activating a governance profile or agent session, specsmith MUST classify the intended use case against EU AI Act risk tiers (prohibited, high-risk Annex III, GPAI systemic-risk, or minimal-risk). High-risk use cases MUST require additional confirmation. Satisfies EU AI Act Art. 6 risk-based approach.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-011]
- **Test_Ids:** ['TEST-216']

## REQ-217. Least-Privilege Agent Permissions
- **ID:** REQ-217
- **Title:** Least-Privilege Agent Permissions
- **Description:** Every agent session MUST operate with the minimum permissions required. Agent capabilities MUST be explicitly declared, and sensitive operations (commit, push, create PR, external calls) MUST be individually gated. Satisfies EU AI Act agent registration, NIST AI RMF least-privilege principle.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-012]
- **Test_Ids:** ['TEST-217']

## REQ-218. Self-Optimization Bounded by Iteration Budget
- **ID:** REQ-218
- **Title:** Self-Optimization Bounded by Iteration Budget
- **Description:** All self-improvement loops (agent improve, eval harness, continuous learning) MUST be bounded by a configurable iteration budget. Unbounded recursion or runaway optimisation MUST be prevented. Satisfies EU AI Act systemic risk controls (GPAISR) and credit spend governance.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-013]
- **Test_Ids:** ['TEST-218']

## REQ-219. Local-First Model Routing for Governance Tasks
- **ID:** REQ-219
- **Title:** Local-First Model Routing for Governance Tasks
- **Description:** Governance classification tasks (preflight, verify, classify_intent) MUST default to a local Ollama model (zero cloud cost) and only escalate to cloud APIs when local confidence is below threshold. Reduces credit spend and avoids unnecessary data transfer to third parties.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-014]
- **Test_Ids:** ['TEST-219']

## REQ-220. Policy Guardrails at the Interface Layer
- **ID:** REQ-220
- **Title:** Policy Guardrails at the Interface Layer
- **Description:** specsmith MUST enforce allow/deny lists for tool categories and data access patterns at the agent interface layer — not just within prompts. Agents MUST NOT access live production databases or unmanaged data sources. Satisfies EU AI Act technical controls, California ADMT data governance requirements.
- **Status:** implemented
- **Source:** BTWS-2027 AI Governance Report [REG-015]
- **Test_Ids:** ['TEST-220']

## REQ-244. GPU-Aware Context Window Sizing
- **ID:** REQ-244
- **Title:** GPU-Aware Context Window Sizing
- **Description:** Before starting an Ollama agent session, specsmith MUST detect available GPU VRAM (NVIDIA via nvidia-smi, AMD via rocm-smi) and recommend a num_ctx value. VRAM tiers: <6 GB → 4096, 6-12 GB → 8192, 12-20 GB → 16384, >=20 GB → 32768. CPU-only defaults to 4096. The function MUST never raise on any platform.
- **Status:** implemented
- **Source:** Plan 0ca40db4 [CTX-001]
- **Test_Ids:** ['TEST-221', 'TEST-222']

## REQ-245. Live Context Fill Indicator
- **ID:** REQ-245
- **Title:** Live Context Fill Indicator
- **Description:** Every active agent conversation MUST track and emit context fill events with schema: {type: context_fill, used: int, limit: int, pct: float}. The fill percentage MUST be surfaced in the terminal UI as a compact progress bar (green 0-60%, yellow 60-80%, orange 80-90%, red >90%).
- **Status:** implemented
- **Source:** Plan 0ca40db4 [CTX-002]
- **Test_Ids:** ['TEST-223']

## REQ-246. Auto Context Compression at Configurable Threshold
- **ID:** REQ-246
- **Title:** Auto Context Compression at Configurable Threshold
- **Description:** When context fill reaches the configurable compression threshold (default 80%, range 50-95%), specsmith MUST automatically trigger context summarization. Compression MUST emit a context_compressed event with before/after token counts. Auto-compression MUST be togglable; when off, only a warning is surfaced.
- **Status:** implemented
- **Source:** Plan 0ca40db4 [CTX-003]
- **Test_Ids:** ['TEST-224']

## REQ-247. Hard Context Reservation — Never 100% Fill
- **ID:** REQ-247
- **Title:** Hard Context Reservation — Never 100% Fill
- **Description:** The context window MUST NEVER be allowed to reach 100% fill. A hard reservation of 15% (or MIN_FREE_TOKENS=2048, whichever is more restrictive) MUST remain free. When fill reaches the hard ceiling (default 85%), ContextFullError MUST be raised and emergency compression triggered regardless of the auto-compress toggle.
- **Status:** implemented
- **Source:** Plan 0ca40db4 [CTX-004]
- **Test_Ids:** ['TEST-225']

## REQ-248. Dev/Stable Update Channel Persistence
- **ID:** REQ-248
- **Title:** Dev/Stable Update Channel Persistence
- **Description:** specsmith MUST persist a user-chosen update channel (stable or dev) to ~/.specsmith/channel. specsmith channel set {stable|dev} writes the file; channel clear removes it. effective_channel_with_source() MUST return (channel, source) where source is user when the file exists, otherwise
- **Status:** implemented
- **Source:** ARCHITECTURE.md [Update Channel Selection]
- **Test_Ids:** ['TEST-248']

## REQ-249. ESDB JSON Export Command
- **ID:** REQ-249
- **Title:** ESDB JSON Export Command
- **Description:** specsmith esdb export [--output PATH] [--json] MUST dump all ESDB records (requirements and testcases) to a versioned JSON payload at the specified path, or default to <project>/.specsmith/esdb_export.json. Output includes esdb_version, ackend,
- **Status:** implemented
- **Source:** ARCHITECTURE.md [ESDB Extended Management]
- **Test_Ids:** ['TEST-249']

## REQ-250. ESDB JSON Import Command
- **ID:** REQ-250
- **Title:** ESDB JSON Import Command
- **Description:** specsmith esdb import <source> [--json] MUST validate a JSON export file (checking for
- **Status:** implemented
- **Source:** ARCHITECTURE.md [ESDB Extended Management]
- **Test_Ids:** ['TEST-250']

## REQ-251. ESDB Timestamped Backup Command
- **ID:** REQ-251
- **Title:** ESDB Timestamped Backup Command
- **Description:** specsmith esdb backup [--dir DIR] [--json] MUST create a timestamped snapshot at <dir>/esdb_backup_<YYYYMMDDTHHMMSSZ>.json (default dir: .specsmith/backups/). The snapshot payload MUST include esdb_version, 	imestamp, ackend,
- **Status:** implemented
- **Source:** ARCHITECTURE.md [ESDB Extended Management]
- **Test_Ids:** ['TEST-251']

## REQ-252. ESDB WAL Rollback Command
- **ID:** REQ-252
- **Title:** ESDB WAL Rollback Command
- **Description:** specsmith esdb rollback [--steps N] [--json] MUST report the number of WAL events that would be undone. In stub mode (ChronoMemory native engine not linked) it MUST return {ok: true, steps_requested: N, records_before: N, note: "..."} without modifying state.
- **Status:** implemented
- **Source:** ARCHITECTURE.md [ESDB Extended Management]
- **Test_Ids:** ['TEST-252']

## REQ-253. ESDB WAL Compact Command
- **ID:** REQ-253
- **Title:** ESDB WAL Compact Command
- **Description:** specsmith esdb compact [--json] MUST request WAL compaction. In stub mode it MUST return {ok: true, backend: "...", records: N, note: "..."} without error.
- **Status:** implemented
- **Source:** ARCHITECTURE.md [ESDB Extended Management]
- **Test_Ids:** ['TEST-253']

## REQ-254. Skills Deactivate Command
- **ID:** REQ-254
- **Title:** Skills Deactivate Command
- **Description:** specsmith skills deactivate <skill-id> [--project-dir DIR] MUST set ctive: false in the skill's skill.json, return True on success, and exit non-zero with an error message if the skill is not found.
- **Status:** implemented
- **Source:** ARCHITECTURE.md [AI Skills Builder]
- **Test_Ids:** ['TEST-254']

## REQ-255. Skills Delete Command
- **ID:** REQ-255
- **Title:** Skills Delete Command
- **Description:** specsmith skills delete <skill-id> [--project-dir DIR] [--yes] MUST prompt for confirmation unless --yes is provided, then permanently remove the skill directory under .specsmith/skills/. Returns non-zero if the skill is not found.
- **Status:** implemented
- **Source:** ARCHITECTURE.md [AI Skills Builder]
- **Test_Ids:** ['TEST-255']

## REQ-256. MCP Server Config Generation Command
- **ID:** REQ-256
- **Title:** MCP Server Config Generation Command
- **Description:** specsmith mcp generate <description> [--json] MUST produce a deterministic MCP server configuration stub with id,
- **Status:** implemented
- **Source:** ARCHITECTURE.md [MCP Server Generator]
- **Test_Ids:** ['TEST-256']

## REQ-257. Agent Ask Keyword Dispatcher
- **ID:** REQ-257
- **Title:** Agent Ask Keyword Dispatcher
- **Description:** specsmith agent ask <prompt> [--project-dir DIR] [--json-output] MUST route prompts to the appropriate subsystem by keyword matching (compliance, audit, skill, esdb, mcp, session) without requiring an LLM. It MUST return {reply, action, prompt} and print human-readable output unless --json-output is set.
- **Status:** implemented
- **Source:** ARCHITECTURE.md [Agent Ask Dispatcher]
- **Test_Ids:** ['TEST-257']

## REQ-258. Kairos ESDB Settings Page
- **ID:** REQ-258
- **Title:** Kairos ESDB Settings Page
- **Description:** The Kairos settings sidebar MUST include an ESDB page under the Specsmith umbrella group. The page MUST display current ESDB status (record count, backend, chain validity) and provide action buttons for Refresh, Export JSON, Import, Backup, Rollback, and Compact.
- **Status:** implemented
- **Source:** ARCHITECTURE.md [Kairos Settings Extensions]
- **Test_Ids:** ['TEST-258']

## REQ-259. Kairos Skills Settings Page
- **ID:** REQ-259
- **Title:** Kairos Skills Settings Page
- **Description:** The Kairos settings sidebar MUST include a Skills page under the Specsmith umbrella group. The page MUST display a description of the Skills system and instructions for using specsmith skills build and related commands.
- **Status:** implemented
- **Source:** ARCHITECTURE.md [Kairos Settings Extensions]
- **Test_Ids:** ['TEST-259']

## REQ-260. Kairos Eval Settings Page
- **ID:** REQ-260
- **Title:** Kairos Eval Settings Page
- **Description:** The Kairos settings sidebar MUST include an Eval page under the Specsmith umbrella group. The page MUST describe the evaluation tracking system and direct users to specsmith eval run for generating reports.
- **Status:** implemented
- **Source:** ARCHITECTURE.md [Kairos Settings Extensions]
- **Test_Ids:** ['TEST-260']

## REQ-261. Kairos AI Providers Table Without Column Overflow
- **ID:** REQ-261
- **Title:** Kairos AI Providers Table Without Column Overflow
- **Description:** The Kairos Agents > Providers settings page MUST display AI models in a table with fixed-width columns (Name: 200px, Model ID: 220px, Context: 80px, Output: 80px) using ConstrainedBox + Clipped elements. Long model names such as o4-mini-deep-research MUST NOT overflow into adjacent columns.
- **Status:** implemented
- **Source:** ARCHITECTURE.md [Kairos Settings Extensions]
- **Test_Ids:** ['TEST-261']

## REQ-262. Kairos MCP AI Builder Card
- **ID:** REQ-262
- **Title:** Kairos MCP AI Builder Card
- **Description:** The Kairos Agents > MCP servers list page MUST include a collapsible AI Builder card that accepts a natural-language server description, calls specsmith mcp generate <description> --json, displays the generated JSON stub, and offers an 'Add to ~/.specsmith/mcp.json' button that appends the stub to the user's MCP config file.
- **Status:** implemented
- **Source:** ARCHITECTURE.md [Kairos Settings Extensions]
- **Test_Ids:** ['TEST-262']

## REQ-263. HuggingFace Open LLM Leaderboard Sync
- **ID:** REQ-263
- **Title:** HuggingFace Open LLM Leaderboard Sync
- **Description:** specsmith MUST implement `src/specsmith/agent/hf_leaderboard.py` that fetches model benchmark data from the HuggingFace Datasets Server (`datasets-server.huggingface.co/rows?dataset=open-llm-leaderboard/contents`). The sync MUST be paginated (100 rows/page) and persist results to `~/.specsmith/model_scores.json` under a `bucket_scores` key.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §21 [HF-001]
- **Test_Ids:** ['TEST-282']

## REQ-264. HF Leaderboard Rate-Limit Handling
- **ID:** REQ-264
- **Title:** HF Leaderboard Rate-Limit Handling
- **Description:** The HF leaderboard sync MUST handle HTTP 429 with exponential-backoff retry (up to 4 attempts). It MUST parse the `RateLimit: "api";r=X;t=Y` header to extract the exact reset window and wait accordingly. A +1 s safety margin MUST be added to the `t=` value.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §21 [HF-002]
- **Test_Ids:** ['TEST-264']

## REQ-265. HF API Token Support
- **ID:** REQ-265
- **Title:** HF API Token Support
- **Description:** When `SPECSMITH_HF_TOKEN` or `hf_api_token` is configured, the HF sync MUST include an `Authorization: Bearer <token>` header. The CLI `specsmith model-intel test-hf` MUST validate the token via `huggingface.co/api/whoami-v2` and report whether the Datasets Server is reachable.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §21 [HF-003]
- **Test_Ids:** ['TEST-283']

## REQ-266. HF Leaderboard Static Fallback
- **ID:** REQ-266
- **Title:** HF Leaderboard Static Fallback
- **Description:** When HF is unreachable (network error, 5xx, or zero parseable rows), specsmith MUST load built-in static benchmark scores covering at least 40 models (OpenAI GPT-4o/mini, Claude 3.5 sonnet/haiku, Gemini 2.x, Mistral, Qwen, Llama, DeepSeek, Phi). The fallback MUST be transparent to callers.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §21 [HF-004]
- **Test_Ids:** ['TEST-263']

## REQ-267. Bucket Scoring Engine
- **ID:** REQ-267
- **Title:** Bucket Scoring Engine
- **Description:** specsmith MUST compute three task-bucket scores from raw benchmark values (0–100 scale): Reasoning = 0.35×MATH + 0.30×GPQA + 0.25×BBH + 0.10×IFEval; Conversational = 0.40×IFEval + 0.35×MMLU-PRO + 0.25×BBH; Longform = 0.35×MUSR + 0.35×IFEval + 0.30×MMLU-PRO. Scores MUST be rounded to 2 decimal places.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §22 [BKT-001]
- **Test_Ids:** ['TEST-265']

## REQ-268. Model Intelligence Recommendations
- **ID:** REQ-268
- **Title:** Model Intelligence Recommendations
- **Description:** `specsmith model-intel recommendations [--bucket reasoning|conversational|longform]` MUST return the top-10 models sorted by the requested bucket score. The governance HTTP server MUST expose `GET /api/model-intel/recommendations?bucket=<name>` returning the same data.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §22 [BKT-002]
- **Test_Ids:** ['TEST-266', 'TEST-280']

## REQ-269. Model Intelligence CLI Commands
- **ID:** REQ-269
- **Title:** Model Intelligence CLI Commands
- **Description:** specsmith MUST provide a `model-intel` CLI group with subcommands: `sync` (run HF sync), `scores [--model NAME]` (list/get cached scores), `recommendations [--bucket NAME]` (top-10 per bucket), `test-hf` (connectivity probe). All commands MUST support `--json` flag.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §21 [HF-005]
- **Test_Ids:** ['TEST-267', 'TEST-268']

## REQ-270. Model Capability Profiles
- **ID:** REQ-270
- **Title:** Model Capability Profiles
- **Description:** specsmith MUST implement `src/specsmith/agent/model_profiles.py` with a `ModelProfile` TypedDict containing `max_tokens`, `temperature`, `ctx_budget`, `action_capable`, `prompt_style` fields. A `get_profile(model)` function MUST resolve by prefix matching (longest key first) over ≥40 known models.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §23 [PRF-001]
- **Test_Ids:** ['TEST-269']

## REQ-271. Context History Trimmer
- **ID:** REQ-271
- **Title:** Context History Trimmer
- **Description:** `trim_history(messages, budget_chars)` in `model_profiles.py` MUST trim conversation history to fit within `budget_chars`. Oldest turns MUST be summarised into a compact `[Earlier conversation summary — N turns condensed]` assistant message rather than silently dropped. System messages MUST always be preserved.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §23 [PRF-002]
- **Test_Ids:** ['TEST-270']

## REQ-272. AI Model Pacer EMA Utilisation
- **ID:** REQ-272
- **Title:** AI Model Pacer EMA Utilisation
- **Description:** The `ModelRateLimitScheduler` MUST track RPM and TPM utilisation as exponentially-weighted moving averages (alpha=0.25) and expose them in `snapshot()` as `rpm_ema` and `tpm_ema` fields.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §24 [PCR-001]
- **Test_Ids:** ['TEST-271']

## REQ-273. AI Model Pacer Adaptive Concurrency
- **ID:** REQ-273
- **Title:** AI Model Pacer Adaptive Concurrency
- **Description:** `on_rate_limit(model, error, attempt)` MUST decrease `dynamic_concurrency` by 1 (minimum=1) and set `reduced_until` to now+120 s. Concurrency MUST restore incrementally (1 step per 60 s) once `reduced_until` has passed. The method MUST return a float delay for the caller to sleep.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §24 [PCR-002]
- **Test_Ids:** ['TEST-272']

## REQ-274. AI Model Pacer Image Token Estimation
- **ID:** REQ-274
- **Title:** AI Model Pacer Image Token Estimation
- **Description:** `estimate_request_tokens()` MUST accept an `image_count` parameter and include `image_count × image_token_estimate` tokens in the reservation. The default `image_token_estimate` MUST be 4096.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §24 [PCR-003]
- **Test_Ids:** ['TEST-273']

## REQ-275. Multi-Provider LLM Client with Fallback
- **ID:** REQ-275
- **Title:** Multi-Provider LLM Client with Fallback
- **Description:** specsmith MUST implement `src/specsmith/agent/llm_client.py` with a `LLMProvider` ABC and `LLMClient` that tries providers in order, falling back on HTTP 401/403/429/5xx. Concrete providers MUST cover Mistral, OpenAI, Google Gemini, and Ollama. A `MockProvider` MUST be available for tests.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §25 [LLM-001]
- **Test_Ids:** ['TEST-274']

## REQ-276. LLM Client O-Series Translation
- **ID:** REQ-276
- **Title:** LLM Client O-Series Translation
- **Description:** When the model name starts with `o1`, `o3`, or `o4`, or contains `-o1-`/`-o3-`/`-o4-`, the LLM client MUST use `max_completion_tokens` instead of `max_tokens`, force temperature to 1, and rename `system` role messages to `developer`.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §25 [LLM-002]
- **Test_Ids:** ['TEST-275']

## REQ-277. LLM Client vLLM Guided-JSON Mode
- **ID:** REQ-277
- **Title:** LLM Client vLLM Guided-JSON Mode
- **Description:** When a JSON schema is provided and the provider type is `byoe` or `huggingface`, the request MUST include `guided_json` and `chat_template_kwargs: {"enable_thinking": false}` to suppress chain-of-thought tokens and enforce structured output.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §25 [LLM-003]
- **Test_Ids:** ['TEST-276']

## REQ-278. Endpoint Preset Registry
- **ID:** REQ-278
- **Title:** Endpoint Preset Registry
- **Description:** `src/specsmith/agent/provider_registry.py` MUST export `ENDPOINT_PRESETS` — a list of built-in connection presets for at least: vLLM (localhost:8000), LM Studio (localhost:1234), llama.cpp (localhost:8080), OpenRouter, Together AI, Groq, Fireworks, DeepInfra, Perplexity, and Azure OpenAI. Each preset MUST include `id`, `label`, `base_url`, `endpoint_kind`, and `needs_key`.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §26 [PRE-001]
- **Test_Ids:** ['TEST-277']

## REQ-279. Endpoint Probe Enriched Metadata
- **ID:** REQ-279
- **Title:** Endpoint Probe Enriched Metadata
- **Description:** `probe_openai_compatible()` MUST return a `models_detail` list where each entry includes `id`, `owner`, `context_length` (from `max_model_len` on vLLM, `context_length` or `context_window` otherwise), and `description`. The cap MUST be 200 models.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §26 [PRE-002]
- **Test_Ids:** ['TEST-278']

## REQ-280. Suggested Profile Generation
- **ID:** REQ-280
- **Title:** Suggested Profile Generation
- **Description:** `specsmith agent suggest-profiles` MUST inspect available backends (cloud env vars, installed Ollama models, saved BYOE endpoints) and propose ready-to-add `ProviderEntry` suggestions with role-tuned temperature and max_tokens for the reasoning/conversational/longform AEE buckets. Suggestions MUST be inert (not auto-saved).
- **Status:** implemented
- **Source:** ARCHITECTURE.md §27 [SGP-001]
- **Test_Ids:** ['TEST-279']

## REQ-281. Kairos AI Settings Bucket Score Display
- **ID:** REQ-281
- **Title:** Kairos AI Settings Bucket Score Display
- **Description:** The Kairos Agents > Providers settings page MUST display bucket scores (reasoning, conversational, longform) retrieved from `GET /api/model-intel/scores/{model}` for each configured provider. Scores MUST be shown as compact numeric badges. A Sync button MUST call `POST /api/model-intel/sync`.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §20–21 [KAI-001]
- **Test_Ids:** ['TEST-281']

## REQ-300. YAML-First Governance Sync Pipeline
- **ID:** REQ-300
- **Title:** YAML-First Governance Sync Pipeline
- **Description:** When `.specsmith/governance-mode` contains `yaml`, `specsmith sync` MUST read docs/requirements/*.yml and docs/tests/*.yml as canonical sources, write .specsmith/requirements.json + testcases.json as JSON caches, and regenerate docs/REQUIREMENTS.md + docs/TESTS.md as derived artifacts. Legacy Markdown mode (governance-mode absent or `markdown`) MUST still work for backward compatibility.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §YAML-Native Governance Layer
- **Test_Ids:** ['TEST-300']

## REQ-301. Strict Governance Schema Validation
- **ID:** REQ-301
- **Title:** Strict Governance Schema Validation
- **Description:** `specsmith validate --strict` MUST enforce 8 governance schema checks: (1) duplicate REQ IDs, (2) duplicate TEST IDs, (3) missing required REQ fields (id/title/status), (4) missing required TEST fields (id/title/requirement_id), (5) orphaned TESTs (reference non-existent REQ), (6) untested REQs (warning), (7) duplicate REQ titles (warning), (8) machine-state drift between YAML and JSON (warning). Exits 1 on errors; warnings do not block. `--json` flag emits structured output.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §YAML-Native Governance Layer
- **Test_Ids:** ['TEST-301']

## REQ-302. Generate Docs Command Renders YAML to Markdown
- **ID:** REQ-302
- **Title:** Generate Docs Command Renders YAML to Markdown
- **Description:** `specsmith generate docs` MUST read docs/requirements/*.yml and docs/tests/*.yml in YAML-first mode, render the canonical Markdown artifacts docs/REQUIREMENTS.md and docs/TESTS.md, and also re-sync the JSON machine state. `--check` flag MUST report what would change without writing. Only available when governance-mode is `yaml`.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §YAML-Native Governance Layer
- **Test_Ids:** ['TEST-302']

## REQ-303. Governance Mode Flag Controls Authority Direction
- **ID:** REQ-303
- **Title:** Governance Mode Flag Controls Authority Direction
- **Description:** `.specsmith/governance-mode` MUST contain `yaml` to activate YAML-first mode. `is_yaml_mode(root)` in `specsmith.governance_yaml` reads this flag. Absence of the file or value `markdown` activates legacy Markdown-primary mode. The flag is written by `scripts/migrate_governance_to_yaml.py`.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §YAML-Native Governance Layer
- **Test_Ids:** ['TEST-303']

## REQ-304. YAML Governance Migration Script
- **ID:** REQ-304
- **Title:** YAML Governance Migration Script
- **Description:** `scripts/migrate_governance_to_yaml.py` MUST be idempotent and execute the following steps in order: (1) remove duplicate REQs from REQUIREMENTS.md, (2) re-sync .specsmith/ JSON from cleaned MD, (3) export JSON to grouped YAML files under docs/requirements/ and docs/tests/, (4) write .specsmith/governance-mode = yaml. Re-running must not corrupt the governance state.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §YAML-Native Governance Layer
- **Test_Ids:** ['TEST-304']

## REQ-305. ChronoStore WAL-Based ESDB Write Layer
- **ID:** REQ-305
- **Title:** ChronoStore WAL-Based ESDB Write Layer
- **Description:** specsmith MUST implement src/specsmith/esdb/store.py with a ChronoStore class providing a WAL-based per-project epistemic state database. The WAL MUST be stored at <project>/.chronomemory/events.wal as NDJSON with SHA-256 hash chaining. A materialized snapshot MUST be written every 50 events at snapshot.json. WAL append MUST be crash-safe via write-to-temp-then-rename.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §ESDB / ChronoStore
- **Test_Ids:** ['TEST-305']

## REQ-306. ESDB Must Be Per-Project
- **ID:** REQ-306
- **Title:** ESDB Must Be Per-Project
- **Description:** Each governed project MUST have its own ESDB at <project_root>/.chronomemory/. Global or shared ESDB instances are not permitted. EsdbBridge MUST delegate to ChronoStore when vents.wal exists, and fall back to flat JSON read-only mode otherwise.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §ESDB / ChronoStore
- **Test_Ids:** ['TEST-306']

## REQ-307. Session State Must Survive Restart
- **ID:** REQ-307
- **Title:** Session State Must Survive Restart
- **Description:** specsmith MUST persist session context to .specsmith/session-state.json and conversation history to .specsmith/conversation-history.jsonl (capped at 200 turns). On init_session(), the previous session context MUST be loaded and a synthetic resume message injected as the first history entry. GET /api/session/history MUST return the stored history.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Session Persistence
- **Test_Ids:** ['TEST-307']

## REQ-308. Context Orchestrator with Tiered Auto-Optimization
- **ID:** REQ-308
- **Title:** Context Orchestrator with Tiered Auto-Optimization
- **Description:** specsmith MUST implement src/specsmith/context_orchestrator.py with a ContextOrchestrator that applies three tiers: Tier 1 (60-79% fill) compresses LEDGER.md history; Tier 2 (80-84%) summarizes conversation and evicts low-confidence ESDB records; Tier 3 (>=85%) emergency-drops records with confidence < 0.7. Data on disk MUST NEVER be deleted.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Context Orchestrator
- **Test_Ids:** ['TEST-308']

## REQ-309. CI Automation Togglable Per Project
- **ID:** REQ-309
- **Title:** CI Automation Togglable Per Project
- **Description:** specsmith ci enable MUST generate CI, Dependabot, and CodeQL configs. specsmith ci status --json MUST return a JSON object with ci_available, ci_passing, open_dep_alerts, open_security_alerts. specsmith ci watch MUST poll until the run completes. CI automation state MUST be persisted to .specsmith/config.yml.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §CI Automation Manager
- **Test_Ids:** ['TEST-309']

## REQ-310. OEA Anti-Hallucination Fields on ESDB Records
- **ID:** REQ-310
- **Title:** OEA Anti-Hallucination Fields on ESDB Records
- **Description:** Every ChronoRecord MUST carry OEA anti-hallucination fields: source_type, confidence, vidence, pistemic_boundary, is_hypothesis, model_assumptions, ecursion_depth. All fields MUST default to safe non-blocking values for records migrated from legacy JSON.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §OEA Anti-Hallucination Governance Layer
- **Test_Ids:** ['TEST-310']

## REQ-311. RAG Retrieval Must Filter by Confidence
- **ID:** REQ-311
- **Title:** RAG Retrieval Must Filter by Confidence
- **Description:** ESDB retrieval MUST accept a min_confidence threshold and exclude records with confidence < min_confidence. Records at exactly the threshold MUST be included. Default threshold is 0.0 (no filtering).
- **Status:** implemented
- **Source:** ARCHITECTURE.md §ESDB / ChronoStore
- **Test_Ids:** ['TEST-311']

## REQ-312. Context Optimize Command
- **ID:** REQ-312
- **Title:** Context Optimize Command
- **Description:** specsmith context optimize --fill-pct <N> [--json] MUST call ContextOrchestrator.optimize() and report tier-specific actions taken. --json MUST emit a JSON summary with 	ier, ctions, and
	okens_freed.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Context Orchestrator
- **Test_Ids:** ['TEST-312']

## REQ-313. Dispatch Run Audit Entry in LEDGER.md
- **ID:** REQ-313
- **Title:** Dispatch Run Audit Entry in LEDGER.md
- **Description:** Every completed `specsmith dispatch run` MUST append a governance ledger entry to LEDGER.md and `.specsmith/ledger.jsonl` recording the dag_id, task description, node count, completed count, failed count, and equilibrium result. This satisfies EU AI Act Art. 12 (record-keeping for multi-agent AI actions).
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-313']

## REQ-314. Worker Identity Disclosure in Dispatch Events
- **ID:** REQ-314
- **Title:** Worker Identity Disclosure in Dispatch Events
- **Description:** Each `node_started` DispatchEvent MUST include the worker role in its payload so the audit trail identifies which agent type executed each node. The role MUST be drawn from ROLE_TOOLS and persisted to events.jsonl. This implements EU AI Act Art. 13 (transparency) for dispatched agent actions.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-314']

## REQ-315. Dispatch Session Traceable to Orchestrator Entry
- **ID:** REQ-315
- **Title:** Dispatch Session Traceable to Orchestrator Entry
- **Description:** Each dispatch run dag_id MUST be traceable back to its originating Orchestrator call (REQ-321). The run() method MUST return a DispatchSummary that includes dag_id, and the CLI MUST display it on completion so the operator can correlate events.jsonl records with specific CLI invocations.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-315']

## REQ-316. Governance Preflight Outcome Recorded Per Node
- **ID:** REQ-316
- **Title:** Governance Preflight Outcome Recorded Per Node
- **Description:** When a node governance preflight returns a non-accepted decision, the FAILED DispatchResult MUST include the governance instruction in its error field. This creates a per-node audit trail of governance decisions aligned with EU AI Act Art. 14 (human oversight) and NIST AI RMF GOVERN.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-316']

## REQ-317. Context Injection Audit via ESDB Record IDs
- **ID:** REQ-317
- **Title:** Context Injection Audit via ESDB Record IDs
- **Description:** When predecessor ESDB records are injected into a successor node's context, the ESDB record IDs (context_in list) MUST be included in the node's TaskNode data structure and available for replay from events.jsonl. This provides a traceable chain of information flow between agents.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-317']

## REQ-318. Dispatch Run Resumability Must Preserve Completed Node Results
- **ID:** REQ-318
- **Title:** Dispatch Run Resumability Must Preserve Completed Node Results
- **Description:** The events.jsonl checkpoint for a DAG run MUST contain enough information to determine which nodes completed and which failed, so that a retry operation never re-executes completed nodes. COMPLETED nodes MUST NOT be re-executed when dispatch retry is invoked (REQ-330).
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-318']

## REQ-319. ESDB dispatch_result Records Must Include DAG Lineage
- **ID:** REQ-319
- **Title:** ESDB dispatch_result Records Must Include DAG Lineage
- **Description:** ChronoRecords written by AgentDispatcher for completed nodes (kind=dispatch_result) MUST include dag_id and node_id in their evidence list and data dict. This enables ESDB-level queries to trace any stored result back to the originating dispatch run and node.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-319']

## REQ-320. Abort Signal Must Be Recorded in Node Failure Error
- **ID:** REQ-320
- **Title:** Abort Signal Must Be Recorded in Node Failure Error
- **Description:** When a node is aborted via abort_node() or POST /api/dispatch/abort, the resulting FAILED DispatchResult MUST include "Aborted" in its error string so the operator and audit log can distinguish intentional aborts from unintended failures. This satisfies EU AI Act Art. 14 §4 (ability to intervene must be traceable).
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-320']

## REQ-321. Orchestrator Is Sole Dispatch Entry Point
- **ID:** REQ-321
- **Title:** Orchestrator Is Sole Dispatch Entry Point
- **Description:** The Orchestrator MUST remain the sole entry point for all dispatched work. Worker agents MUST NOT initiate new dispatches or call AgentDispatcher directly.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-321']

## REQ-322. DAG Decomposition Before Worker Dispatch
- **ID:** REQ-322
- **Title:** DAG Decomposition Before Worker Dispatch
- **Description:** When use_dag=True, the Orchestrator MUST call TaskDAGBuilder.build(task) and validate the resulting TaskDAG is acyclic before dispatching any worker agent. On cycle detection a DAGValidationError MUST be raised and execution MUST fall back to the existing flat GroupChat path with a warning.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-322']

## REQ-323. TaskNode Must Carry Required Fields
- **ID:** REQ-323
- **Title:** TaskNode Must Carry Required Fields
- **Description:** Each TaskNode MUST carry a unique string id, a human-readable title, an assigned role matching ROLE_TOOLS, an explicit depends_on list of node ids, a TaskStatus (PENDING | RUNNING | COMPLETED | FAILED | BLOCKED), context_in (list of ESDB record IDs), context_out (ESDB record ID written on completion or None), and result (DispatchResult or None).
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-323']

## REQ-324. Concurrent Dispatch Bounded by max_workers
- **ID:** REQ-324
- **Title:** Concurrent Dispatch Bounded by max_workers
- **Description:** AgentDispatcher MUST execute independent (runnable) TaskNodes concurrently up to max_workers (default 4) using ThreadPoolExecutor. It MUST NOT dispatch more than max_workers nodes simultaneously at any point during a run.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-324']

## REQ-325. Fail-Forward BLOCKED Propagation
- **ID:** REQ-325
- **Title:** Fail-Forward BLOCKED Propagation
- **Description:** When a TaskNode transitions to FAILED, AgentDispatcher MUST mark all direct and transitive dependent nodes as BLOCKED. Non-dependent sibling nodes that are still PENDING or RUNNING MUST continue executing without interruption.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-325']

## REQ-326. AgentPool Must Reuse Idle Workers
- **ID:** REQ-326
- **Title:** AgentPool Must Reuse Idle Workers
- **Description:** AgentPool MUST reuse idle ConversableAgent instances for new tasks of the same role rather than spawning unbounded agents. The pool MUST track active and idle workers per role and enforce the max_workers ceiling.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-326']

## REQ-327. ESDB Context Written on Node Completion
- **ID:** REQ-327
- **Title:** ESDB Context Written on Node Completion
- **Description:** On successful TaskNode completion, AgentDispatcher MUST write a ChronoRecord to ChronoStore with kind=dispatch_result containing the DispatchResult payload. Successor tasks MUST receive predecessor ChronoRecord IDs in their context_in and retrieve the records via ESDB query before starting.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-327']

## REQ-328. DAG State Transitions Persisted as JSONL Events
- **ID:** REQ-328
- **Title:** DAG State Transitions Persisted as JSONL Events
- **Description:** Every TaskNode state transition (node_started, node_completed, node_failed, node_blocked) and the terminal dag_done event MUST be serialized as a DispatchEvent and appended to .specsmith/dispatch/<dag_id>/events.jsonl. The file MUST be created before the first node starts.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-328']

## REQ-329. Per-Node Governance Preflight Before Worker Start
- **ID:** REQ-329
- **Title:** Per-Node Governance Preflight Before Worker Start
- **Description:** Before a worker agent begins executing a TaskNode, AgentDispatcher MUST call execute_with_governance (or equivalent preflight check) with the node task description. If governance returns needs_clarification or rejected the node MUST transition to FAILED immediately.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-329']

## REQ-330. DAG Run Must Be Resumable from Checkpoint
- **ID:** REQ-330
- **Title:** DAG Run Must Be Resumable from Checkpoint
- **Description:** A saved DAG run (events.jsonl) MUST be resumable via specsmith dispatch retry. The retry command MUST replay only the FAILED or BLOCKED nodes from the last checkpoint while treating COMPLETED nodes as already done. COMPLETED nodes MUST NOT be re-executed.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-330']

## REQ-331. Dispatch CLI Group with run/status/list/retry
- **ID:** REQ-331
- **Title:** Dispatch CLI Group with run/status/list/retry
- **Description:** specsmith dispatch MUST expose four subcommands: run <TASK> [--max-workers N] [--json] [--no-dag] to start a dispatch; status [--dag-id ID] to print per-node status; list to enumerate all saved DAG runs; retry --node NODE_ID --dag-id ID to re-run a single failed node.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-331']

## REQ-332. Kairos Live DAG Graph Panel
- **ID:** REQ-332
- **Title:** Kairos Live DAG Graph Panel
- **Description:** Kairos MUST render a DispatchPanelView that subscribes to GET /api/dispatch/events SSE and renders an SVG DAG graph with nodes coloured by status (pending=grey, running=blue, completed=green, failed=red, blocked=amber) and directed edges showing dependencies. A node click MUST open a side panel with role, summary, files changed, and ESDB record ID.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-332']

## REQ-333. Kairos Gantt Timeline Strip
- **ID:** REQ-333
- **Title:** Kairos Gantt Timeline Strip
- **Description:** Kairos MUST render a GanttStrip alongside the DAG graph showing a horizontal timeline bar per node, filled as the node transitions from pending to running to completed, visually indicating parallel execution overlap.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-333']

## REQ-334. Kairos Per-Node Retry and Abort Controls
- **ID:** REQ-334
- **Title:** Kairos Per-Node Retry and Abort Controls
- **Description:** Kairos MUST provide a Retry button on FAILED and BLOCKED nodes (calls POST /api/dispatch/retry) and an Abort button on RUNNING nodes (calls POST /api/dispatch/abort). Retry and Abort MUST be disabled when not applicable to the node status.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Multi-Agent DAG Dispatcher
- **Test_Ids:** ['TEST-334']

## REQ-335. specsmith test-ran CLI Subcommand
- **ID:** REQ-335
- **Title:** specsmith test-ran CLI Subcommand
- **Description:** specsmith MUST provide a `test-ran <TEST-ID> --result passed|failed|error|skipped` CLI subcommand that records a test run outcome in `.specsmith/testcases.json`. On invocation it MUST update `last_result` and `last_run_at` fields on the matching test case record, transition status from `pending` to `implemented` when result is `passed`, transition to `failing` when result is `failed`, write a best-effort ledger entry via `add_entry`, and emit a JSON payload (with `--json`) or a human-readable summary. If the test ID is not found it MUST exit 1. If `testcases.json` is absent it MUST exit 1 with a message directing the user to run `specsmith sync`.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Governance CLI
- **Test_Ids:** ['TEST-335']

## REQ-336. specsmith save CLI Command
- **ID:** REQ-336
- **Title:** specsmith save CLI Command
- **Description:** specsmith MUST provide a top-level `save` CLI command that performs a full governance checkpoint in three steps: (1) create a timestamped ESDB backup via ChronoStore.backup(); (2) git-commit all pending governance changes (LEDGER.md, .specsmith/, docs/) with an auto-generated commit message; (3) git-push the current branch to origin. The command MUST exit 0 on success, exit 1 on any step failure, and print a human-readable summary of what was saved. `--json` MUST emit a structured payload with backup_path, commit_hash, and push_ok fields.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §CI Automation Manager — save/load Commands
- **Test_Ids:** ['TEST-336']

## REQ-337. specsmith load CLI Command
- **ID:** REQ-337
- **Title:** specsmith load CLI Command
- **Description:** specsmith MUST provide a top-level `load` CLI command that pulls the latest governance state from origin: (1) git-pull the current branch; (2) optionally restore the latest ESDB backup when `--restore-backup` is passed; (3) print a status report of what changed. The command MUST exit 0 on success and exit 1 if git-pull fails with an unresolvable conflict. `--json` MUST emit a structured payload with pull_ok, files_changed, and backup_restored fields.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §CI Automation Manager — save/load Commands
- **Test_Ids:** ['TEST-337']

## REQ-338. specsmith_run Agent Tool with Slash-Command Routing
- **ID:** REQ-338
- **Title:** specsmith_run Agent Tool with Slash-Command Routing
- **Description:** The agent tool registry MUST expose a `specsmith_run(command)` tool that normalises three input forms to `specsmith <args>` and executes via subprocess: (1) slash-command prefix (`/specsmith save`); (2) single-word verb shortcuts (`save`, `load`, `push`, `pull`, `sync`, `audit`, `status`, `watch`, `commit`, `validate`, `doctor`, `run`); (3) full passthrough (`specsmith <args>`). The tool MUST be registered in AVAILABLE_TOOLS and build_tool_registry() with REG-001/REG-002 epistemic claim metadata. Agents MUST use specsmith_run for all governance CLI operations instead of raw run_shell calls.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Agent Tool Registry — specsmith_run
- **Test_Ids:** ['TEST-338']

## REQ-339. M005 Agent-Run-Tool Migration
- **ID:** REQ-339
- **Title:** M005 Agent-Run-Tool Migration
- **Description:** The migration framework MUST include migration M005 (version=5) that auto-upgrades existing projects to use the specsmith_run governance command. M005 MUST: (1) write `.specsmith/agent-tools.json` declaring specsmith_run as the primary_governance_command with a full verb_shortcuts list; (2) append a "Governance commands" section to AGENTS.md documenting all /specsmith slash-command forms, backing up the original to `.specsmith/agents.md.m005.bak`. Both steps MUST be non-destructive and support `dry_run=True` and `rollback()`. M005 MUST be registered in MigrationRegistry.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Migration Framework — M005
- **Test_Ids:** ['TEST-339']

## REQ-340. /specsmith REPL Slash-Command Handler
- **ID:** REQ-340
- **Title:** /specsmith REPL Slash-Command Handler
- **Description:** The Nexus REPL (agent/repl.py) MUST handle `/specsmith <args>` as a first-class slash command that passes args verbatim to the specsmith CLI subprocess and streams output directly to the terminal without buffering. The handler MUST gracefully handle subprocess timeout (120 s default) and unexpected exceptions without crashing the REPL. The REPL startup banner MUST advertise the /specsmith command. Invoking `/specsmith` with no args MUST display specsmith --help.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Nexus REPL — /specsmith Handler
- **Test_Ids:** ['TEST-340']

## REQ-341. Terminal Awareness Skill in Skills Catalog
- **ID:** REQ-341
- **Title:** Terminal Awareness Skill in Skills Catalog
- **Description:** specsmith.skills MUST include a 	erminal-awareness skill in the CROSS_PLATFORM domain covering: (1) shell detection from Python and from the shell itself; (2) PowerShell 5 vs 7 syntax differences (null-coalescing, ternary, parallel ForEach-Object, encoding, &&/|| availability); (3) cmd.exe rules (no PowerShell cmdlets in pipelines, % variables, ^ continuation); (4) bash/zsh/fish patterns (background PID capture, trap cleanup, timeout); (5) Python subprocess spawn with PID tracking using communicate(timeout) and DEVNULL stdin; (6) PowerShell Start-Process -PassThru PID tracking with WaitForExit; (7) a cross-platform command equivalents table; (8) a cleanup checklist for spawned processes.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §37 Skills Catalog
- **Test_Ids:** ['TEST-341']

## REQ-342. Shell-Aware Command Generation
- **ID:** REQ-342
- **Title:** Shell-Aware Command Generation
- **Description:** Agents operating on behalf of specsmith MUST detect the active shell before emitting shell commands. PowerShell cmdlets (Write-Host, Get-ChildItem, Start-Process, etc.) MUST NOT be emitted when the active shell is bash, zsh, fish, or cmd.exe. bash-isms (, export, $!) MUST NOT be emitted in PowerShell or cmd.exe contexts. The terminal-awareness skill provides the detection and equivalents reference that agents MUST consult.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §37 Skills Catalog
- **Test_Ids:** ['TEST-342']

## REQ-343. Subprocess Spawn with PID Tracking and Cleanup
- **ID:** REQ-343
- **Title:** Subprocess Spawn with PID Tracking and Cleanup
- **Description:** specsmith process execution (specsmith exec, run_tracked) MUST spawn subprocesses using communicate(timeout=N) with stdin=DEVNULL to prevent hanging. Spawned PIDs MUST be written to .specsmith/pids/<pid>.json so specsmith ps and specsmith abort can list and kill them. On timeout, the implementation MUST call proc.kill() then proc.communicate() to drain pipes and avoid zombie processes. On Windows, CREATE_NEW_PROCESS_GROUP MUST be set for clean signal forwarding.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §37 Skills Catalog
- **Test_Ids:** ['TEST-343']

## REQ-344. specsmith.esdb Namespace Re-exports chronomemory v0.1.1
- **ID:** REQ-344
- **Title:** specsmith.esdb Namespace Re-exports chronomemory v0.1.1
- **Description:** src/specsmith/esdb/__init__.py MUST re-export the full chronomemory v0.1.1 public API surface under the specsmith.esdb namespace: ChronoStore, ChronoRecord, WalEvent, open_store, EsdbBridge, EsdbRecord, EsdbStatus, DepGraph, DependencyEdge, RollbackReport, invalidate, ContextPack, ContextPackCompiler, ContextPackEntry, RustChronoStore, RustRecord, RUST_BACKEND, plus module-level references to query and metrics. specsmith.esdb.bridge MUST expose EsdbBridge, ContextPackCompiler, DepGraph, RUST_BACKEND, query, and metrics.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §36 specsmith.esdb Namespace
- **Test_Ids:** ['TEST-344']

## REQ-345. LLM Context MUST Use query.what_is_known Not store.query(rag_filter)
- **ID:** REQ-345
- **Title:** LLM Context MUST Use query.what_is_known Not store.query(rag_filter)
- **Description:** All specsmith code paths that inject ESDB ChronoRecords into LLM context (retrieval index building, context seed generation, context orchestrator eviction decisions) MUST use query.what_is_known(store) instead of store.query(rag_filter=True). query.what_is_known excludes infrastructure record kinds (edge, rollback_event, token_metric, skill_run) in addition to applying the confidence >= 0.6 filter. Infrastructure records MUST NEVER appear in agent-facing context.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §36 specsmith.esdb Namespace
- **Test_Ids:** ['TEST-345']

## REQ-346. specsmith save --force Propagates Force to Push
- **ID:** REQ-346
- **Title:** specsmith save --force Propagates Force to Push
- **Description:** specsmith save MUST accept a --force flag that propagates to the underlying run_push() call, bypassing the gitflow direct-to-main guard and any other push safety checks. The push MUST use git push --force-with-lease (not --force) to avoid overwriting concurrent remote changes. --force has no effect when --no-push is also passed. When --force is omitted, all existing safety checks apply unchanged.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §38 VCS Force Operations
- **Test_Ids:** ['TEST-346']

## REQ-347. specsmith pull --discard Hard-Resets to Remote Branch
- **ID:** REQ-347
- **Title:** specsmith pull --discard Hard-Resets to Remote Branch
- **Description:** specsmith pull MUST accept a --discard flag. When passed, the implementation MUST: (1) run git fetch origin <branch> to bring the remote ref current; (2) run git reset --hard origin/<branch> to hard-reset the working tree; (3) report success with the branch name. All local uncommitted changes are discarded. This replaces the normal git pull (which preserves local state) when a clean reset to remote is required.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §38 VCS Force Operations
- **Test_Ids:** ['TEST-347']

## REQ-348. specsmith pull --clean Removes Untracked Files After Discard
- **ID:** REQ-348
- **Title:** specsmith pull --clean Removes Untracked Files After Discard
- **Description:** When specsmith pull --clean is passed, the implementation MUST perform the same hard-reset sequence as --discard and additionally run git clean -fd to remove all untracked files and directories. The success message MUST note that untracked files were removed. --clean implies --discard; passing --clean without --discard MUST produce the same result.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §38 VCS Force Operations
- **Test_Ids:** ['TEST-348']

## REQ-349. gh-ci-polling Skill Prohibits Sleep-Based CI Waiting
- **ID:** REQ-349
- **Title:** gh-ci-polling Skill Prohibits Sleep-Based CI Waiting
- **Description:** specsmith.skills MUST include a gh-ci-polling skill in the GOVERNANCE domain documenting gh run watch as the correct CI-wait primitive. The skill MUST explicitly prohibit Start-Sleep, sleep, and time.sleep as CI wait mechanisms. It MUST provide: (1) the canonical gh run watch pattern for bash and PowerShell; (2) non-blocking gh run list --json conclusion status check; (3) the one acceptable polling loop (with state check, minimum 15-second interval) for when gh run watch is unavailable; (4) gh run view --log-failed for immediate failure triage.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §37 Skills Catalog
- **Test_Ids:** ['TEST-349']

## REQ-350. Epistemic Metadata Passthrough in Sync Pipeline
- **ID:** REQ-350
- **Title:** Epistemic Metadata Passthrough in Sync Pipeline
- **Description:** specsmith sync MUST pass through platform, boundary, and confidence fields from YAML requirement sources into the .specsmith/requirements.json machine-state entries when those fields are present in the YAML. These fields are used by generate_requirements_md to render them into REQUIREMENTS.md and by belief.py to parse Platform/Boundary/Confidence metadata. Absent fields MUST be omitted from the JSON entry (not written as null).
- **Status:** implemented
- **Source:** ARCHITECTURE.md §YAML-Native Governance Layer
- **Test_Ids:** ['TEST-350']

## REQ-351. specsmith checkpoint Governance Anchor Command
- **ID:** REQ-351
- **Title:** specsmith checkpoint Governance Anchor Command
- **Description:** specsmith MUST provide a checkpoint CLI command that emits a compact GOVERNANCE ANCHOR summarising the current project state: project name (from scaffold.yml), AEE phase with readiness percentage, audit health and failed check count, REQ count, TEST count, ESDB record count with chain validity, up to 3 recent WI- identifiers from LEDGER.md, and the last preflight acceptance line. With --json it MUST emit a JSON payload containing ts, project, phase, phase_label, phase_pct, health, audit_failed, req_count, test_count, esdb_records, esdb_chain_valid, recent_wis, last_preflight, and anchor fields. Without --json it MUST emit a human-readable bordered GOVERNANCE ANCHOR block with a footer instructing agents to include it verbatim in any context summary. All data gathering MUST be best-effort (exceptions silently swallowed) so the command never fails even on projects with no ESDB or LEDGER.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Session Governance Protocol
- **Test_Ids:** ['TEST-351']

## REQ-352. M006 Session Governance Migration Auto-injects Protocol into AGENTS.md
- **ID:** REQ-352
- **Title:** M006 Session Governance Migration Auto-injects Protocol into AGENTS.md
- **Description:** specsmith MUST include migration M006 (version=6) that detects whether AGENTS.md contains any of the sentinel strings 'specsmith checkpoint', 'Session Governance Protocol', 'GOVERNANCE ANCHOR', or 'governance heartbeat'. When none are present, M006 MUST back up AGENTS.md to .specsmith/agents.md.m006.bak and inject the full Session Governance Protocol section (heartbeat every 8-10 turns, preflight gate, drift detection checklist, checkpoint-in-summary rule, session end). M006 MUST be idempotent (re-running when section is present is a no-op), non-destructive (original always backed up), and registered in MigrationRegistry so it runs automatically via specsmith migrate-project and specsmith upgrade --full.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Session Governance Protocol
- **Test_Ids:** ['TEST-352']

## REQ-353. Modern Web Framework Project Types
- **ID:** REQ-353
- **Title:** Modern Web Framework Project Types
- **Description:** specsmith MUST support the following modern web framework project types in addition to the existing web-frontend and fullstack-js types: nextjs-app (Next.js / React with SSR/SSG, next lint, jest/playwright), nuxt-app (Nuxt.js / Vue, vitest, playwright), sveltekit-app (SvelteKit, vitest, playwright), remix-app (Remix React, vitest, playwright), astro-site (Astro static/SSR, vitest, playwright). Each MUST have a corresponding ToolSet entry in the tool registry with appropriate lint, typecheck, test, security, build, and format tools. Each MUST appear in _TYPE_LABELS with a human-readable label.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §Implemented Specsmith System
- **Test_Ids:** ['TEST-353']

## REQ-354. CodityAdapter Scaffolds AI Code Review CI Workflow
- **ID:** REQ-354
- **Title:** CodityAdapter Scaffolds AI Code Review CI Workflow
- **Description:** specsmith MUST provide a CodityAdapter registered as 'codity' in the integrations registry. CodityAdapter.generate() MUST detect the VCS host from scaffold.yml content ('gitlab' keyword → gitlab, 'azure' keyword → azure, else github) and from directory heuristics (.gitlab-ci.yml → gitlab, azure-pipelines.yml → azure). For github it MUST write .github/workflows/codity-review.yml; for gitlab it MUST write .gitlab-ci-codity.yml; for azure it MUST write .azure-pipelines/codity-review.yml. All variants MUST install the Codity CLI via the official install script, run 'codity review --staged', and require CODITY_ACCESS_TOKEN. GitLab and Azure variants MUST additionally call 'codity config set-pat --provider <vcs>'. generate() MUST also write docs/codity-setup.md (one-time setup checklist) and append a TODO checklist to LEDGER.md if it exists. The adapter MUST be discoverable via specsmith integrate codity.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §39
- **Test_Ids:** ['TEST-354', 'TEST-355']

## REQ-355. AGENTS.md Template Includes Codity.ai Pre-commit Rule
- **ID:** REQ-355
- **Title:** AGENTS.md Template Includes Codity.ai Pre-commit Rule
- **Description:** The AGENTS.md Jinja2 template (agents.md.j2) MUST include a 'Codity.ai Code Review' section that instructs agents: if 'codity doctor' exits 0 (Codity is configured), run 'codity review --staged' before any commit touching production code; HIGH-severity findings are blocking; MEDIUM-severity findings require inline acknowledgement in the commit message; setup is via 'specsmith integrate codity --project-dir .'.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §39
- **Test_Ids:** ['TEST-357']

## REQ-356. codity-ai-review Governance Skill in Skills Catalog
- **ID:** REQ-356
- **Title:** codity-ai-review Governance Skill in Skills Catalog
- **Description:** specsmith MUST include a 'codity-ai-review' SkillEntry in the governance domain skills catalog. The skill MUST document: Codity CLI install command (curl install script), codity login (magic-link browser auth), codity init (per-repo initialisation), daily commands (review --staged, scan --staged, test-gen --staged, doctor), the AGENTS.md blocking rule (HIGH severity = commit blocked, MEDIUM = acknowledgement required), CI integration via specsmith integrate codity, GitHub App setup, GitLab PAT setup (codity config set-pat --provider gitlab), and Azure DevOps PAT setup. The skill MUST be tagged with codity, ai-review, code-review, security, test-gen, ci, github, gitlab, azure, staged, pre-commit and discoverable via specsmith skill list.
- **Status:** implemented
- **Source:** ARCHITECTURE.md §39
- **Test_Ids:** ['TEST-356']

