# AWP Full Specification Traceability and Contradiction Review

**Date:** 2026-08-20  
**Status:** **COMPLETE SEAM/OWNER-AUTHORITY REVIEW — supplemented by separate pre-run omission/reuse audit**  
**Scope:** Architecture, ADRs, domains, workflows, UI/IA, schemas/contracts and I0–I9 boundaries.

## Purpose

This review checks whether the specification set describes **one internally coherent system** across authority, identity and lifecycle seams.

It must be read together with [`AWP-PRE-RUN-VISION-DRIFT-GAP-REVIEW.md`](AWP-PRE-RUN-VISION-DRIFT-GAP-REVIEW.md), which asks a different question: **did we omit any important owner intent, FOSS/reuse requirement, harvest requirement or product surface even if the specs we did write are mutually consistent?**

The earlier version of this document incorrectly allowed “no seam contradiction” to sound like “no gaps of any kind.” The pre-run audit corrected that overclaim.

## Review Result

After the pre-run amendments:

- no known blocking cross-domain authority/identity contradiction remains;
- no known semantic omission remains around FOSS/reuse/Overdeck harvesting, `aw*` CLI/MCP, Agents collection, Decision Log, GOLIVE semantics or target navigation;
- exact implementation/provider/source evidence remains a pre-I0 verification task behind already-defined seams;
- high-fidelity visual Design Complete remains intentionally pending.

## Cross-Domain Authority Checks

| Concern | Authoritative model | Provider/projection | Result |
|---|---|---|---|
| Project vs Repository | Project owns software-delivery context/defaults; Repository owns source relation | forge repository mapping | Consistent |
| Plan vs PlanningSession | Plan/PlanRevision owns durable intent; PlanningSession owns interaction context | model/conversation | Consistent |
| GOLIVE | Project readiness projection over gates/evidence | Project/UI read model | Consistent; not a second lifecycle authority |
| Task vs FactoryRun | Task owns work goal/dependencies; FactoryRun owns orchestration instance | Fabro graph/node | Consistent |
| AgentRun vs Attempt | AgentRun logical assignment; Attempt immutable execution inputs/result | ACP/native provider run IDs | Consistent |
| Workspace vs Pod | Workspace owns isolated work/WIP association | Kubernetes Pod/PVC | Consistent |
| ChangeSet vs PR/branch | ChangeSet exact candidate/provenance | GitHub branch/commit/PR | Consistent |
| Review vs Approval | Review evaluates candidate; Approval authorizes protected action | forge review/status | Consistent |
| Decision vs Approval | Decision material choice/history; Approval consent | ADR/Attention projections | Consistent |
| CIExecution vs workflow/check | normalized AWP CI occurrence/meaning | GitHub Actions/checks + ARC mechanics | Consistent |
| VerificationEvidence vs agent claim | AWP evidence/gate authority | test/CI executions | Consistent |
| Artifact vs Release | immutable artifact/digest/provenance vs promotion/version set | registry/package tags | Consistent |
| Release vs Environment | immutable Release vs mutable/protected target | namespace/provider env | Consistent |
| Deployment vs rollout | AWP Release→Environment progression/history | Helm/Kubernetes rollout | Consistent |
| Cluster/Machine/Workload vs K8s | AWP product identity/capabilities/history | Node/Pod UID/status | Consistent |
| Connection/binding/requirement | global connection vs project grant vs unmet/deferred need | provider auth/resource | Consistent |
| Configuration vs Policy | typed desired/effective values vs authorization/progression rules | provider observations | Consistent |
| Secret vs config | CredentialReference/SecretStore | attempt-scoped projection | Consistent |
| Event vs Audit | business fact vs attribution/action trail | — | Consistent |
| Realtime vs state | lossy projection | gateway transport | Consistent |
| Telemetry vs product state | operational evidence only | OTel backend | Consistent |
| Notification vs Attention | Notification delivery projection | external channel | Consistent |
| UI/API/CLI/MCP | shared application commands/queries and policy | transport/projection | Consistent after control-surface amendment |

## Critical Workflow Checks

### I1: Project -> Plan -> Task -> Factory -> Change -> Review -> Merge

**Consistent.** I1 uses final `Project`, `Plan/PlanRevision`, `Task`, `FactoryRun`, `AgentRun`, `Attempt`, `Workspace`, `ChangeSet` and `Review` identities. No temporary `Job`, `TemporaryPlan` or PR-as-domain shortcut is required.

### Review correction loop

**Consistent.** `changes requested` returns to correction work, creates a new ChangeSet revision and requires evidence/review appropriate to the new candidate.

### CI / Verification evolution

**Consistent.** I1 persists thin final-form `VerificationEvidence` and consumes actual repository-required checks. I5 activates full `VerificationAuthority`, CI planning, admission/invalidation and optimization over the same seam.

### Planning -> execution

**Consistent.** Rich Planning activates I2; I1 narrow Plan interaction still uses final Plan identity. Simple/Expert changes participation, not completeness or authority.

### Merge -> Release -> Deployment

**Consistent.** I1 ends at trusted Merge. I6 activates Artifact/Release/Environment/Deployment using exact source/ChangeSet/provenance seams already preserved.

