# AWP Pre-Run Vision-Drift Gap Review

**Date:** 2026-08-20  
**Status:** **SEMANTIC/REUSE GAP REVIEW COMPLETE — amendments landed; source-harvest execution + high-fi remain pre-I0 gates**  
**Purpose:** Audit the completed target-state specification baseline against VISION, accepted Planning decisions, FOSS/reuse research, Overdeck capability-preservation intent, UI atlas and I0–I9 boundaries before implementation creates new precedent.

## Executive Result

The original full-specification pass was strong on **domain seam consistency** but its earlier “complete/no gaps” claim was too broad. It did not fully prove that every owner intent, reuse requirement and code-harvest requirement had reached the implementation-facing specs.

This audit found fourteen coverage/presentation issues. The **semantic/specification omissions are now amended**. The remaining gates are deliberately operational/visual:

```text
PRE-I0 SOURCE VERIFICATION
  inspect exact I0/I1 Overdeck source candidates
  verify current Platform exports actually consumed
  verify selected provider/FOSS versions/capabilities
  record dispositions; do not rebuild around missing evidence

P7 VISUAL DESIGN COMPLETE
  rendered human diagrams where valuable
  U1..U6 high-fi
  spec/mockup reconciliation
  explicit owner visual approval
```

The GitHub connector available during this audit can inspect `platform-modules/mod` but does **not** expose the private Overdeck repository. Therefore this review does not fabricate source paths or pretend the physical Overdeck harvest has already happened. Instead the source harvest is now a hard pre-build gate with a defined record schema.

## Audit Sources

- [`../VISION.md`](../VISION.md)
- [`AWP-FOSS-DECISIONS.md`](AWP-FOSS-DECISIONS.md)
- [`AWP-FOSS-MINIMALISM-DECISION-PASS.md`](AWP-FOSS-MINIMALISM-DECISION-PASS.md)
- [`AWP-FOSS-REUSE-DEEP-RESEARCH.md`](AWP-FOSS-REUSE-DEEP-RESEARCH.md)
- [`AWP-PLANNING-ARCHITECTURE-REVIEW.md`](AWP-PLANNING-ARCHITECTURE-REVIEW.md)
- [`AWP-PLANNING-DECISION-REGISTER.md`](AWP-PLANNING-DECISION-REGISTER.md)
- [`AWP-UI-SCREEN-ATLAS.md`](AWP-UI-SCREEN-ATLAS.md)
- [`AWP-INCREMENTAL-DELIVERY-PLAN.md`](AWP-INCREMENTAL-DELIVERY-PLAN.md)
- [`AWP-INCREMENT-REALIZATION-MATRIX.md`](AWP-INCREMENT-REALIZATION-MATRIX.md)
- [`../specs/INDEX.md`](../specs/INDEX.md)

## Gap Register and Resolution

