# AWP VISION → Specification Traceability Audit

**Date:** 2026-08-20  
**Status:** **FULL PRE-RUN VISION TRACE COMPLETE — semantic omissions corrected; physical harvest/provider/visual gates remain explicit**  
**Source authority:** [`../VISION.md`](../VISION.md)  
**Purpose:** Prove that implementation can start from the target specifications without silently losing owner intent, while distinguishing accepted architectural refinements from accidental vision drift.

## Executive Result

The current specification set preserves the material AWP product VISION after this audit, but only after correcting several omissions discovered during the pre-run review.

New VISION-specific corrections landed in this pass:

```text
Project onboarding must produce a durable ProjectVision, not only GOLIVE/Plan context
ProjectVision / Plan / GOLIVE are distinct authorities
one token/session authority per provider Account credential is an explicit invariant
Botmaster + systray are restored as first external dogfood communication adapters
all 15 page specs now contain explicit page-specific User Journeys and authority/safety contracts
```

The remaining pre-run items are **not unidentified product semantics**. They are explicit evidence/visual/source gates:

```text
exact Overdeck source/CLI/capability harvest
historical Overdeck FactoryRun UX wording/source check before I4 high-fi if available
current Subrouter/provider compatibility proof
I0/I1 Platform/FOSS consumer/provider tests + exact pins
Node/TypeScript/pnpm pin against actual consumed Platform revision
rendered page journey/relationship diagrams where review value is high
I0/I1 U1–U6 high-fi + explicit owner approval
```

## Status Vocabulary

```text
PRESERVED
  source VISION maps directly to current target specs/plans.

CORRECTED
  audit found a real omission and canonical specs were amended.

ACCEPTED REFINEMENT
  later architecture/FOSS/UX decision intentionally changed the original mechanism while preserving the goal.

PHYSICAL GATE
  semantic seam is specified; exact existing-code/provider evidence still must be inspected before equivalent code.

VISUAL GATE
  behavior is specified but required human visual/diagram approval is intentionally not complete.
```

## 1. Product Identity / Purpose

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| AWP is the successor to Overdeck, not a shallow rewrite | architecture baseline/principles, design progress | **PRESERVED** | Preserve proven capability; discard accidental coupling. |
| AWP owns complete software delivery lifecycle | domain model + Plan→Factory→Review→CI→Release→Deployment workflows | **PRESERVED** | Providers perform mechanics; AWP owns why/state/authority/next. |
| Product-manager UX, not low-level agent runner | UI IA, Home, Project, Plan, Planning | **PRESERVED** | Owner-facing work/questions dominate raw infrastructure objects. |
| Product should later support external customers/beta testers | I9 productization specs/reliability/tenancy boundaries | **PRESERVED** | Not pulled into I0–I1. |
| “thin” over battle-tested infrastructure, build as little as possible | platform/FOSS reuse spec + binding FOSS register + harvest plan | **PRESERVED** | “Thin” means semantic control plane over proven mechanics, not UI-only software. |

## 2. Preserve Overdeck Capability Without Preserving Architecture Debt

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| keep every working/special Overdeck capability that belongs in AWP | `AWP-OVERDECK-CAPABILITY-HARVEST-PLAN` | **PRESERVED + PHYSICAL GATE** | Every relevant item must get explicit disposition before equivalent custom code. |
| reorganize/dedupe hundreds of CLI tools into `aw*` family | control-surfaces spec + harvest plan | **PRESERVED + PHYSICAL GATE** | Exact source inventory still needs authorized Overdeck source access. |
| existing CI/deployment mechanical fixer scripts first | incidents/resolvers + harvest plan | **PRESERVED + PHYSICAL GATE** | Harvest/classify/qualify before replacements; agentic resolver second. |
| preserve useful deck-ui behavior only when Astryx lacks it | platform-reuse + UI harvest | **ACCEPTED REFINEMENT** | Old product identity does not become runtime fallback; behavior can be ported into AWP-owned component. |
| recover useful prior FactoryRun UX/wording before redesign | FactoryRun spec + harvest/history requirement | **PHYSICAL GATE before I4 visual freeze** | Current target behavior is specified; if historical source exists, inspect before rich FactoryRun high-fi rather than rediscover later. |
| Botmaster and systray remain separate tools | Communications domain | **PRESERVED** | They stay external to AWP core. |
| Botmaster/systray should be first communication channels | Communications domain | **CORRECTED** | Restored as preferred first external dogfood adapters when external channel becomes necessary. |

