chore(aiwg): adopt shared BT6 maintainer workflow (#148)

* docs(policy): allow low-impact contributor courtesy cleanup

* chore(aiwg): migrate to shared BT6 maintainer plugin

* chore: reconcile delivery validation

.aiwg/requirements/UC-001.md

@@ -1,21 +1,123 @@
 # UC-001 — Conduct a Scoped Security Mission
 
-**Primary actor:** Authorized operator  
-**Goal:** Execute a recon-to-report mission against an explicitly authorized target.
+## Metadata
 
-## Main Flow
+- **ID:** UC-001
+- **Status:** Baselined (brownfield)
+- **Level:** User goal
+- **Scope:** Mission, target, orchestration, arsenal, evidence, and reporting subsystems
+- **Primary actor:** Authorized operator
+- **Goal:** Execute a reconnaissance-to-report mission against an explicitly authorized target without exceeding the rules of engagement.
+- **Related stories:** US-01, US-02, US-04, US-05
+- **Quality drivers:** NFR-01, NFR-02, NFR-03, NFR-05, NFR-08
 
-1. Operator defines target and rules of engagement.
-2. System validates target/scope inputs and creates mission context.
-3. Admiral plans tasks and assigns operator roles.
-4. Operators invoke approved arsenal capabilities within scope.
-5. Tool outputs become evidence and candidate findings.
-6. Findings are verified and a report is produced.
+## Preconditions
 
-## Invariants
+- The operator has written authorization and has identified the target and allowed activity.
+- Required tools and model or connected-agent configuration are available.
+- The operator can review high-impact actions and retain evidence securely.
 
-- Out-of-scope public network access is denied.
-- Dangerous operations follow approval policy.
-- A finding must retain evidence/provenance.
+## Trigger
 
-**Implementation coverage:** `src/mission/`, `src/admiral/`, `src/operators/`, `src/orchestration/`, `src/target/`, `src/arsenal/`, `src/evidence/`, `src/analysis/`, and report/disclosure scripts.
+The operator starts a mission with a target definition and rules of engagement through a supported entry surface.
+
+## Main Success Scenario
+
+1. The operator supplies the target, allowed scope, objectives, and execution constraints.
+2. The system normalizes and validates the target and creates an authorized mission context.
+3. The Admiral produces a task plan and assigns work to operator roles.
+4. Each operator proposes tool activity against the authorized mission context.
+5. The runtime validates scope, arguments, approval class, and timeout before dispatch.
+6. Approved arsenal adapters execute and return structured observations.
+7. The system records raw evidence separately from candidate findings.
+8. Candidate findings are adjudicated or independently verified against retained evidence.
+9. The reporting path emits a result that identifies evidence and verification state.
+10. The operator reviews the result and controls any disclosure or external delivery.
+
+## Alternate Flows
+
+### A1 — Planning without a cloud API key
+
+At step 3, the operator selects a connected local coding agent or local OpenAI-compatible provider. The shared mission and safety behavior remains unchanged; UC-002 supplies the provider flow.
+
+### A2 — Read-only or non-dangerous operation
+
+At step 5, the requested tool is classified as non-dangerous. The system may dispatch without an interactive approval while still enforcing target scope and argument validation.
+
+### A3 — Candidate finding is refuted
+
+At step 8, verification cannot reproduce or substantiate the candidate. The system retains the evidence and refutation outcome but does not promote the candidate to a verified finding.
+
+## Exception Flows
+
+### E1 — Target is outside scope
+
+1. Scope validation rejects the target or derived destination.
+2. No network tool is dispatched and no target credential is attached.
+3. The system records a refusal suitable for operator diagnosis.
+
+### E2 — Dangerous action is not approved
+
+1. The runtime presents the action and relevant risk information for approval.
+2. The operator rejects or does not approve the action.
+3. Execution stops at the gate; the mission may continue with safer alternatives.
+
+### E3 — Tool, provider, or task times out
+
+1. The configured timeout terminates or abandons the bounded operation.
+2. The system records failure context without converting it into a successful observation.
+3. The planner may retry only through declared fallback behavior.
+
+## Postconditions
+
+### Success
+
+- Mission state records the completed activity and disposition.
+- Reported findings retain a path to evidence and verification state.
+- No tool execution or credential forwarding occurred outside authorized scope.
+
+### Failure
+
+- The system fails closed for authorization, scope, approval, and credential-routing failures.
+- Partial observations remain distinguishable from verified findings.
+
+## Special Requirements
+
+- **Safety:** Out-of-scope public network access is denied by deterministic controls, not model judgment alone.
+- **Authorization:** Real operations require an explicit authorized target context.
+- **Secret isolation:** Target headers are sent only to their configured exact origin.
+- **Evidence:** Finding claims identify retained evidence or a reproducible receipt.
+- **Testability:** CI exercises deterministic negative paths without live targets or paid models.
+
+## Acceptance Criteria
+
+- [ ] Given an authorized target, when a mission starts, then every dispatched network action carries the validated target context.
+- [ ] Given an unrelated public host, when a tool attempts access, then the action is rejected before dispatch.
+- [ ] Given a dangerous action, when approval is absent or rejected, then no corresponding tool process starts.
+- [ ] Given target-specific credentials, when a redirect or different origin is requested, then credentials are not forwarded.
+- [ ] Given a candidate finding, when it is reported as verified, then evidence and verification state are present.
+- [ ] Given a tool or reasoning timeout, when the deadline expires, then the mission records an explicit failure or declared fallback rather than a false success.
+
+## Design and Test Traceability
+
+| Concern | Design / implementation | Verification |
+| --- | --- | --- |
+| Mission lifecycle | `src/mission/`, `src/admiral/`, `src/orchestration/`, `src/operators/` | Mission, adjudication, agent-feedback, and parallel-agent tests |
+| Scope and authorization | `src/target/`, `src/opsec/`, `src/arsenal/approval.ts` | Scope-gate, approval-gate, validation, and target-header tests |
+| Evidence and findings | `src/evidence/`, `src/analysis/`, verification scripts | Evidence-integrity, report-redaction, and finding-verifier tests |
+
+## Open Issues
+
+- Quantified workload and concurrent mission baselines remain a planned measurement item (NFR-11).
+- Reliable swarm advantage over solo baselines is not an acceptance assumption for this use case.
+
+## References
+
+- @.aiwg/requirements/nfr-register.md — Safety, authorization, provenance, secret-isolation, and testability requirements.
+- @.aiwg/architecture/software-architecture-doc.md — Components and trust boundaries satisfying this flow.
+- @src/mission/index.ts — Mission state and lifecycle implementation.
+- @src/target/index.ts — Authorized-target representation and validation boundary.
+- @src/arsenal/approval.ts — Dangerous-tool approval policy.
+- @src/__tests__/arsenal-scope-gate.test.ts — Negative scope-containment evidence.
+- @src/__tests__/arsenal-approval-gate.test.ts — Approval enforcement evidence.
+- @src/__tests__/target-headers-static.test.ts — Exact-origin credential-routing evidence.

.aiwg/requirements/UC-002.md

@@ -1,13 +1,80 @@
 # UC-002 — Connect a Model or Coding Agent
 
-**Primary actor:** Operator or integrator  
-**Goal:** Use a hosted provider, local OpenAI-compatible model, or connected coding-agent CLI as the reasoning backbone.
+## Metadata
 
-## Main Flow
+- **ID:** UC-002
+- **Status:** Baselined (brownfield)
+- **Level:** User goal
+- **Scope:** Configuration, provider/model registry, LLM adapters, and connected local agents
+- **Primary actor:** Operator or integrator
+- **Goal:** Use a hosted provider, local OpenAI-compatible model, or authenticated coding-agent CLI as the reasoning backbone.
+- **Related story:** US-03
+- **Quality drivers:** NFR-05, NFR-06, NFR-07, NFR-08, NFR-11
 
-1. User selects/configures a provider or local agent.
-2. System resolves provider/model capabilities and credentials.
-3. Requests are routed with timeout and fallback behavior.
-4. Tool-capable orchestration consumes responses and records outcomes.
+## Preconditions
 
-**Implementation coverage:** `src/llm/`, `src/config/`, `src/agent/`, provider-model registry, setup and fallback tests.
+- At least one supported provider, local inference endpoint, or local agent executable is available.
+- Any required credential is supplied through the supported configuration mechanism.
+- UC-001 remains authoritative for tool execution and target safety.
+
+## Trigger
+
+The user selects a provider/model or connected local agent during setup or mission execution.
+
+## Main Success Scenario
+
+1. The user selects a provider family and model or a connected agent.
+2. Configuration resolves the provider, base URL, credential source, and capability metadata.
+3. The adapter validates required settings without exposing secret values.
+4. The orchestration layer submits a bounded reasoning request through the shared interface.
+5. The adapter translates the request and returns normalized content and tool proposals.
+6. The runtime treats the response as untrusted input and applies shared tool, target, and evidence controls.
+7. The mission records the selected reasoning path and its outcome.
+
+## Alternate Flows
+
+- **A1 — Connected local agent:** Resolve the executable and working environment; no new cloud API key is required.
+- **A2 — Local OpenAI-compatible endpoint:** Route to the configured base URL while applying local-address handling and timeouts.
+- **A3 — Declared fallback:** If the primary path fails in a configured, recoverable manner, use the declared fallback and record both outcomes.
+
+## Exception Flows
+
+- Missing credentials or executable: fail configuration validation with a redacted, actionable error.
+- Unsupported provider/model combination: reject before a mission request is submitted.
+- Timeout or malformed response: record failure and do not reinterpret incomplete output as a valid tool instruction.
+- Provider attempts a privileged action: route the proposal through the same approval and scope gates as every other provider.
+
+## Postconditions
+
+- The reasoning path and result are explicit in mission state or diagnostics.
+- Credentials remain isolated to configuration/provider boundaries.
+- Provider choice does not bypass deterministic execution controls.
+
+## Acceptance Criteria
+
+- [ ] A connected local agent can perform mission planning without a newly supplied cloud API key.
+- [ ] Provider selection resolves only supported provider/model combinations.
+- [ ] Local and hosted base URLs route to their intended adapter without credential crossover.
+- [ ] Timeouts produce an explicit error or declared fallback outcome.
+- [ ] Model-generated tool proposals still require UC-001 scope and approval enforcement.
+- [ ] Configuration and error output redact provider secrets.
+
+## Design and Test Traceability
+
+| Concern | Design / implementation | Verification |
+| --- | --- | --- |
+| Provider/model selection | `src/config/`, `src/config/provider-models.ts` | Provider-model and provider-specific tests |
+| Common reasoning interface | `src/llm/index.ts`, `src/agent/` | Local-agent selection, path, tool-calling, and fallback tests |
+| Bounded execution | Orchestration and configuration timeout controls | Model-fallback and agent-error tests |
+
+## References
+
+- @.aiwg/architecture/adr-002.md — Provider-neutral reasoning decision.
+- @.aiwg/architecture/software-architecture-doc.md — Provider adapter and trust-boundary design.
+- @src/config/index.ts — Runtime configuration behavior.
+- @src/config/provider-models.ts — Provider/model capability registry.
+- @src/llm/index.ts — Shared hosted/local LLM interface.
+- @src/agent/local-agents.ts — Connected local-agent resolution.
+- @src/__tests__/local-agent-selection.test.ts — Local-agent selection evidence.
+- @src/__tests__/provider-models.test.ts — Registry and compatibility evidence.
+- @scripts/test-model-fallback.mjs — Declared fallback verification.

.aiwg/requirements/UC-003.md

@@ -1,13 +1,79 @@
 # UC-003 — Operate Through Supported Surfaces
 
-**Primary actor:** Operator or integrating client  
-**Goal:** Start and inspect capabilities through CLI, War Room/HTTP, library, or MCP.
+## Metadata
 
-## Main Flow
+- **ID:** UC-003
+- **Status:** Baselined (brownfield)
+- **Level:** User goal
+- **Scope:** CLI, library, localhost HTTP/War Room, and MCP adapters
+- **Primary actor:** Operator or integrating client
+- **Goal:** Start and inspect supported capabilities through an appropriate surface while preserving shared domain behavior.
+- **Related stories:** US-02, US-06
+- **Quality drivers:** NFR-04, NFR-06, NFR-07, NFR-08
 
-1. User selects an entry surface.
-2. Surface validates and translates input into shared domain operations.
-3. Shared mission, target, arsenal, and reporting services execute.
-4. Results return in surface-appropriate form.
+## Preconditions
 
-**Implementation coverage:** `src/cli.ts`, `src/server.ts`, `src/index.ts`, `src/mcp-server.ts`, `src/ui/`.
+- The selected surface is installed and configured.
+- The operation is supported by that surface; MCP is intentionally narrower than the full application.
+- Any real target activity satisfies UC-001 preconditions.
+
+## Trigger
+
+The actor invokes a CLI command, library export, localhost HTTP route, browser action, or MCP tool.
+
+## Main Success Scenario
+
+1. The selected adapter parses and validates surface-specific input.
+2. It translates the request into a shared domain operation.
+3. Shared mission, target, provider, arsenal, and reporting services execute the request.
+4. The adapter translates the result into the documented surface contract.
+5. The actor receives structured state, output, or an actionable error.
+
+## Alternate Flows
+
+- **CLI/library:** Execute in the current Node.js process with terminal or typed return values.
+- **War Room/HTTP:** Bind to loopback by default and serve browser/API responses after Host and origin validation.
+- **MCP:** Expose only declared MCP tools over stdio and reuse common validation for supported reconnaissance.
+
+## Exception Flows
+
+- Invalid schema or arguments: reject at the adapter boundary before domain execution.
+- Invalid Host/origin: reject the HTTP request before a sensitive route is reached.
+- Unsupported MCP capability: return a documented MCP error rather than silently invoking a broader internal API.
+- Domain failure: preserve the underlying failure semantics and do not convert it to a surface-specific success.
+
+## Postconditions
+
+- Equivalent supported operations preserve shared safety and domain invariants across surfaces.
+- The result conforms to the chosen surface’s documented schema.
+- Surface-specific exposure does not broaden privileges.
+
+## Acceptance Criteria
+
+- [ ] CLI and library operations reach shared domain modules rather than duplicate mission logic.
+- [ ] The HTTP server defaults to loopback and rejects invalid Host/origin combinations.
+- [ ] MCP input is schema-validated and returns structured output for supported tools.
+- [ ] Unsupported operations fail explicitly on the selected surface.
+- [ ] Contract changes are typechecked, tested, documented, and visible during release review.
+
+## Design and Test Traceability
+
+| Surface | Implementation | Verification |
+| --- | --- | --- |
+| CLI | `src/cli.ts` | Build, CLI smoke, and validation tests |
+| Library | `src/index.ts` | Export and index tests |
+| HTTP / War Room | `src/server.ts`, `src/ui/` | Local API hardening and proxy tests |
+| MCP | `src/mcp-server.ts` | Schema/static validation and documentation review |
+
+## References
+
+- @.aiwg/architecture/adr-001.md — Local-first modular-monolith decision.
+- @.aiwg/architecture/software-architecture-doc.md — Delivery adapter and API surface design.
+- @src/cli.ts — Command-line adapter.
+- @src/index.ts — Library composition surface.
+- @src/server.ts — Local HTTP and War Room adapter.
+- @src/mcp-server.ts — MCP stdio adapter.
+- @src/__tests__/local-api-hardening-static.test.ts — HTTP boundary evidence.
+- @src/__tests__/validation.test.ts — Input-validation evidence.
+- @docs/API_REFERENCE.md — Human-readable HTTP contract.
+- @docs/MCP_GUIDE.md — Human-readable MCP contract.

.aiwg/requirements/UC-004.md

@@ -1,15 +1,78 @@
 # UC-004 — Analyze a Source Code Repository
 
-**Primary actor:** Security researcher  
-**Goal:** Ingest supported source languages and identify evidence-backed vulnerability candidates.
+## Metadata
 
-## Main Flow
+- **ID:** UC-004
+- **Status:** Baselined; multi-language coverage remains experimental
+- **Level:** User goal
+- **Scope:** Repository ingest, structural extraction, white-box analysis, evidence, and finding verification
+- **Primary actor:** Security researcher
+- **Goal:** Ingest an authorized repository and identify evidence-backed vulnerability candidates without overstating language or analysis maturity.
+- **Related story:** US-07
+- **Quality drivers:** NFR-03, NFR-08, NFR-09, NFR-11
 
-1. Researcher supplies an authorized repository.
-2. Ingest identifies language and extracts structural blocks.
-3. Decomposition and analysis produce candidate findings.
-4. Results are graded or verified against evidence.
+## Preconditions
 
-**Implementation coverage:** `src/recon/code-ingest.ts`, `src/recon/ts-parse.ts`, `src/recon/ts-grammars.ts`, `src/recon/whitebox.ts`, `src/analysis/`, decomposition scripts.
+- The researcher is authorized to analyze the repository.
+- Input size and file types satisfy configured containment limits.
+- Required parser grammars or safe fallback behavior are available.
 
-**Maturity note:** Multi-language ingestion is experimental even where benchmark results are proven.
+## Trigger
+
+The researcher selects a repository or supported source input for white-box analysis.
+
+## Main Success Scenario
+
+1. The system enumerates eligible files under configured containment and size limits.
+2. Ingest identifies the language and selects the corresponding structural parser.
+3. The parser extracts bounded code blocks with source locations.
+4. Analysis processes the blocks and emits candidate observations with source evidence.
+5. Candidate findings are graded, refuted, or verified against the cited code.
+6. Results report language/parser maturity and verification status.
+
+## Alternate Flows
+
+- A supported Tree-sitter grammar extracts structural blocks for the detected language.
+- The Python-specific path uses its specialized parser where configured.
+- A safe documented fallback may produce reduced-fidelity blocks while marking the limitation.
+
+## Exception Flows
+
+- Unsupported input: fail safely with an explicit unsupported-language result.
+- Oversized, recursive, binary, or escaping input: containment limits reject or bound processing.
+- Parser failure: record the error and do not fabricate structural evidence.
+- Unverified candidate: retain as a candidate or refuted result, never silently promote to verified.
+
+## Postconditions
+
+- Each reported code observation can identify its source file and region.
+- Parser limitations and experimental maturity remain visible.
+- Repository content never grants authority to override analysis or safety instructions.
+
+## Acceptance Criteria
+
+- [ ] Supported grammars extract source blocks with stable file and line context.
+- [ ] Unsupported or malformed input fails explicitly and safely.
+- [ ] Ingest limits prevent unbounded traversal or oversized processing.
+- [ ] Findings preserve source evidence and verification state.
+- [ ] Documentation does not generalize benchmark success beyond the evaluated corpus/language path.
+
+## Design and Test Traceability
+
+| Concern | Implementation | Verification |
+| --- | --- | --- |
+| Input containment | `src/recon/code-ingest.ts`, `src/recon/whitebox.ts` | Ingest-limit and white-box-containment tests |
+| Structural parsing | `src/recon/ts-parse.ts`, grammar registry | Parser, grammar, fallback, and adversarial tests |
+| Evidence-backed output | `src/analysis/`, finding verification scripts | Verification and report-redaction tests |
+
+## References
+
+- @.aiwg/architecture/software-architecture-doc.md — Reconnaissance and source-ingest component design.
+- @.aiwg/architecture/vision-alignment.md — Maturity boundary for source analysis claims.
+- @src/recon/code-ingest.ts — Repository ingest and limits.
+- @src/recon/ts-parse.ts — Structural parser implementation.
+- @src/recon/whitebox.ts — White-box analysis composition.
+- @src/__tests__/ingest-limits.test.ts — Resource-containment evidence.
+- @src/__tests__/ts-parse-adversarial.test.ts — Adversarial parser evidence.
+- @src/__tests__/whitebox-containment.test.ts — Path and analysis containment evidence.
+- @scripts/verify-finding.mjs — Finding-verification path.

.aiwg/requirements/UC-005.md

@@ -1,13 +1,81 @@
 # UC-005 — Reproduce Claims and Benchmark Results
 
-**Primary actor:** Maintainer, contributor, or evaluator  
-**Goal:** Re-derive public capability claims from committed data and detect fitting or provenance regressions.
+## Metadata
 
-## Main Flow
+- **ID:** UC-005
+- **Status:** Baselined (brownfield)
+- **Level:** User goal
+- **Scope:** Benchmark corpora, manifests, ground truth, receipts, graders, claim verification, and CI
+- **Primary actor:** Maintainer, contributor, or evaluator
+- **Goal:** Re-derive public capability claims from versioned evidence and detect grading, provenance, or fitting regressions.
+- **Related stories:** US-08, US-09, US-10
+- **Quality drivers:** NFR-03, NFR-08, NFR-09
 
-1. Evaluator runs claim or benchmark verification.
-2. Harness reads committed corpus, receipts, and ground truth.
-3. Scores and verdicts are recomputed.
-4. CI fails if claims, provenance, or anti-fitting invariants do not hold.
+## Preconditions
 
-**Implementation coverage:** `bench/`, `scripts/verify-claims.mjs`, model/benchmark scripts, anti-fitting tests, `.github/workflows/ci.yml`.
+- The evaluated corpus, manifest, ground truth, and required receipts are available under their documented retention policy.
+- The evaluator uses the declared harness, metric, model/configuration identity, and command.
+- Sensitive or third-party material is handled according to repository policy.
+
+## Trigger
+
+The evaluator runs claim verification, a benchmark verifier, or the corresponding CI gate.
+
+## Main Success Scenario
+
+1. The harness loads the versioned corpus/manifest and ground truth.
+2. It validates required receipt identity and provenance fields.
+3. The grader recomputes per-case outcomes from retained evidence.
+4. Aggregate scores and headline verdicts are recomputed using the declared metric.
+5. Anti-fitting checks verify separation and policy invariants.
+6. The verifier compares derived values with public claims.
+7. It emits a pass/fail result and enough context to reproduce a mismatch.
+8. CI blocks integration when a required claim, provenance, or anti-fitting invariant fails.
+
+## Alternate Flows
+
+- A local evaluator runs only deterministic verification against committed artifacts.
+- A live benchmark run produces new receipts, followed by deterministic grading in a separate step.
+- Raw sensitive transcripts may be withheld while a declared, re-derivable graded receipt remains available; the documentation must state the reproduction boundary.
+
+## Exception Flows
+
+- Missing or stale evidence: fail the affected claim rather than substituting an estimate.
+- Model/provider outage during a live run: classify as infrastructure/run failure, not model success or failure.
+- Ground-truth or manifest mismatch: stop grading and identify the conflicting artifact.
+- Suspected self-fitting or corpus leakage: fail the anti-fitting gate pending review.
+
+## Postconditions
+
+- Every passing headline claim maps to the evaluated corpus, metric, and retained evidence.
+- Failed claims identify the discrepant artifact or value.
+- Benchmark scope is not generalized to unsupported product maturity.
+
+## Acceptance Criteria
+
+- [ ] `npm run verify-claims` derives required public claims from repository artifacts.
+- [ ] Seeded claim mismatches, missing provenance, or fitting violations cause a non-zero gate result.
+- [ ] Receipts identify the relevant corpus/model/configuration and evaluation outcome.
+- [ ] Live-run infrastructure failures remain distinct from evaluated model verdicts.
+- [ ] Maturity documentation limits conclusions to the evaluated scope.
+
+## Design and Test Traceability
+
+| Concern | Implementation | Verification |
+| --- | --- | --- |
+| Claim derivation | `scripts/verify-claims.mjs`, benchmark manifests/receipts | Claim verification in CI |
+| Finding grading | Verification/refutation and grading scripts | Script self-tests and benchmark tests |
+| Anti-fitting | No-fitting and no-self-fitting checks | Seeded anti-fitting tests |
+| Gate enforcement | `.github/workflows/ci.yml` | CI job status and local command parity |
+
+## References
+
+- @.aiwg/architecture/adr-004.md — Evidence-derived public-claims decision.
+- @.aiwg/architecture/adr-005.md — Current-state versus research-vision decision.
+- @.aiwg/architecture/vision-alignment.md — Maturity interpretation rules.
+- @scripts/verify-claims.mjs — Deterministic public-claim verifier.
+- @scripts/verify-finding.mjs — Finding verification.
+- @scripts/refute-finding.mjs — Candidate-refutation path.
+- @scripts/test-no-fitting.mjs — Anti-fitting evidence.
+- @scripts/test-no-self-fitting.mjs — Self-fitting prevention evidence.
+- @.github/workflows/ci.yml — Required automated gates.

.aiwg/requirements/nfr-register.md

@@ -1,16 +1,105 @@
 # Non-Functional Requirements Register
 
-| ID | Requirement | Verification |
-| --- | --- | --- |
-| NFR-01 Safety | Networked tools must deny off-scope public hosts by default. | Scope-containment tests and smoke/gate suites |
-| NFR-02 Authorization | Real operations require an explicit authorized target context. | API/mission validation tests and doctrine audit |
-| NFR-03 Provenance | Public claims and findings must trace to committed or retained evidence. | `verify-claims`, finding verifier, provenance gate |
-| NFR-04 Local security | HTTP server defaults to loopback and guards Host/origin. | Server tests and Docker configuration inspection |
-| NFR-05 Secret isolation | Target credentials are injected only for their configured exact origin. | Target-header tests |
-| NFR-06 Portability | Core build supports Node.js 18+ on common desktop/server environments. | CI plus documented install matrix |
-| NFR-07 Compatibility | CLI, HTTP, library, and MCP contracts change intentionally and visibly. | Typecheck, contract tests, release review |
-| NFR-08 Testability | Deterministic paths must run without live model/network dependencies in CI. | Main CI workflow |
-| NFR-09 Honesty | Experimental/research/roadmap work must not be described as stable. | Vision alignment and claim audit |
-| NFR-10 Recoverability | Updates preserve configured sensitive artifact paths. | Update self-tests |
-| NFR-11 Performance | Timeout controls bound local-agent, task, and planning calls. | Timeout/fallback tests; future percentile baseline |
-| NFR-12 Maintainability | Major trust-boundary and platform decisions require ADR updates. | Architecture review checklist |
+## Metadata and Scope
+
+- **Status:** Baselined for the current brownfield architecture
+- **Owner:** Architecture and safety stewards
+- **Review cadence:** Every iteration and whenever a trust boundary, delivery surface, provider contract, or maturity label changes
+- **Measurement rule:** A requirement without a repeatable verification method is aspirational and cannot pass a phase gate.
+
+## Requirement Register
+
+| ID | Category | Measurable requirement | Verification and pass condition | Design source | Status |
+| --- | --- | --- | --- | --- | --- |
+| NFR-01 | Safety | Built-in network-capable tools must deny unrelated public hosts by default after a mission target is established. | Scope-gate negative tests pass for unrelated public destinations; no adapter bypass is accepted. | ADR-003; SAD §§5, 10 | Active |
+| NFR-02 | Authorization | Real target operations require an explicit authorized target context before dispatch. | Mission/API validation and arsenal approval suites reject absent authorization context. | UC-001; ADR-003 | Active |
+| NFR-03 | Provenance | Public claims and verified findings must trace to retained evidence or a reproducible versioned receipt. | Claim/finding verifiers and provenance CI gate pass; unsupported claims fail closed. | UC-005; ADR-004 | Active |
+| NFR-04 | Local security | HTTP binds to loopback by default and rejects invalid Host/origin combinations. | Server static/behavior tests and Docker binding inspection pass. | UC-003; ADR-001 | Active |
+| NFR-05 | Secret isolation | Target credentials and headers may be forwarded only to their configured exact origin and must be redacted from diagnostics. | Target-header and credential-redaction negative tests pass. | UC-001; ADR-003 | Active |
+| NFR-06 | Portability | The core build supports Node.js 18+ and the repository’s declared desktop/server environments. | CI install, build, typecheck, and documented platform smoke checks pass. | ADR-001; ADR-002 | Active |
+| NFR-07 | Compatibility | CLI, HTTP, library, MCP, provider, and evidence contracts change only with visible documentation, type, and test updates. | Contract/type tests pass and release review identifies breaking changes. | UC-002; UC-003 | Active |
+| NFR-08 | Testability | Deterministic safety, parser, provider-routing, evidence, and claim paths run in CI without live targets or paid model dependencies. | Required CI jobs execute from fixtures/committed artifacts and pass. | Test strategy | Active |
+| NFR-09 | Claim honesty | Experimental, research, and roadmap capabilities must not be represented as stable; benchmark claims remain corpus-scoped. | Documentation/maturity audit and claim verifier report no contradictory status. | UC-005; ADR-005 | Active; automation gap tracked |
+| NFR-10 | Recoverability | Update workflows preserve configured sensitive or expensive local artifact paths and provide a clear failure result. | Update self-tests verify protected-path survival and rollback/failure behavior. | Risk R-07 | Active |
+| NFR-11 | Performance | Every local-agent, planning, task, and external-tool operation has a configured finite timeout; percentile workload baselines must be recorded before performance promotion claims. | Timeout/fallback tests pass; benchmark receipt states workload, environment, and percentile when a performance claim is made. | UC-001; UC-002; UC-004 | Partially measured |
+| NFR-12 | Maintainability | Any new delivery surface, persistence system, privilege boundary, provider contract, generic execution path, or maturity promotion requires an ADR and traceability update. | Architecture review checklist finds an accepted/proposed ADR and updated UC/US/NFR matrices. | SAD §10; ADR-005 | Active |
+
+## Quality-Attribute Detail
+
+### 1. Usability and Accessibility
+
+- CLI, HTTP, and MCP errors must identify invalid input or unsupported behavior without exposing secrets.
+- The browser surface should retain keyboard-accessible core controls; a formal WCAG conformance level is not yet claimed.
+- Documentation distinguishes operator, developer, API, and MCP entry paths.
+
+### 2. Reliability and Recoverability
+
+- Authorization, scope, approval, origin, and evidence-verification failures fail closed.
+- Timeouts bound external reasoning/tool work; retry is permitted only where a declared fallback avoids duplicate unsafe effects.
+- Local reports/evidence require an operator-owned backup and retention policy; the project does not claim centralized durability.
+
+### 3. Performance and Scale
+
+- The current product is local/self-hosted; no hosted fleet SLO or concurrent-user capacity is claimed.
+- Any future latency/throughput statement must name workload, hardware/runtime, sample count, percentile, and receipt.
+- Source-ingest and concurrent mission baselines remain an explicit construction item.
+
+### 4. Supportability and Observability
+
+- Build, doctor, preflight, smoke, test, claim, and provenance gates provide local diagnostic layers.
+- Mission/tool failures must retain enough redacted context to distinguish validation, provider, timeout, process, parse, and verification failures.
+- Centralized metrics, traces, paging, and production SLO dashboards are N/A for the current self-hosted baseline; hosted evolution requires a new baseline.
+
+### 5. Security and Privacy
+
+- Model output, target content, imported code, external tools, and browser requests are untrusted inputs.
+- Secrets must use supported configuration/environment mechanisms, never committed values.
+- Evidence and disclosures may be restricted or embargoed and remain operator-controlled.
+- T3MP3ST provides product controls and usage guidance; it does not claim organizational certification or legal authorization on the operator’s behalf.
+
+### 6. Compliance and Legal Constraints
+
+- Authorized use and coordinated disclosure are mandatory operating constraints.
+- AGPL-3.0-or-later governs distribution of this repository.
+- GDPR, CCPA, PCI DSS, HIPAA, CFAA, and local law applicability depends on deployment and engagement context; repository mention is not certification.
+
+### 7. Environmental and Design Constraints
+
+- Runtime: Node.js 18+ with TypeScript/ESM.
+- Default architecture: local-first modular monolith with filesystem artifacts and no application database.
+- Default HTTP exposure: loopback.
+- Hosted multi-tenancy, distributed workers, or centralized retained customer data require new architecture, threat, retention, and compliance decisions.
+
+### 8. Documentation and Localization
+
+- Stable/experimental/research/roadmap labels must remain consistent across product and SDLC documentation.
+- Interface changes update human-facing API/MCP/operator documentation in the same change.
+- English is the current maintained documentation language; no localization commitment is claimed.
+
+## Assumptions, Dependencies, and Open Issues
+
+- Operators control host security, authorization records, evidence retention, and disclosure decisions.
+- External model/tool availability and behavior are not controlled by T3MP3ST.
+- Open measurements: source-ingest percentiles, concurrent mission resource profiles, and startup/shutdown timing.
+- Open governance: machine-checkable maturity-label consistency and complete network-adapter safety inventory.
+
+## Traceability Summary
+
+| Requirement group | Use cases | Architecture decisions | Primary test evidence |
+| --- | --- | --- | --- |
+| Safety / authorization / secrets | UC-001 | ADR-003 | Arsenal scope/approval, target-header, redaction tests |
+| Provider / portability / compatibility | UC-002, UC-003 | ADR-001, ADR-002 | Provider registry, local-agent, API hardening, typecheck |
+| Evidence / honesty | UC-004, UC-005 | ADR-004, ADR-005 | Finding verification, claim, provenance, anti-fitting gates |
+| Maintainability / recoverability | All | ADR-001, ADR-005 | Update self-tests, architecture and release review |
+
+## References
+
+- @.aiwg/requirements/UC-001.md — Scoped mission behavior.
+- @.aiwg/requirements/UC-002.md — Provider and local-agent behavior.
+- @.aiwg/requirements/UC-003.md — Delivery-surface behavior.
+- @.aiwg/requirements/UC-004.md — Source-analysis behavior.
+- @.aiwg/requirements/UC-005.md — Claim and benchmark reproducibility.
+- @.aiwg/architecture/software-architecture-doc.md — Architectural tactics and traceability matrices.
+- @.aiwg/testing/test-strategy.md — Verification layers and quality gates.
+- @SECURITY.md — Product safety, vulnerability reporting, and authorized-use policy.
+- @.github/workflows/ci.yml — Automated verification implementation.

.aiwg/requirements/user-stories.md

@@ -1,14 +1,140 @@
-# User Stories
+# User Story Register
 
-| ID | Story | Acceptance signal |
-| --- | --- | --- |
-| US-01 | As an operator, I can define an authorized target and scope before execution. | Scope receipt exists; invalid/off-scope target is refused. |
-| US-02 | As an operator, I can launch and monitor a mission from the CLI or War Room. | Shared mission state is visible through both surfaces. |
-| US-03 | As an operator, I can connect an already-authenticated local coding agent. | Mission planning works without a new cloud API key. |
-| US-04 | As an operator, I can approve or reject dangerous actions. | Approval decision is enforced before execution. |
-| US-05 | As a researcher, I can preserve evidence behind each finding. | Finding links to tool/model evidence and verification state. |
-| US-06 | As an integrator, I can access supported reconnaissance through MCP. | MCP schema validates and returns structured output. |
-| US-07 | As a researcher, I can ingest supported source languages. | Supported grammar extracts blocks; unsupported input fails safely. |
-| US-08 | As a maintainer, I can reproduce headline claims. | `npm run verify-claims` succeeds from committed artifacts. |
-| US-09 | As a contributor, I can see whether a feature is stable, experimental, research, or roadmap. | Maturity classification is explicit in docs/alignment matrix. |
-| US-10 | As a maintainer, I can detect prompt, provenance, and fitting regressions in CI. | Corresponding CI gates fail on seeded violations. |
+## Register Metadata
+
+- **Status:** Baselined brownfield stories
+- **Owner:** Product/requirements steward
+- **Definition of ready:** Actor, value, scope, linked UC/NFR, testable acceptance criteria, and implementation evidence are present.
+- **Definition of done:** Acceptance evidence passes; documentation and traceability are updated; no critical safety or security finding remains.
+
+## Summary
+
+| ID | Priority | Parent use case | Status | Story |
+| --- | --- | --- | --- | --- |
+| US-01 | Critical | UC-001 | Implemented | Define an authorized target and scope before execution. |
+| US-02 | High | UC-001, UC-003 | Implemented | Launch and monitor a mission from supported surfaces. |
+| US-03 | High | UC-002 | Implemented | Connect an authenticated local coding agent. |
+| US-04 | Critical | UC-001 | Implemented | Approve or reject dangerous actions. |
+| US-05 | Critical | UC-001 | Implemented | Preserve evidence behind each finding. |
+| US-06 | High | UC-003 | Implemented (narrow surface) | Access supported reconnaissance through MCP. |
+| US-07 | High | UC-004 | Experimental | Ingest supported source languages safely. |
+| US-08 | Critical | UC-005 | Implemented | Reproduce headline claims. |
+| US-09 | High | UC-005 | Implemented; continuous review | See capability maturity clearly. |
+| US-10 | Critical | UC-005 | Implemented | Detect prompt, provenance, and fitting regressions in CI. |
+
+## Story Cards
+
+### US-01 — Define Authorized Scope
+
+**As an** authorized operator, **I want** to define a target and allowed scope before execution **so that** real operations remain within written authorization.
+
+- **Value:** Prevents off-target activity and creates the context required by every safety gate.
+- **Scope:** Target normalization, rules of engagement, scope receipt, and pre-dispatch validation; excludes obtaining legal authorization.
+- **NFRs:** NFR-01, NFR-02, NFR-05
+- **Acceptance:** Given a valid target, a mission context/receipt is created; given an unrelated public host, execution is refused before dispatch; target credentials never cross origins.
+- **Evidence:** Target, scope-gate, and target-header implementation/tests.
+
+### US-02 — Launch and Monitor a Mission
+
+**As an** operator, **I want** to launch and inspect mission state from the CLI or War Room **so that** I can control long-running work through the surface that fits my workflow.
+
+- **Value:** Makes shared mission behavior observable without creating separate execution engines.
+- **Scope:** Mission create/start/state/results through supported surfaces; excludes distributed fleet scheduling.
+- **NFRs:** NFR-04, NFR-07, NFR-11
+- **Acceptance:** Both surfaces reach shared mission state; invalid surface input fails before execution; timeout/failure state is visible and not reported as success.
+- **Evidence:** CLI, server, mission, and local-API hardening code/tests.
+
+### US-03 — Connect a Local Coding Agent
+
+**As an** operator, **I want** to use an already-authenticated local coding agent **so that** mission planning can work without a new cloud API key.
+
+- **Value:** Preserves local/keyless operation and provider choice.
+- **Scope:** Discovery, selection, path resolution, request/response normalization, tool proposal handling; excludes bypassing tool controls.
+- **NFRs:** NFR-05, NFR-06, NFR-08, NFR-11
+- **Acceptance:** A supported local agent is resolved and selected; missing executables fail explicitly; tool proposals pass through shared scope/approval controls; credentials are not invented or exposed.
+- **Evidence:** Local-agent module plus selection, path-resolution, home, tool-calling, and fallback tests.
+
+### US-04 — Control Dangerous Actions
+
+**As an** operator, **I want** to approve or reject dangerous actions **so that** high-impact execution reflects explicit human intent.
+
+- **Value:** Creates a deterministic human-control boundary below model reasoning.
+- **Scope:** Risk classification, approval prompt/decision, and dispatch gate; excludes making an unsafe action safe merely by approval.
+- **NFRs:** NFR-01, NFR-02
+- **Acceptance:** No dangerous action dispatches without approval; rejection is final for that request; approval does not bypass target scope or validation.
+- **Evidence:** Arsenal approval implementation and approval-gate tests.
+
+### US-05 — Preserve Finding Evidence
+
+**As a** researcher, **I want** every finding to retain its evidence and verification state **so that** reports are defensible and candidates are not mistaken for verified vulnerabilities.
+
+- **Value:** Reduces false positives and supports coordinated disclosure.
+- **Scope:** Evidence capture, integrity, redaction, candidate/verified/refuted state, and report linkage.
+- **NFRs:** NFR-03, NFR-05
+- **Acceptance:** Verified findings link to retained evidence; redaction removes sensitive values from report paths; failed verification remains candidate/refuted.
+- **Evidence:** Evidence vault/gate, analysis report, verifier/refuter, integrity and redaction tests.
+
+### US-06 — Use Supported MCP Reconnaissance
+
+**As an** integrator, **I want** supported reconnaissance exposed through MCP **so that** an MCP client can invoke a narrow structured capability.
+
+- **Value:** Enables agent/tool interoperability without exposing the full internal runtime.
+- **Scope:** Declared MCP tools, input schema, stdio transport, structured response; excludes undocumented mission/arsenal access.
+- **NFRs:** NFR-07, NFR-08
+- **Acceptance:** Valid input returns the documented structure; invalid input returns an MCP error; unsupported capabilities are not silently routed to broader APIs.
+- **Evidence:** MCP server and MCP guide, validated by type/build and interface review.
+
+### US-07 — Ingest Supported Source Languages
+
+**As a** security researcher, **I want** supported source languages converted into bounded structural blocks **so that** white-box analysis can cite the relevant code.
+
+- **Value:** Extends evidence-backed analysis beyond a single source language while preserving honest maturity claims.
+- **Scope:** Language detection, grammar selection, bounded parsing, safe fallback, source locations; excludes universal correctness claims.
+- **NFRs:** NFR-08, NFR-09, NFR-11
+- **Acceptance:** Supported grammars produce located blocks; unsupported/malformed/oversized inputs fail safely; experimental maturity remains explicit.
+- **Evidence:** Ingest/parser/white-box modules and grammar, adversarial, fallback, multilang, and containment tests.
+
+### US-08 — Reproduce Headline Claims
+
+**As a** maintainer, **I want** headline claims recomputed from versioned evidence **so that** releases do not publish stale or fabricated performance results.
+
+- **Value:** Makes public claims auditable and regression-sensitive.
+- **Scope:** Declared committed claims and receipts; excludes results whose licensed/sensitive raw source cannot be retained unless the reproduction boundary is disclosed.
+- **NFRs:** NFR-03, NFR-09
+- **Acceptance:** `npm run verify-claims` succeeds for consistent evidence and fails on seeded mismatch or missing required provenance.
+- **Evidence:** Claim verifier, benchmark artifacts, and CI claim/provenance gates.
+
+### US-09 — See Capability Maturity
+
+**As a** contributor or user, **I want** each capability labeled stable, experimental, research, or roadmap **so that** I can distinguish implemented guarantees from direction.
+
+- **Value:** Prevents architecture and product decisions from relying on aspirational claims.
+- **Scope:** README/features/SAD/vision alignment and promotion criteria.
+- **NFRs:** NFR-09, NFR-12
+- **Acceptance:** Status is explicit and consistent in authoritative docs; promotion includes safety tests, operational path, documentation, and reproducible evidence.
+- **Evidence:** Vision-alignment matrix, ADR-005, claim audit, and planned consistency automation.
+
+### US-10 — Detect Integrity Regressions in CI
+
+**As a** maintainer, **I want** prompt, provenance, claim, and fitting regressions to fail CI **so that** unsafe or misleading changes cannot merge silently.
+
+- **Value:** Converts research/evidence policy into repeatable release gates.
+- **Scope:** Deterministic audit jobs and seeded negative tests; excludes paid/live benchmark availability.
+- **NFRs:** NFR-03, NFR-08, NFR-09
+- **Acceptance:** Seeded prompt/provenance/fitting violations fail the corresponding command and required CI job; infrastructure failures remain distinct from evaluated model results.
+- **Evidence:** CI workflow, anti-fitting tests, provenance gate, prompt audit, and claim verifier.
+
+## INVEST and Readiness Assessment
+
+The stories are independently reviewable but share cross-cutting safety constraints; each delivers operator/maintainer value, has bounded scope, and contains pass/fail acceptance signals. Story-point estimates and sprint assignment are intentionally absent because the stories describe a brownfield baseline, not a newly estimated backlog. Future change slices derived from them must be sized in the iteration plan.
+
+## References
+
+- @.aiwg/requirements/UC-001.md — Parent flow for US-01, US-02, US-04, and US-05.
+- @.aiwg/requirements/UC-002.md — Parent flow for US-03.
+- @.aiwg/requirements/UC-003.md — Parent flow for US-02 and US-06.
+- @.aiwg/requirements/UC-004.md — Parent flow for US-07.
+- @.aiwg/requirements/UC-005.md — Parent flow for US-08 through US-10.
+- @.aiwg/requirements/nfr-register.md — Cross-cutting quality constraints.
+- @.aiwg/architecture/software-architecture-doc.md — Implementing components and interfaces.
+- @.aiwg/testing/test-strategy.md — Acceptance and regression strategy.