| ID | Gap found | Severity | Resolution now |
|---|---|---|---|
| **G01** | No canonical Overdeck capability/code-harvest gate; proven tools/scripts/modules could be silently rebuilt. | BLOCKER | **CLOSED in spec:** [`AWP-OVERDECK-CAPABILITY-HARVEST-PLAN.md`](AWP-OVERDECK-CAPABILITY-HARVEST-PLAN.md) defines required categories, dispositions, provenance and pre-build gate. Exact source inventory executes before its consuming increment. |
| **G02** | Platform/FOSS implementation-facing reuse map was narrower than the final FOSS research. | BLOCKER | **CLOSED:** [`../specs/architecture/platform-reuse.md`](../specs/architecture/platform-reuse.md) now contains mandatory project-native → Platform → harvest → native → standard → FOSS/provider → custom order and complete selected/trigger map. |
| **G03** | Resolver spec did not require harvesting proven Overdeck CI/deployment recovery scripts before writing replacements. | BLOCKER for resolver work | **CLOSED:** `domains/incidents-resolvers` now requires qualification/port/replacement of existing deterministic recovery knowledge before generic resolver code. |
| **G04** | Account/model domain did not explicitly prevent rebuilding token/routing/health/fallback before checking current Platform/Subrouter capability. | BLOCKER for account work | **CLOSED:** account spec now makes current Platform/Subrouter verification mandatory and keeps Subrouter behind provider seams rather than declaring it universal domain truth. |
| **G05** | No full shared UI/API/CLI/MCP control-surface contract; `aw*` CLI intent could drift. | BLOCKER before CLI/MCP work | **CLOSED:** [`../specs/architecture/control-surfaces.md`](../specs/architecture/control-surfaces.md) defines shared application commands/queries, auth/policy/audit, `aw*` family and official MCP SDK use. |
| **G06** | VISION/atlas global Agents collection/analytics had no dedicated page spec. | DESIGN prerequisite | **CLOSED:** [`../specs/ui/agents.md`](../specs/ui/agents.md). |
| **G07** | First-class Project Decision Log had domain semantics but no dedicated page spec. | DESIGN prerequisite | **CLOSED:** [`../specs/ui/decision-log.md`](../specs/ui/decision-log.md). |
| **G08** | UI INDEX silently simplified away the accepted six-group atlas navigation and global collections. | VISION-DRIFT BLOCKER | **CLOSED:** `ui/INDEX` restores canonical HOME / WORK / EXECUTION / DELIVERY / OPERATIONS / SETTINGS target IA; increment activation may hide unavailable destinations but may not redesign the product shell. |
| **G09** | `GOLIVE` appeared in Project/onboarding but lacked precise semantics and risked becoming a fake percentage widget. | BLOCKER for I2 design | **CLOSED:** `GOLIVE` is defined as a Project readiness projection/artifact over authoritative gates/evidence/blockers/deferrals; no duplicate primitive or fake percentage authority. |
| **G10** | Astryx/deck-ui rule existed but was not connected to the harvest gate. | DESIGN prerequisite | **CLOSED:** `port-behavior` disposition explicitly requires inspecting proven deck-ui/Overdeck behavior before recreating missing complex UI; output becomes AWP-owned. |
| **G11** | Several no-build standards/tools from deep research were absent from the canonical reuse map. | BLOCKER | **CLOSED:** reuse spec now covers official Dev Container tooling, MCP SDK, repo build graphs, Testcontainers preservation, release-prep adapters, K3s installer/upgrader/health sources, supply-chain formats and Helm/Kustomize among others. |
| **G12** | Risk of accidentally migrating Botmaster/systray/personal toolkit behavior into AWP. | Boundary check | **ALREADY CLOSED:** communications spec explicitly keeps Botmaster CLI and systray outside core AWP; they can only be external communication adapters/endpoints if desired. |
| **G13** | Human HTML exists but many diagrams are still text/preformatted and high-fi is not yet embedded. | VISUAL Design Complete | **OPEN BY DESIGN:** presentation hardening + U1–U6 remain P7, before UI implementation. This is not permission to start UI code. |
| **G14** | Canonical FOSS research/decisions were not all available as human HTML. | Human-auditability | **CLOSED:** HTML companions now exist for FOSS Decisions, Minimalism Pass, Deep Research, Harvest Plan and this review. |

## Verified Platform Availability

The connected `platform-modules/mod` repository is available for the implementation-time verification pass and currently contains packages including the relevant generic families such as `ai`, `audit`, `auth`, `db`, `jobs`, `notifications`, `realtime`, `search`, `tenancy`, `ui-primitives`, `ui-tokens` and `util`.

That establishes that the reuse gate is actionable, but it is **not** a substitute for checking exact current exports/version/capability before AWP consumes each package. The `platform-reuse` spec requires that evidence.

## Canonical No-Rebuild Decision Order

```text
Need capability
  -> use existing project-native mechanism if it already owns the behavior
  -> verify platform-modules/mod
  -> inspect proven Overdeck capability/script/module harvest
  -> use native Node/Postgres/K3s/Kubernetes primitive when sufficient
  -> use open standard/interchange format where it deletes custom integration
  -> use selected narrow FOSS/provider
  -> only then authorize custom generic mechanics
```