## 3. Security / Containment / Execution

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| normal agents never work on user's workstation | deployment topology + workspace/security specs | **PRESERVED** | K3s execution is invariant from I0. |
| K3s is permanent substrate, not late retrofit | I0 delivery plan + Workspace/Cluster specs | **PRESERVED** | Full Cluster product UI waits I7, substrate begins I0. |
| agents can safely have powerful rights only inside isolated execution | capability/security/workspace specs | **PRESERVED** | System ceiling + workload isolation + no reusable publication credentials. |
| isolated Workspace/WIP must survive crashes/pod deletion | workspace-execution + durable execution | **PRESERVED** | disposable compute; recoverable WIP is not disposable. |
| machine enrollment via SSH should be automatic/self-service | Cluster domain + machine-enrollment workflow | **PRESERVED** | preflight → install/join → verify; user does not need K3s commands. |
| Machine capabilities first-class | Cluster domain | **PRESERVED** | scheduling inputs are data, not hostname rules. |
| explain why work is queued/placed | Cluster/Factory UI | **PRESERVED** | no opaque queue count. |

## 4. Project Onboarding / VISION / GOLIVE / Planning

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| onboarding generates Project VISION | Project domain, domain model, onboarding workflow | **CORRECTED** | `ProjectVision` is now durable/versioned project-level intent, not chat text. |
| onboarding generates GOLIVE | Project domain + onboarding | **PRESERVED** | GOLIVE is readiness projection, not fake percent/second Plan. |
| VISION, Plan and GOLIVE mean different things | Project/Planning domains | **CORRECTED/EXPLICIT** | Vision = enduring product intent; Plan = bounded work; GOLIVE = readiness. |
| new/existing project evidence should be inspected rather than retyped | onboarding + Planning truth model | **PRESERVED** | observed/documented/desired/recommended remain distinct. |
| interactive agent-led software planning | Planning domain/workflow/UI | **PRESERVED** | Planner leads agenda; structured state survives chat loss. |
| user should not keep asking “what next?” | planner leadership + Planning UI | **PRESERVED** | Now/Next/Later + Plan Index. |
| selectable delivery/work method including Scrum/Kanban/Scrumban/Custom and iterative/incremental/predictive concerns | Planning/delivery configuration specs | **PRESERVED / TERMINOLOGY REFINED** | “Agile” is not modeled as opposite of Incremental; underlying consequences are primary. |
| Start / Schedule / Park explicit execution handoff | Planning domain/UI | **PRESERVED** | no silent execution. |
| Project page shows GOLIVE, Plans, attention and active delivery | Project UI | **PRESERVED** | ProjectVision summary now also visible. |
| Plan page shows waves/phases/tasks/concurrency and clickable Factory/Agent | Plan UI | **PRESERVED** | graph never sole accessible representation. |

## 5. Human-in-the-Loop / Autonomy / Resolver Decisions

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| 0–100 configurable HITL/autonomy | Policy/Autonomy domain + Settings/Approval UI | **PRESERVED / MODEL REFINED** | numeric control is preset/editor over explicit rules, not magic permission integer. |
| arbitrary configurable criteria/hooks | Policy domain | **PRESERVED** | rules can match action/risk/path/environment/confidence/security/cost/custom hooks. |
| fully autonomous operation should be possible | Policy/Autonomy | **PRESERVED** | within authentication/security/owner-intent ceilings. |
| higher-authority resolver model can make delegated technical decisions | ResolverPolicy / Decision | **PRESERVED** | durable structured Decision, not invisible chat output. |
| humans only interrupted when policy/owner authority really requires it | Planning/Attention/HITL | **PRESERVED** | unrelated work continues when dependencies allow. |

