# AWP Overdeck Capability Harvest Plan **Date:** 2026-08-20 **Status:** **BINDING PRE-BUILD / MIGRATION GATE** **Purpose:** Preserve proven Overdeck capability and operational knowledge without carrying Overdeck's accidental architecture into AWP or rebuilding working mechanics unnecessarily. ## Core Rule > **Preserve proven capability; discard accidental coupling.** No proven Overdeck capability that falls inside AWP's product boundary may be silently discarded or rebuilt simply because AWP starts in a new repository. Equally, no Overdeck package/module/script earns a place in AWP merely because it already exists. Every relevant item receives an explicit disposition. ## Scope of Harvest Audit at least these sources before their first consuming increment: ```text Overdeck CLI tools factory-related tools and adapters deployment-untangling / recovery scripts CI/CD helper scripts and failure recipes Git/workspace/publication helpers account/model/provider-routing helpers configuration/auth/realtime/health helpers reusable generic modules operational scripts that encode hard-won failure handling UI/deck-ui components or behavior absent from Astryx special capabilities visible only in code/scripts and not old docs ``` The audit is capability-oriented. Do not copy whole directories just to preserve them. ## Explicitly Outside Core AWP The following remain part of Overdeck/personal tooling unless a future explicit Decision changes the boundary: ```text Botmaster CLI systray tooling workstation-specific personal automation personal environment/toolkit behavior unrelated to a general software-delivery product ``` AWP may integrate Botmaster/systray through `CommunicationEndpoint` / provider adapters. Their product identity and personal-tool implementation do not migrate into AWP. ## Required Disposition Each candidate records one of: | Disposition | Meaning | |---|---| | `reuse-as-is` | Existing implementation cleanly fits the target seam and ownership rules. | | `adapt` | Reuse core mechanics with bounded changes to fit AWP interfaces. | | `wrap` | Keep implementation mostly intact behind an AWP Provider/adapter contract. | | `port-behavior` | Preserve proven behavior/UX/algorithm, but implement it as AWP-owned code because old identity/coupling must not survive. | | `replace-with-platform` | Existing capability is superseded by a verified `platform-modules/mod` capability. | | `replace-with-foss` | Existing capability is superseded by accepted standard/FOSS/native mechanics. | | `reference-only` | Useful test cases/lessons/UX but implementation should not migrate. | | `outside-awp` | Intentionally remains in Overdeck/personal tooling. | | `retire` | Obsolete and has no product capability worth preserving. | `rebuild` is not a disposition. If custom AWP implementation is required, the record must explain why `reuse/adapt/wrap/platform/FOSS/native` all fail the target contract. ## Harvest Record Schema For every candidate: ```text id source repository/path capability name current purpose known consumers proof it works / operational history hidden failure-handling knowledge license/ownership coupling/debt to remove target AWP primitive/module/seam disposition selected replacement/provider if applicable increment first consumed migration/port notes verification/acceptance evidence owner/Decision reference ``` The record should point to exact source paths/commits once the repository audit occurs. Do not rely on chat memory or a verbal statement that “Overdeck had this.” ## Mandatory Categories by Increment ### I0 / I1 Inventory before implementation begins: ```text Git/repository/workspace helpers publication/merge helpers K3s/offload/execution helpers factory helpers and Fabro integration knowledge account/model routing helpers configuration/auth/audit/realtime helpers CI runner/check helpers needed for I1 cleanup/recovery/checkpoint/WIP preservation logic ``` ### I2 / I3 Before Planning/autonomy implementation: ```text project onboarding helpers existing plan/requests/work-management behavior configuration policy helpers human-in-the-loop / communication behavior account selection/configuration UX behavior ``` ### I4–I8 Before their consuming increments: ```text Factory observability/chat/diff/file behavior CI impact/check/resolution helpers release/deployment/rollback helpers deployment-untangling scripts cluster enrollment/health/upgrade helpers incident/resolver scripts and recipes ``` The full inventory may be created up front, but actual code moves remain increment-scoped. ## Resolver Script Harvest Existing deterministic deployment/CI recovery scripts are not merely legacy shell code. They may encode failure classifications and remediation order learned from real incidents. Harvest them as follows: ```text existing script/helper -> identify failure class + preconditions -> isolate deterministic action from workstation assumptions -> define required capabilities/credentials -> define idempotency/retry/rollback behavior -> wrap/port as candidate ResolutionRecipe -> test against representative failure fixture -> review + VerificationEvidence -> only then mark trusted reusable recipe ``` Do not copy scripts that assume broad workstation sudo, hidden global state, mutable shared checkouts or reusable publication credentials. If a new resolver agent discovers a better procedure later, it proposes a new/superseding recipe through the same ChangeSet/Review/Verification path. ## UI / deck-ui Harvest Astryx remains the primary visual component source. When Astryx lacks required behavior: ```text inspect existing deck-ui / Overdeck implementation -> preserve useful interaction/accessibility/edge-case behavior -> remove Overdeck/deck-ui identity and accidental styling/coupling -> implement/port as AWP-owned component -> document provenance + acceptance behavior ``` Do **not** add `deck-ui` as AWP's runtime fallback library. Complex behavior should not be recreated from memory when a proven source implementation already exists. ## Platform and FOSS Cross-Check For every Overdeck harvest candidate, run the same delete-test: ```text Does project-native tooling already own it? Does platform-modules/mod now own it? Does Node/Postgres/K3s/Kubernetes already own it? Is there an accepted standard/FOSS tool that deletes the subsystem? ``` An old Overdeck implementation may be replaced rather than migrated when a cleaner accepted provider now exists. Examples: ```text custom runner daemons -> GitHub Actions + ARC custom factory graph mechanics -> Fabro custom MCP wire -> official MCP TypeScript SDK custom K3s upgrade executor -> system-upgrade-controller custom node problem daemon -> node-problem-detector custom board dragging -> Pragmatic Drag and Drop custom graph interaction -> React Flow ``` The value harvested may be tests, policy, edge cases or failure knowledge even when code is replaced. ## Import/Port Quality Rules Reused code must meet AWP architecture rather than importing legacy debt: ```text no provider types in domain no workstation-global path assumptions no hidden credentials no duplicate lifecycle authority no shared mutable checkout assumption no broad sudo/host authority for normal AgentRun no hidden config precedence no silent cleanup/destructive behavior no raw provider state becoming AWP identity ``` If removing those assumptions would effectively rewrite the implementation, retain only behavior/tests/knowledge and use `port-behavior` or a FOSS replacement. ## Harvest Gate for New Custom Code A new generic helper/subsystem in AWP is allowed only when its change/Decision states: ```text 1. required AWP semantic capability 2. Platform check result 3. Overdeck harvest check result 4. native/standard/FOSS check result 5. why available mechanics do not satisfy the contract 6. why the remaining custom code is AWP-specific or the smallest viable adapter ``` Architecture conformance/CI should eventually make this provenance easy to inspect for major subsystems. ## Deliverable Inventory The implementation-phase audit creates a living table, e.g.: | ID | Source | Capability | Target seam | Disposition | Increment | Evidence | |---|---|---|---|---|---:|---| | H-001 | Overdeck `` | deployment failure classifier | ResolutionRecipe | adapt/port | I6/I8 | fixture + review | | H-002 | deck-ui `` | diff interaction | AWP DiffViewer | port-behavior | I1/I4 | UI acceptance | | H-003 | Overdeck `` | account routing helper | AccountProvider | replace/wrap after Subrouter check | I0/I1 | provider test | Do not invent source paths before the audit actually inspects the source repositories. ## Acceptance The harvest plan is working when: - every I0/I1-relevant existing capability has an explicit disposition before equivalent custom code is written; - no proven behavior is lost simply because it was undocumented; - no personal Overdeck tooling leaks into AWP product scope; - migrated behavior conforms to AWP target seams; - FOSS/Platform replacement is preferred when it deletes more legacy complexity; - implementation reviews can answer **why this code exists in AWP instead of being reused/replaced**.