### Failure -> Incident -> Resolution

**Consistent.** local retry/recovery can exist earlier; I8 generalizes significant failure into Incident/Resolver/ResolutionAttempt without replacing Attempt/evidence/change workflows. Resolver amendments now require harvesting proven deterministic Overdeck CI/deployment recovery knowledge before equivalent custom recipes.

## Security / Trust Checks

- Agent/CI/reviewer workloads do not hold reusable forge publication/merge credentials.
- `Connection -> CredentialReference -> SecretStore`; Project binding and lower scopes only narrow.
- normal agent/CI work runs in K3s execution plane; workstation is not normal execution authority.
- gateway may authenticate ingress but control plane performs final Principal/capability/policy evaluation.
- CLI/MCP are not privileged bypasses; they share the same commands, policy, audit and protected-action gates.

## Configuration / Planning Checks

- first Expert Plan may explicitly establish reusable ProjectPlanningDefaults; Plan-specific override never silently changes them;
- Simple mode may delegate technical decisions but cannot hide OwnerRequired/PolicyRequired choices;
- recommendations retain confidence/basis/consequences/change conditions;
- readiness is gate/consequence based;
- GOLIVE is a Project readiness projection over authoritative gates/evidence, not an editable percentage authority;
- Decision history is superseded, not rewritten.

## Reuse / Anti-Rebuild Traceability

The pre-run audit added a missing implementation-facing chain:

```text
required capability
 -> project-native check
 -> Platform check
 -> Overdeck harvest check
 -> native/standard check
 -> selected FOSS/provider check
 -> custom code only when justified
```

`platform-reuse`, the FOSS Decision register and the Overdeck harvest plan are now explicit implementation authorities.

Subrouter is preserved as a strong current-capability reuse candidate behind `AccountProvider`, not hard-coded as domain truth.

Botmaster/systray remain outside core AWP.

## UI / Domain Traceability Checks

- target global navigation is HOME / WORK / EXECUTION / DELIVERY / OPERATIONS / SETTINGS; activation can hide future destinations but cannot silently replace the target IA;
- Work Command Center is a projection, not state authority;
- Project page aggregates GOLIVE, work, attention, decisions and delivery primitives with links to sources;
- Planning maps to PlanningSession/Decision/Deferral/EffectiveDeliveryPlan;
- FactoryRun/Agent/Agents map to Task/AgentRun/Attempt/Workspace and preserve provenance;
- Review binds exact ChangeSet revision/evidence;
- CI distinguishes expected/executed/reused/omitted/stale evidence;
- Decision Log is a projection over canonical Decision history;
- Release/Deployment visually separates immutable Release from Environment-specific Deployment;
- Cluster uses AWP Machine/Workload identities, not raw Kubernetes catalog;
- Incident maps Incident/ResolutionAttempt/Recipe and returns code/config fixes through normal delivery;
- Settings maps Configuration/Policy/Connections and does not reveal secrets.

## Increment Boundary Checks

| Capability | Target known now | Operational activation |
|---|---|---|
| foundation/state/security/provider seams | yes | I0 |
| complete code-to-merge lifecycle | yes | I1 |
| rich Planning/GOLIVE | yes | I2 |
| generic Decisions/Approvals/autonomy | yes | I3 |
| full Factory/Agent observability | yes | I4 |
| CI/VerificationAuthority | yes | I5 |
| Release/Deployment/R3 | yes | I6 |
| Cluster product surface | yes | I7 |
| generic self-healing | yes | I8 |
| external/enterprise + formal R5 reliability | yes | I9 |

A later full spec is never permission to implement early.

## Implementation-Local Decisions Still Open

The following can remain I0/I1 implementation choices **only while they remain behind established seams**:

```text
opaque ID encoding
runtime schema validator/code-generation library
initial SecretStore implementation detail
exact S3-compatible provider/config
realtime transport implementation
auth/session provider implementation for dogfood
OTel Collector/backend deployment
DBOS package wiring/migration detail
Kubernetes measured resource defaults
CSS/component technique after high-fi approval
```

If one changes trust, public compatibility, primitive ownership, target workflow or future increment contract, it becomes a Decision/spec amendment.

## Remaining Pre-I0 Evidence Work

Not target-design gaps:

```text
exact I0/I1 Overdeck source inventory + harvest dispositions
exact Platform exports/versions actually consumed
exact external provider/FOSS versions/capabilities actually consumed
representative integration/failure tests
```

These are required by the reuse gate before equivalent code is authored.

## Visual Design Gap

The semantic baseline is complete. **Visual Design Complete is not.** U1–U6 high-fi plus human diagram/presentation hardening and spec/mockup reconciliation remain the next gate.

## Conclusion

The combined reviews now cover both failure classes:

```text
TRACEABILITY REVIEW
  Are the written specs one coherent system?

PRE-RUN VISION/REUSE REVIEW
  Did we forget an important thing we intended to write?
```

No known semantic blocker remains after the amendments. Do not start user-facing implementation until the pre-I0 source/reuse checks and U1–U6 visual approval gates are satisfied.