## 6. Accounts / Models / Credentials

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| global Provider/Account/Model management | Accounts/Models/Providers + Settings | **PRESERVED** | multiple accounts are normal. |
| select account/model per Project/Plan/Task/Run | account selection/config hierarchy | **PRESERVED** | exact resolved choice persisted per Attempt. |
| one token owner; stop duplicate refresh races | Accounts/Models/Providers + Connections | **CORRECTED/EXPLICIT** | exactly one mutable token/session authority per logical Account credential. |
| Subrouter should be reused if it solves routing/token mechanics | account spec + reuse preflight | **ACCEPTED REFINEMENT + PHYSICAL GATE** | candidate behind seam; current capability must be proven before custom router. |
| credentials not spread into workloads/config | Connections/Security/Workspace | **PRESERVED** | CredentialReference → SecretStore; narrow projections only. |

## 7. Configuration

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| all meaningful configuration inspectable/editable in UI | Configuration domain/architecture + Settings UI | **PRESERVED** | typed definitions; purpose/provenance/consequence. |
| System → Project → Plan → Task levels | configuration hierarchy | **PRESERVED** | Run is immutable resolved snapshot where appropriate. |
| inherited/effective values visible | Settings UI | **PRESERVED** | Reset-to-inherited supported. |
| untouchable settings still visible read-only with explanation | Settings UI | **PRESERVED** | never hide locked config. |
| distinguish desired/applied/observed config and drift | Configuration architecture | **PRESERVED** | no silent repair without history. |

## 8. Factory / Agents / Observability

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| observable software factory | Factory domain/workflow + FactoryRun UI | **PRESERVED** | run, task, agent, attempts, WIP, ChangeSet. |
| realtime Factory UI | Event/realtime + FactoryRun/Agent UI | **PRESERVED** | realtime is projection; authoritative state recoverable by query. |
| click agent to chat/tool/file/diff view | Agent UI | **PRESERVED** | structured tools/diffs, raw provider logs secondary. |
| global Agents page with node/task/factory/model/account/status and historical stats | Agents UI | **CORRECTED** | dedicated collection/analytics page added. |
| Project→Plan→Task→FactoryRun→Agent relationships clickable/breadcrumbed | UI IA/page specs | **PRESERVED** | product-manager wayfinding is binding. |
| token/cost/error analytics where provider supports | Agents/Agent UI | **PRESERVED** | never fabricate unavailable metrics. |

## 9. Git / Changes / Review / Merge Authority

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| platform owns workspaces/git/versioning/publication/merge | Repository/ChangeSet/Review/Workspace workflows | **PRESERVED** | agents request, trusted control plane publishes/merges. |
| agents' normal execution job is code/review/fix, not lifecycle mechanics | security/factory/review architecture | **PRESERVED WITH ROLE DISTINCTION** | planner/resolver are separate bounded system roles; coding AgentRuns do not become lifecycle authority. |
| independent review and exact-candidate fidelity | ChangeSet/Review + task-to-merge | **PRESERVED** | Review binds exact candidate revision. |
| failures/corrections create new provenance rather than rewriting history | Attempts/ChangeSets/Review | **PRESERVED** | retry/new revision is explicit. |

## 10. CI / Verification / Self-Improvement

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| AWP owns CI semantics, provider only execution | CI/Verification domains + CI boundary | **PRESERVED** | GitHub Actions + ARC are mechanics. |
| changed files → affected components/capabilities → invariants → checks | CI domain/Planning | **PRESERVED** | conservative on uncertainty. |
| avoid stupid path-only “.ts changed → typecheck” rules | CI specification | **PRESERVED** | dependency/capability graph semantics. |
| Verification cannot be self-certified by agent | VerificationAuthority | **PRESERVED** | smallest falsifying test; authoritative admission/gates. |
| CI optimizer can improve CI but not silently weaken it | CI domain/UI | **PRESERVED** | proposals go through normal AWP lifecycle. |
| AWP should dogfood its own execution/CI | I0/I1 delivery plan | **PRESERVED** | I0 goal explicitly enables AWP to begin building AWP. |

