Docs: versioned as-built ABCA specification in EARS (extract from current code)

[krokoko]

Roadmap: Exposed project specifications
Priority: P0
Related: #666 (EARS syntax for normative requirements), #506 (harness glossary), #507 (PEV control model), #453 (OpenAPI/JSON Schema)

Doc area

Design / architecture (docs/design/) — plus a new versioned normative spec artifact (location TBD, e.g. docs/spec/ or repo-root SPEC.md)

Describe the issue

ABCA's behavior today is defined by the as-built implementation (CDK TypeScript, Python agent runtime, CLI, Cedar policies, workflow YAML) and by scattered design prose. There is no single, versioned, language-agnostic requirements specification that captures what the system must do.

That gap hurts two audiences:

1. Validators / maintainers — without normative requirements checked into the repo, drift between intended behavior and code is hard to review or test against.
2. Re-implementers / fork authors — anyone who wants to modify the factory, port it to another language or tech stack, or rebuild a conforming implementation must reverse-engineer handlers, stacks, and agent pipeline code.

Issue #666 will require EARS for normative requirements in ADRs. This issue delivers the as-built product/platform specification those ADRs can point at: extract requirements from the current codebase (and reconciled design docs), express normative statements in EARS, and keep the result versioned in-repo beside the code.

Affected docs / artifacts

• New: versioned normative specification (path TBD; prefer something reviewable as a first-class repo artifact, not only Starlight content)
• docs/design/ARCHITECTURE.md, ORCHESTRATOR.md, WORKFLOWS.md, Cedar/HITL and related design docs — sources to reconcile, not replace wholesale
• docs/design/ABCA_V2.md (or successor) — link from the ABCA Spec track
• Starlight mirrors via mise //docs:sync if the chosen path is under a synced tree
• Cross-links from README / developer guide once the artifact exists

Suggested change

1. Reverse-engineer as-built requirements

Walk the current system boundaries and extract observable contracts, not implementation anecdotes:

• Task admission and lifecycle (REST API / orchestrator states)
• Workflow resolution and Plan–Execute–Verify control flow
• Compute isolation and agent runtime contract
• Policy / Cedar / HITL gates
• Adapter surfaces (GitHub, Linear, Jira, Slack, …) at the requirement level (what must be true), not SDK details
• Progress / observability events operators and the CLI rely on
• Security and tenancy boundaries that are already enforced in code

Mark each requirement with provenance (code path, design doc, or “inferred as-built”) so reviewers can challenge accuracy.

2. Author a language-agnostic normative spec

Produce a single versioned document (or small set of documents with a clear entrypoint) that:

• States purpose, goals, and non-goals
• Defines the core domain model and component boundaries at an abstraction level suitable for re-implementation
• Expresses normative requirements in EARS (ubiquitous, state-driven, event-driven, optional-feature, unwanted-behavior), consistent with The ABCA ADR standard shall require EARS syntax for normative requirements #666
• Separates MUST behavior from implementation-defined choices (AWS CDK vs alternate IaC, specific runtimes, etc.)
• Remains independent of TypeScript / Python / AWS service names where the requirement is portable; call out AWS-specific obligations explicitly when they are part of this reference implementation’s contract

3. Keep the spec versioned and reviewable

• Check the artifact into git so PRs that change behavior can update requirements in the same change (or flag intentional drift)
• Document how the spec relates to design docs (Docs: ABCA Spec — harness engineering glossary and extension catalog #506 / Docs: ABCA Spec — Plan–Execute–Verify (PEV) control model #507) and machine-readable API contracts (Docs: publish OpenAPI/JSON Schema and integration index #453): prose requirements vs OpenAPI/JSON Schema are complementary, not duplicates
• Prefer incremental delivery (skeleton + highest-value domains first) over a one-shot perfect tome

Acceptance criteria

• Versioned normative specification checked into the repo with a clear entrypoint path
• Normative statements use EARS patterns (aligned with The ABCA ADR standard shall require EARS syntax for normative requirements #666 once accepted; until then, draft in EARS and note the dependency)
• Spec covers at least: problem/goals/non-goals, domain model, orchestration lifecycle, agent/runtime contract, policy gates, and adapter/extension boundaries
• Requirements are as-built–faithful: extracted from current code (and reconciled docs), with provenance notes for contested items
• Spec is written so an alternate stack could claim conformance without copying this repo’s languages or AWS-only APIs for portable requirements
• Design docs and ABCA Spec track link to the new artifact; mise //docs:sync run if applicable
• No runtime behavior change required for the initial extraction PR (documentation / spec only)

Out of scope

• Rewriting or replacing the CDK/Python implementation
• Enforcing automated conformance tests against every EARS statement (follow-up once the baseline exists)
• Full OpenAPI/JSON Schema publication (tracked in Docs: publish OpenAPI/JSON Schema and integration index #453)
• Rewriting ADRs themselves (tracked in The ABCA ADR standard shall require EARS syntax for normative requirements #666)