AWP-specific domain semantics remain AWP-owned.

## Explicit No-Rebuild Areas

Before custom implementation, prove the selected reuse path is insufficient:

```text
factory graph mechanics                 Fabro
agent protocol                          ACP where supported
MCP wire                                official TypeScript MCP SDK
CI execution/runners                    GitHub Actions + ARC
workspace mechanics                     Kubernetes primitives
project environment                     existing repo definitions + Dev Container standard/CLI
account/model routing/token mechanics   current Platform/Subrouter verification first
bounded jobs/outbox                     Platform jobs when fitting
DB/auth/audit/config/logger/realtime    current Platform capabilities first
board drag/drop                         Pragmatic Drag and Drop
graph interaction                       React Flow
charts                                  Chart.js
K3s install/join                        official K3s installer; k3sup optional helper
K3s upgrades                            system-upgrade-controller
node problem detection                  node-problem-detector
hardware feature depth                  Node Feature Discovery only when needed
current CPU/memory                      metrics-server
historical OS/node metrics              node_exporter only when needed
historical K8s object metrics           kube-state-metrics only when needed
Kubernetes packaging                    Helm
manifest overlays                       Kustomize selectively
contract diff                           OpenAPI + oasdiff
threat modeling                         OWASP + Threat Dragon when useful
SBOM/provenance/findings                CycloneDX/SPDX + SLSA/in-toto + SARIF
release preparation                     project-native / Changesets / Release Please / semantic-release
scan/sign/OCI transport                 Trivy + Cosign + ORAS
existing deterministic recovery         vetted Overdeck CI/deployment scripts before replacements
```

## Trigger-Only Infrastructure Remains Deferred

The audit does not pull optional infrastructure forward:

```text
Agent Sandbox, Kata, Kueue, Cilium/Hubble, Kyverno,
OpenBao/ESO, Flux/Flagger, vCluster, OpenTofu,
self-hosted storage/registry profiles, persistent telemetry stack,
SPIFFE/SPIRE and enterprise/fleet machinery
```

Use only on the documented trigger and through the target adapter seam.

## Increment Boundary Check

No delivery sequence changed:

```text
I0  foundation + actual reuse/source-harvest verification for I0/I1
I1  complete Project -> Plan -> Task -> FactoryRun -> AgentRun -> ChangeSet -> Review -> Merge dogfood lifecycle
I2  Planning/onboarding/GOLIVE
I3  Decisions/Approvals/autonomy
I4  Factory/Agent observability
I5  CI control plane
I6  Release/Deployment
I7  Cluster product surface
I8  self-healing
I9  external/enterprise + formal SLO machinery
```

## Hard Pre-I0 Implementation Gate

The semantic gaps are fixed, but **implementation must not begin around unverified reuse assumptions**. Before I0/I1 custom code is authored:

```text
[ ] inspect exact I0/I1 Overdeck source candidates and record dispositions
[ ] verify/pin exact Platform exports actually consumed
[ ] verify/pin selected external FOSS/provider versions/capabilities actually consumed
[ ] check current Subrouter capability before custom account-routing/token code
[ ] classify I0/I1-relevant CI/deployment/cleanup/recovery scripts instead of ignoring them
[ ] show a no-rebuild disposition for every meaningful I0/I1 generic subsystem
```

This is source verification, not another product-design interview.

## Visual Gate

Before user-facing I1 coding:

```text
render/polish the human diagrams needed for design review
create U1..U6 high-fidelity states
review mockups against target specs + canonical six-group IA
amend any exposed Decision/spec issue
obtain explicit owner approval
```

## Conclusion

There is no longer a known **semantic** omission that authorizes rebuilding the FOSS/Platform/Overdeck mechanics discussed in the earlier sessions. The corrected specs now make reuse/harvest a mandatory implementation decision path.

The remaining uncertainty is concrete source/provider evidence, which is intentionally checked before the first consuming code, and visual high-fidelity, which remains the next Design Complete gate.