## 11. Release / CD / Deployment / Recovery

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| AWP owns Artifact/Release/Environment/Deployment lifecycle | delivery domains/workflows | **PRESERVED** | immutable release + env-specific deployment. |
| deployment health + rollback + deterministic/agentic resolver | Deployment/Incident workflows | **PRESERVED** | previous safe Release explicit. |
| Flux adapter in original increment sketch | binding FOSS decisions + ADR 0008 | **ACCEPTED REFINEMENT** | baseline is Helm render + Kubernetes SSA; Flux only when real GitOps requirement appears. |
| reuse mature deployment mechanics rather than custom reconciler | reuse/FOSS + deployment boundary | **PRESERVED** | no custom GitOps engine. |
| supply-chain evidence/provenance | Artifact/Release specs | **PRESERVED** | SLSA/in-toto, CycloneDX/SPDX, Trivy/Cosign/ORAS as applicable. |

## 12. Cluster / Operations

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| Cluster page answers health/capacity/running/queue | Cluster UI | **PRESERVED** | not Kubernetes Dashboard 2.0. |
| Add Machine as simple user action | Cluster UI + enrollment workflow | **PRESERVED** | SSH/preflight/install/join/verify. |
| machine lifecycle/maintenance/removal safe | Cluster domain/UI | **PRESERVED** | affected WIP/workloads shown before action. |
| native/simple mechanics before extra operators | FOSS/reuse | **PRESERVED** | K3s-native-first. |
| future deeper hardware/health/upgrade uses NFD/NPD/system-upgrade-controller | FOSS coverage | **PRESERVED** | no custom daemons/scheduler. |

## 13. Communications / Attention

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| Communication is a primitive | Communications domain | **PRESERVED** | endpoint/provider replaceable. |
| Botmaster/systray separate from AWP identity | Communications | **PRESERVED** | external adapters only. |
| Botmaster then systray first external owner channels | Communications | **CORRECTED** | restored explicitly. |
| external notification failure cannot lose action item | Attention/Communications | **PRESERVED** | in-product Attention canonical. |

## 14. UI / UX / Human Auditability

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| Astryx as AWP visual component source | platform-reuse + UI specs | **PRESERVED** | deck-ui only behavior/source harvest on actual gap. |
| self-explanatory UI; technical raw data secondary | UI IA/page specs | **PRESERVED** | provider JSON/logs/K8s are evidence layers. |
| tooltips explain purpose | UI IA | **ACCEPTED UX REFINEMENT** | help explains purpose/consequence where useful; do not add redundant tooltip to literally every obvious control. |
| every page gets own spec | `docs/specs/ui/*` | **PRESERVED** | 15 page contracts + whole-product IA. |
| every page spec explains user journeys | UI completeness audit + amended pages | **CORRECTED** | all 15 normalized. |
| full design diagram per page | presentation standard + UI completeness audit | **VISUAL GATE** | semantic journey flows exist; rendered diagram pass remains before visual Design Complete where it adds review value. |
| exact approved high-fi before implementing user-facing state | presentation standard + increment plan | **VISUAL GATE** | U1–U6 next. |
| complete Empty/Loading/Error/Populated/Stale/accessibility/responsive behavior | page specs + UI IA | **PRESERVED** | visual variants only where materially distinct. |
| stable URL/breadcrumb wayfinding | UI IA/page specs | **PRESERVED** | primitive relationships remain navigable. |

## 15. Specification / Governance / Anti-Drift

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| central specs are source of truth | full-spec ratification + presentation standard | **PRESERVED** | latest merged canonical spec is authority. |
| spec + architecture changes protected by CI/process | engineering practices/spec governance | **PRESERVED TARGET** | implementation must add conformance/stale/link checks from I0. |
| human-readable specs, not AI-only docs | presentation standard + HTML companions | **PRESERVED** | Markdown canonical, HTML human review surface. |
| Decisions preserve why intent changed | Decision domain/Decision Log/ADRs | **PRESERVED** | accepted history immutable/superseded. |
| no vision drift across increments | target-state + realization matrix + this audit | **PRESERVED** | later capability fully specified but activated only at its increment. |

## 16. Architecture / Modularity / Reuse

