t3mp3st/.aiwg/requirements/UC-001.md

UC-001 — Conduct a Scoped Security Mission

Metadata

• 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

Preconditions

• 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.

Trigger

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.