| VISION intent | Canonical authority | Status | Notes |
|---|---|---|---|
| modular monolith | ADR 0002/module boundaries | **PRESERVED** | no service sprawl. |
| strict coding standards / modular boundaries | engineering practices + module boundary spec | **PRESERVED** | R1 executable architecture checks activate I0. |
| use `platform-modules/mod` before building generic helpers | platform-reuse + I0/I1 preflight | **PRESERVED + PHYSICAL GATE** | current package/export snapshot already inspected; consuming tests/pins pending. |
| FOSS MIT/Apache preference and replaceable providers | FOSS decisions/coverage | **PRESERVED** | license is one input; total-system complexity decides. |
| “everything is a primitive” | domain-model qualification policy | **ACCEPTED REFINEMENT** | durable lifecycle/identity concepts become primitives; not every field/provider object becomes ceremonial primitive. |
| provider independence | adapters/domain model | **PRESERVED** | provider IDs are mappings; capability-based contracts. |

## 17. Increment Sequence

The VISION's I0–I9 product sequence remains recognizable and binding through the canonical Increment Realization Matrix:

```text
I0 Foundation / self-hosting substrate
I1 complete Project -> Plan -> Task -> FactoryRun -> AgentRun -> ChangeSet -> Review -> Merge slice
I2 ProjectVision-aware onboarding + Real Planning / GOLIVE
I3 Decisions / Approval / autonomy
I4 Factory + Agent observability
I5 CI control plane
I6 Release / Deployment
I7 Cluster product surface
I8 Incident / Resolver / self-healing
I9 customer/enterprise + formal reliability/SLO productization
```

Mechanics changed only through accepted architecture/FOSS decisions, e.g. Helm+SSA baseline instead of unconditional Flux.

## 18. Remaining Physical / Evidence Gates

These are explicit before their consuming code; they are not permission to reopen the architecture from scratch:

### I0/I1

```text
Overdeck source harvest
  exact paths/commits/dispositions for CLI, Git/workspace/publication,
  K3s/offload, factory, account routing, config/auth/realtime/health,
  CI helpers, WIP/recovery/cleanup

Platform consumer proof
  exact consumed package versions/revision + AWP integration tests

Subrouter proof
  account/token/routing/session authority and failure semantics

Provider proofs
  DBOS
  Kubernetes Workspace + gVisor
  Dev Container representative projects
  Fabro
  ACP
  GitHub + ARC
  official MCP SDK

runtime pin
  Node / TypeScript / pnpm compatible with actual consumed Platform revision
```

### Later consuming increments

```text
FactoryRun historical UX/request source check before I4 visual freeze if source exists
CI/deployment resolver script harvest before I5/I6/I8 equivalents
cluster enrollment/health/upgrade helper harvest before I7 equivalents
UI/deck-ui behavior harvest whenever Astryx lacks required interaction
```

## 19. Remaining Visual Gates

```text
page journey/relationship/state diagrams in human HTML where they improve review
I1 U1 Project + ProjectVision + minimal Plan/Task
I1 U2 FactoryRun active
I1 U3 waiting/failure/retry/WIP safety
I1 U4 ChangeSet/Review
I1 U5 Ready to merge
I1 U6 Merged/completed
explicit owner approval
```

Then Design Complete can be marked for I0/I1 user-facing states.

## 20. Final Gap Verdict

After the corrections above, **no known material VISION requirement is absent from the semantic target specification baseline**.

What remains is intentionally visible:

```text
SEMANTIC VISION COVERAGE                GREEN
FOSS / NO-REBUILD SEMANTIC COVERAGE     GREEN
UI PAGE CONTRACT SEMANTIC COVERAGE      GREEN
OVERDECK PHYSICAL HARVEST               PENDING before equivalent code
PLATFORM/SUBROUTER/FOSS PROVIDER PROOFS PENDING before consuming code
RUNTIME VERSION PIN                     PENDING actual compatibility state
PAGE DIAGRAM / PRESENTATION PASS        PENDING visual Design Complete
U1–U6 HIGH-FI                           PENDING owner approval
IMPLEMENTATION                          NOT STARTED
```

If any preflight or visual review reveals a new material contradiction, it must become a Finding/Decision/spec amendment before implementation is allowed to establish a different authority.