From 86bb44e1095da0539da340ce8b9fc1cab5c32f32 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Fri, 3 Jul 2026 09:05:03 +0200 Subject: [PATCH 1/9] docs(deploy): [Deploy-S2] research + plan for target-adapter archetype doctrine entry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Planning-only harness run docs (research.md, plan.md, pr-body.md) for the deployment target-adapter archetype (proposed Archetype 7). No doctrine content authored yet — gated on separate-session PLAN-EVAL PASS. Refs #338 #327 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_012wKHquACkXnWPDgJYhhFjN --- .llm/tmp/run/deploy-s2-doctrine/plan.md | 236 ++++++++++++++++++++ .llm/tmp/run/deploy-s2-doctrine/pr-body.md | 45 ++++ .llm/tmp/run/deploy-s2-doctrine/research.md | 99 ++++++++ 3 files changed, 380 insertions(+) create mode 100644 .llm/tmp/run/deploy-s2-doctrine/plan.md create mode 100644 .llm/tmp/run/deploy-s2-doctrine/pr-body.md create mode 100644 .llm/tmp/run/deploy-s2-doctrine/research.md diff --git a/.llm/tmp/run/deploy-s2-doctrine/plan.md b/.llm/tmp/run/deploy-s2-doctrine/plan.md new file mode 100644 index 000000000..08a2ff91b --- /dev/null +++ b/.llm/tmp/run/deploy-s2-doctrine/plan.md @@ -0,0 +1,236 @@ +# Plan: Deployment target-adapter archetype doctrine entry (#338 [Deploy-S2]) + +## Run Metadata + +| Field | Value | +| -------------- | ------------------------------------------------ | +| Run ID | `deploy-s2-doctrine` | +| Branch | `feat/deploy-s2-doctrine` (off `origin/main` cf1ac47b) | +| Phase | `plan` (planning-only; Implement after PLAN-EVAL PASS) | +| Target | `docs` — `docs/architecture/doctrine/` + `.llm/harness/` | +| Archetype | Authors a **new** archetype (proposed **Archetype 7 — Deployment Target Adapter**) | +| Scope overlays | `SCOPE-docs.md` (doctrine-facing docs) | + +## Archetype + +This slice **authors** doctrine; it does not build a package, so the run itself has no package +archetype — it uses `SCOPE-docs.md`. The doctrine entry it defines is a **new Archetype 7 — +Deployment Target Adapter**, framed as a deployment specialization that **composes** existing +archetypes rather than duplicating them: + +- **Archetype 2 (Integration)** supplies the port/adapter seam: a package-owned `OsServicePort` + (bare-metal: servy + systemd adapters) and cloud adapters (docker/compose/k8s/aca wrapping + `aspire publish`/`aspire deploy`/`aspire do`; deno-deploy wrapping `deno deploy`). +- **Archetype 6 (CLI/Tooling)** supplies the thin-router presentation: `netscript deploy + ` parses input and routes to an adapter; **no** target-specific business logic in the + command surface. + +Justification against the doctrine skill / A9: A9 says archetype drives package shape and "pick the +larger, fold the smaller." Archetype 7 is the *larger, named* pattern that folds A2 and A6 for the +deployment domain, giving the four adapter slices (#339 systemd, #340 deno-deploy, #342 docker/ +compose, #343 aca — per epic) a single named conformance target. The alternative (B: a subtype under +A2 + a note under A6) is recorded in the Open-Decision Sweep for PLAN-EVAL ratification. + +## Current Doctrine Verdict + +`docs/architecture/doctrine/10-codebase-verdict-and-handoff.md` is a frozen 2026-04 snapshot (per +#305 audit) and does not cover deployment. **N/A** for this entry — the deployment archetype is +net-new and adds no package verdict. (The eventual `deploy-core` extraction ties into the existing +`packages/cli — AP-1` "command registry/deploy target seams" debt entry; see Arch-Debt Implications.) + +## Axioms in Play + +| Axiom | Why it matters | +| ----- | -------------- | +| A9 | Archetype drives package shape; Archetype 7 folds A2+A6 for deployment (pick-larger rule). | +| A11 | Name extension axes before abstraction — the **target** is the named extension axis; each target is an adapter behind a stable port, not a new abstraction layer. | +| A2 | Simple over easy at boundaries — one uniform 7-op adapter contract across every target. | +| A5 | Composition over inheritance — targets compose the shared base config (#337) + implement the port; no target base-class hierarchy. | +| A13 | Crash boundaries explicit — bare-metal health-gated activation + `rollback`; cloud rollback maps to platform-native mechanisms. | +| A7 | Web Platform / upstream first — wrap `aspire`/`deno compile`/`deno deploy`/`servy`, do not reinvent. | + +## Goal + +A doctrine-canonical **Archetype 7 — Deployment Target Adapter** entry that: (1) names the +`OsServicePort` / cloud-adapter port seam and the uniform 7-op adapter contract +(`plan/emit · up · down · status · logs · rollback · secrets`); (2) codifies the thin-CLI-router law +(no target business logic in the command surface; convention-bearing primitives — health, OTEL, +secrets, rollback — live in a core, not per-target); (3) states its gates and debt rules; (4) is +written to be absorbed by #305's doctrine revamp (durable prose, named `F-DEPLOY-*` gates seeded +`reviewed`, no frozen tables, no dead citations). Adapter slices #339–#343 must conform to it. + +## Scope + +- **Doctrine:** append "Archetype 7 — Deployment Target Adapter" to + `docs/architecture/doctrine/06-archetypes.md` (Minimum shape, "Doctrine for this archetype", + checklist rows); update the `## How to choose` decision order (add step 7) and the + `## Archetype assignments for current packages` table (deploy target-adapter row). +- **Harness:** add `.llm/harness/archetypes/ARCHETYPE-7-deploy-target-adapter.md`; add a decision- + order row to `.llm/harness/archetypes/README.md`; add an **Arch 7** column + + `F-DEPLOY-*` archetype-specific gate rows to `.llm/harness/gates/archetype-gate-matrix.md`. +- **Debt:** add an arch-debt entry recording (a) the future `deploy-core` centralization obligation + and (b) that `F-DEPLOY-*` are seeded `reviewed` until #339+ land — with a closing gate. +- **#305 cross-reference note** inside the Archetype 7 prose so the revamp absorbs it. + +## Non-Scope + +- **No** implementation of `OsServicePort`, adapters, or CLI routing (Phase 1+, #339–#343). +- **No** edit to `deploy-schema.ts` — the config contract is #337 (PR #352), already landed. +- **No** renumber/restructure of the doctrine files — that is #305's job; #338 only appends. +- **No** `.claude/` config/skills/hooks/agent-orchestration changes → `validate-claude-surface.ts` + is **N/A** (this slice touches `docs/` + `.llm/harness/`, not the Claude surface). +- **No** new labels / umbrella issue (spec §7 item 3 is a separate Phase-0 task, not this slice). + +## Hidden Scope + +- The harness has **three** archetype surfaces that must stay in lockstep (doctrine `06-archetypes.md`, + `.llm/harness/archetypes/README.md` + `ARCHETYPE-N.md`, and `archetype-gate-matrix.md`). Adding an + archetype to only one is a consistency defect the doctrine-lint / evaluator will catch. +- `06-archetypes.md` "How to choose" is a *numbered* decision order — inserting Archetype 7 means the + new step must slot correctly relative to A6 (a deploy adapter that is *only* a CLI flow with no + port stays A6; Archetype 7 applies when the port/adapter seam + multi-target routing exist). +- The archetype must be **package-agnostic** (encode the LAW, per #305) — name the seam and the + contract, not a specific `deploy-core` package that does not exist yet. + +## Locked Decisions + +| ID | Decision | Rationale | +| --- | -------- | --------- | +| D1 | New **Archetype 7 — Deployment Target Adapter** (composes A2 + A6), appended to `06-archetypes.md`. | Epic calls it an archetype; gives #339–#343 one named conformance target; A9 pick-larger-fold-smaller. | +| D2 | Uniform 7-op adapter contract: `plan/emit · up · down · status · logs · rollback · secrets`. | Directly from spec §4; every target implements a subset; Aspire adapters delegate `up/plan`. | +| D3 | Port seam named `OsServicePort` (bare-metal) + cloud-adapter; thin-CLI-router law is mandatory doctrine. | Spec §5.1, §3.1; plugin-thinness/core-centralization law. | +| D4 | Back the archetype with named `F-DEPLOY-1` (adapter implements the 7-op contract) and `F-DEPLOY-2` (no target business logic in command surface), seeded **`reviewed`** not `gated`. | #305 registry model; deployment packages are future-wave (#339+ unbuilt). | +| D5 | Write durable archetype prose only — no frozen verdict tables, no `../phase-0-research/*` citations; add a `#305` cross-reference note. | #305 is purging dead links + separating constitution from generated state; entry must be absorbable. | +| D6 | Convention-bearing primitives (health, OTEL, secrets, rollback) are doctrine-required to live in a **core**, not per-target. | Plugin-thinness/core-centralization law; spec §7 item 5. | +| D7 | Stay package-agnostic — name the seam + contract, not a concrete `deploy-core` package. | Encode the LAW (#305); the package does not exist yet. | +| D8 | `deploy.targets.*` clean break is **already contract-first done** by #337 (PR #352); this slice only *references* the base, does not restate the migration. | Avoid duplicating #337; spec §3.3 D5 clean break. | + +## Open-Decision Sweep + +| Decision | Status | Notes | +| -------- | ------ | ----- | +| Archetype 7 (A) vs A2-subtype (B) shape | safe to defer to PLAN-EVAL | Recommend (A); evaluator ratifies the doctrine-shape judgment. Non-blocking. | +| `F-DEPLOY-*` exact IDs/count | safe to defer | Proposed `F-DEPLOY-1/2`; PLAN-EVAL may realign with #305's fitness-registry naming. Seeded `reviewed`. | +| Name the future `deploy-core` package in prose? | resolved now (D7) | Stay package-agnostic; name the seam only. | +| Add labels / umbrella (spec §7 item 3) | out of scope | Separate Phase-0 task, not #338. | + +> No decision is marked "must resolve now" — all are resolved (locked) or safe to defer to PLAN-EVAL. + +## Risk Register + +| Risk | Mitigation | +| ---- | ---------- | +| #305 renumber later moves/renames `06-archetypes.md`, orphaning the entry. | Write absorbable prose + inline `#305` cross-reference note; record coordination stance in research.md so #305 folds it in. No live #305 branch today → no merge conflict now. | +| Archetype added to doctrine but not to the two harness surfaces (or vice versa) → inconsistency. | Slice 2 updates all three surfaces atomically; validation runs `arch:check` + a manual three-surface consistency check. | +| Over-specifying a `deploy-core` package that does not exist yet. | D7: package-agnostic prose; name only the seam + op contract. | +| Gate seeded as `gated` would red CI against unbuilt packages. | D4: seed `F-DEPLOY-*` as `reviewed`, mirroring #305's ch06 approach. | + +## Anti-Patterns to Resolve or Avoid + +| AP | Status | Plan | +| -- | ------ | ---- | +| AP-1 (god file / oversized) | risk (future impl) | Archetype prose mandates thin router + one-adapter-per-file; not a concern for the doctrine text itself. | +| AP-11 (premature abstraction) | avoid | A11: the *target* is the named extension axis; do not introduce a port until a 2nd adapter is foreseeable (it is — servy+systemd+cloud), so the port is justified, not premature. | +| AP (plugin-thinness violation) | avoid | D3/D6 codify the thin-router + core-centralization law as doctrine. | + +## Fitness Gates + +| Gate | Required | Expected evidence | +| ---- | -------- | ----------------- | +| `arch:check` (doctrine-lint, `check-doctrine.ts`) | yes | Runs clean after the `06-archetypes.md` append — no dead links, no AP/F ref break introduced. | +| Three-surface consistency (doctrine ↔ README ↔ gate-matrix) | yes | Manual: Archetype 7 present + coherent in all three; decision-order + assignments table updated. | +| `F-DEPLOY-1` (7-op adapter contract) | seeded `reviewed` | Defined in the new entry + gate-matrix; not enforced until #339+ land. | +| `F-DEPLOY-2` (no target business logic in command surface) | seeded `reviewed` | Defined in the new entry + gate-matrix; enforced at Phase-1 impl. | +| `validate-claude-surface.ts` | no (N/A) | Slice touches `docs/` + `.llm/harness/`, not `.claude/` — recorded N/A. | +| `deno task fmt:check` (scoped, docs) | yes | Markdown reflow clean on the edited doctrine/harness files. | + +## Commit-Slice List (Implement phase — after PLAN-EVAL PASS) + +Each slice is a single commit with trailers `Refs #338 #327`, committed → pushed → PR-commented, +then appended to `commits.md`. + +**Slice 1 — Doctrine: Archetype 7 entry.** +- Proves: the deployment target-adapter pattern is doctrine-canonical with a named op contract + + thin-router law + core-centralization rule + checklist. +- Files: `docs/architecture/doctrine/06-archetypes.md` (append `## Archetype 7 — Deployment Target + Adapter` after Archetype 6; add step 7 to `## How to choose`; add a row to `## Archetype + assignments for current packages`; add checklist rows). Includes the inline `#305` cross-ref note. +- Gate: `arch:check` clean; `fmt:check` clean; manual doctrine read. + +**Slice 2 — Harness: archetype selection + gate matrix.** +- Proves: the harness can *select* and *gate* Archetype 7 (all three archetype surfaces in lockstep). +- Files: new `.llm/harness/archetypes/ARCHETYPE-7-deploy-target-adapter.md`; `.llm/harness/archetypes/ + README.md` (decision-order row); `.llm/harness/gates/archetype-gate-matrix.md` (Arch 7 column + + `F-DEPLOY-*` archetype-specific gate rows, seeded `reviewed`). +- Gate: three-surface consistency check; `fmt:check` clean. + +**Slice 3 — Debt: deploy-core centralization + gate-seed record.** +- Proves: future adapter slices (#339–#343) have a closing gate; the `deploy-core` extraction is + tracked against the existing `packages/cli` deploy-target-seams debt. +- Files: `.llm/harness/debt/arch-debt.md` (new `## deployment — Archetype-7 core-centralization + + F-DEPLOY seed` entry; owner, target = Phase-1 #339+, closing gate = `F-DEPLOY-1/2` promoted + `gated`; cross-links the existing `packages/cli — AP-1` "command registry/deploy target seams"). +- Gate: debt-registry format consistency; `fmt:check` clean. + +## Exact Doctrine Files + Anchors + +| File | Edit | Anchor (verified present) | +| ---- | ---- | ------------------------- | +| `docs/architecture/doctrine/06-archetypes.md` | insert new section | after `## Archetype 6 — CLI / Tooling Package`, before `## How to choose` | +| `docs/architecture/doctrine/06-archetypes.md` | add decision step 7 | `## How to choose` (numbered list, currently 1–6) | +| `docs/architecture/doctrine/06-archetypes.md` | add table row | `## Archetype assignments for current packages` | +| `docs/architecture/doctrine/06-archetypes.md` | add checklist rows | `## Archetype checklist for review` | +| `.llm/harness/archetypes/ARCHETYPE-7-deploy-target-adapter.md` | new file | — | +| `.llm/harness/archetypes/README.md` | add row | `## Decision Order` table | +| `.llm/harness/gates/archetype-gate-matrix.md` | add column + gates | `## Fitness Gates` table + `## Archetype-specific Gates` (`F-DEPLOY-*`) | +| `.llm/harness/debt/arch-debt.md` | new entry | append (`## — ` format) | + +## #305 Coordination Stance + +- #305 is OPEN at RFC stage, **no live branch** → no merge collision now. Coordination is + forward-looking: write Archetype 7 so #305 absorbs it into the revamped archetype chapter and its + `F-DEPLOY-*` rows into `11-fitness-registry`. +- Constraints imposed by #305 (all locked as D4/D5): durable prose, named testable gates seeded + `reviewed`, no frozen tables, no dead `../phase-0-research/*` citations, inline cross-ref note. +- Recorded in `research.md` (#305 coordination section). PLAN-EVAL should confirm the entry does not + conflict with #305's package-graph chapter (ch06-new) — it does not: Archetype 7 is a package + *shape*, orthogonal to the package-*graph* law. + +## Validation Plan + +| Order | Gate | Command or check | Expected result | +| ----- | ---- | ---------------- | --------------- | +| 1 | Anchor pre-check | `rtk grep "## Archetype 6" docs/architecture/doctrine/06-archetypes.md` (+ How to choose, assignments) | anchors present before editing | +| 2 | Doctrine-lint | `rtk proxy deno task arch:check` | PASS — no dead links / ref breaks from the append | +| 3 | Docs fmt (scoped) | `deno run --allow-read --allow-run .llm/tools/run-deno-fmt.ts --root docs/architecture/doctrine --ext md` | clean (no reflow diff) | +| 4 | Three-surface consistency | manual: Archetype 7 in `06-archetypes.md` + `archetypes/README.md` + `gate-matrix.md`; decision-order + assignments updated | consistent | +| 5 | Claude surface | N/A (no `.claude/` change) — record N/A | N/A | +| 6 | Debt-registry format | manual: new entry matches `## — ` shape + has owner/target/closing gate | consistent | + +## Arch-Debt Implications + +| Entry | Action | Notes | +| ----- | ------ | ----- | +| `## deployment — Archetype-7 core-centralization + F-DEPLOY seed` | **create** (Slice 3) | Tracks the future `deploy-core` extraction + `F-DEPLOY-*` `reviewed→gated` promotion when #339–#343 land. Owner: deployment epic #327. Closing gate: `F-DEPLOY-1/2` promoted `gated`. | +| `packages/cli — AP-1` "command registry/deploy target seams" (existing, ~L379) | **cross-link** | The OsServicePort extraction from the CLI feature ties into this existing restructure debt; do not duplicate — reference it. | + +## Risks + +- See Risk Register above. Primary risk is #305 orphaning the entry — mitigated by absorbable prose + + cross-ref note + research.md coordination record. + +## Dependencies + +- **#337 / PR #352** (`feat/deploy-s1-targets-config`) — the config contract the archetype references + (`DeployTargetBaseSchema`). Landed; this slice only cites it, does not depend on merge order. +- **#305** — forward coordination only; not a blocker. +- Deployment epic **#327** — parent; this is Phase 0. + +## Drift Watch + +- If #305 opens an implementation branch that renumbers `06-archetypes.md` before this lands → + rebase the append onto the new file name; log to `drift.md`. +- If PLAN-EVAL rules for shape (B) over (A) → rescope Slice 1 to a subtype under A2 + note under A6; + log `significant` drift. +- If the adapter op set changes in a later epic decision (e.g. adds `secrets` sub-verbs) → update the + contract in the entry; log to `drift.md`. diff --git a/.llm/tmp/run/deploy-s2-doctrine/pr-body.md b/.llm/tmp/run/deploy-s2-doctrine/pr-body.md new file mode 100644 index 000000000..226de2e27 --- /dev/null +++ b/.llm/tmp/run/deploy-s2-doctrine/pr-body.md @@ -0,0 +1,45 @@ +## [Deploy-S2] Deployment target-adapter archetype doctrine entry — RESEARCH + PLAN + +Phase 0 of the deployment epic (#327). This PR is **planning-only**: it lands the harness run +docs (`research.md` + `plan.md`) for the doctrine entry. **It does not author the doctrine change +itself** — that is the Implement phase, gated on a separate-session **PLAN-EVAL PASS**. + +Closes #338 +Refs #327 + +### Summary + +Plans a new **Archetype 7 — Deployment Target Adapter** doctrine entry describing how a deploy +target (windows/servy, systemd, deno-deploy, docker/compose, k8s, aca) is structured: + +- **Port seam:** generalize `WindowsServicePort` → `OsServicePort` (servy + systemd adapters); + cloud targets wrap `aspire publish`/`aspire deploy`/`aspire do`; deno-deploy wraps `deno deploy`. +- **Uniform 7-op adapter contract:** `plan/emit · up · down · status · logs · rollback · secrets`. +- **Thin-CLI-router law:** no target business logic in the command surface; convention-bearing + primitives (health, OTEL, secrets, rollback) live in a **core**, not per-target. +- **Config base:** each target's config member extends `DeployTargetBaseSchema` from #337 (PR #352). +- Archetype 7 **composes** Archetype 2 (Integration port/adapters) + Archetype 6 (CLI thin router) + per A9's pick-larger-fold-smaller rule; it is the conformance target for adapter slices #339–#343. + +### Scope + +- **In:** `research.md`, `plan.md` (this PR). Plans edits to + `docs/architecture/doctrine/06-archetypes.md`, `.llm/harness/archetypes/*`, and + `.llm/harness/gates/archetype-gate-matrix.md`, plus an arch-debt entry — **for the Implement + phase, not this PR.** +- **Out:** no `OsServicePort`/adapter/CLI implementation (Phase 1+); no `deploy-schema.ts` edit + (that is #337); no doctrine renumber (that is #305); no labels/umbrella issue. + +### #305 coordination + +#305 (Architecture Doctrine revamp, RFC, OPEN, no in-flight branch) will renumber/restructure the +doctrine and stand up a fitness registry. The planned entry is written to be **absorbed** by #305: +durable archetype prose, named `F-DEPLOY-*` gates seeded `reviewed` (not `gated`, since #339+ are +unbuilt), no frozen tables, no dead `../phase-0-research/*` citations, and an inline `#305` +cross-reference. Archetype 7 (package *shape*) is orthogonal to #305's package-*graph* chapter. + +### Status + +- [ ] **PLAN-EVAL** (separate session, OpenHands) — required PASS before any doctrine content is + authored. +- Planning-only until PLAN-EVAL PASS. Do not merge as an implementation. diff --git a/.llm/tmp/run/deploy-s2-doctrine/research.md b/.llm/tmp/run/deploy-s2-doctrine/research.md new file mode 100644 index 000000000..53c2845e8 --- /dev/null +++ b/.llm/tmp/run/deploy-s2-doctrine/research.md @@ -0,0 +1,99 @@ +# Research — deploy-s2-doctrine (#338 [Deploy-S2]) + +Slice: Deployment target-adapter archetype doctrine entry. Phase 0 of deployment epic #327. +Author: Claude Opus 4.8 (RESEARCH+PLAN only; no doctrine content authored here — that is the +Implement phase after PLAN-EVAL PASS). + +## Re-baseline + +- Carried-in source: deployment architecture spec + decision-gap tracker in + `.claude/worktrees/deployment-research/.llm/tmp/run/epic-deployment-aggregation/` + (`deployment-architecture-spec.md` §7 "Doctrine impact", item 1). +- Re-derived against `origin/main` @ `cf1ac47b` (worktree branch `feat/deploy-s2-doctrine`). +- #337's config contract has landed on branch `feat/deploy-s1-targets-config` (PR **#352**, OPEN): + `packages/config/src/domain/schemas/deploy-schema.ts` now exports `DeployTargetBaseSchema` + (shared base raw-shape), `WindowsDeployTargetSchema` (base spread + Servy fields), and + `DeployConfigSchema` (`targets.windows` only). Adapter slices #339+ compose the base by spread. +- What changed vs the carried-in spec: nothing material to the doctrine framing. The spec's + "clean break" (D5) and "OsServicePort" seam are confirmed by the landed #337 shape (base + + member composition, no back-compat alias, `docker` sub-block carried under the base for later + migration to the docker/compose target). + +## Findings + +| # | Finding | How to verify | +| -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| 1 | Doctrine archetypes live in `docs/architecture/doctrine/06-archetypes.md`; six archetypes (1 Small Contract … 6 CLI/Tooling), each with "Minimum shape" + "Doctrine for this archetype" + a checklist. Append-only. | `06-archetypes.md` | +| 2 | The archetype file has stable anchors this slice edits: `## Archetype 6 — CLI / Tooling Package`, `## How to choose` (numbered decision order), `## Archetype assignments for current packages` (table), `## Archetype checklist for review`. | `06-archetypes.md` §headings | +| 3 | Governing axiom is **A9** ("Archetype drives package shape"). The "How to choose" rule: if two archetypes apply, pick the larger and fold the smaller in; do not split a package across two. | `06-archetypes.md` L232–247; doctrine skill axiom table | +| 4 | The deploy feature today lives **inside** `packages/cli` (`src/public/features/deploy/deploy-group.ts`), Archetype 6. The epic generalizes `WindowsServicePort` → `OsServicePort` (servy + systemd adapters) and adds cloud adapters wrapping `aspire publish/deploy`. | spec §3.1, §5.1 | +| 5 | The per-target **adapter contract** is a uniform op set: `plan/emit`, `up`, `down`, `status`, `logs`, `rollback`, `secrets`. Aspire-driven adapters delegate `up/plan` to the Aspire CLI; direct adapters (windows/linux/deno-deploy) implement natively. | spec §4 (adapter contract line), §3.1 | +| 6 | The command surface must stay a **thin router** (plugin-thinness / core-centralization law): no target-specific business logic in the command layer; convention-bearing primitives (health, OTEL, secrets, rollback) live in a core, not per-target. | spec §3.1, §7 item 5; MEMORY plugin-thinness law | +| 7 | Per-target **tiers**: Tier 1 = Deno Deploy, deno-compile bare-metal (linux/windows), Docker/Compose; Tier 2 = k8s, Azure (ACA/AppService/AKS), GCP Cloud Run, Koyeb, DO/Render; Tier 3 (track) = Vercel/CF Workers/AWS Lambda (no first-party Deno runtime). | spec §4 target table | +| 8 | SERVY verdict = **MODERNIZE** (upstream healthy; rot is NetScript-side: no Linux, doc/code drift, no rollback/multi-instance, weak secrets, dead docker/script config, `deno:2.5` pin). Bare-metal artifact = `deno compile` single binary (ADOPT). | spec §5, servy-assessment | +| 9 | `arch:check` = `deno run --allow-read .llm/tools/fitness/check-doctrine.ts` (the doctrine fitness lint). This is the doctrine-lint gate for the slice. | `deno.json` L42 | +| 10 | The harness archetype gate matrix (`.llm/harness/gates/archetype-gate-matrix.md`) has columns Arch 1–6 and an "Archetype-specific Gates" section reserving the `F--*` namespace (e.g. `F-CLI-*`) for archetype-specific gates. Future archetypes "may publish their own gate IDs in the same namespace pattern (`F-SVC-*`, `F-PLG-*`)". | gate-matrix.md L36–44 | +| 11 | arch-debt.md uses `## — ` headers. Line ~379 already records `packages/cli — AP-1` restructure debt naming **"command registry/deploy target seams"** — the eventual OsServicePort extraction ties into that existing entry. | `arch-debt.md` | +| 12 | Harness archetype selection is mirrored in `.llm/harness/archetypes/README.md` (decision-order table + one `ARCHETYPE-N-*.md` file per archetype). A new archetype needs a matching `ARCHETYPE-7-*.md` + a README row + a gate-matrix column. | README.md L11–20 | + +## #305 coordination (MUST — recorded state + fit) + +- **#305 [S4] Architecture Doctrine revamp** — state **OPEN**, labels `type:docs` `area:tooling` + `priority:p1` `rfc`, parent epic #301. **No in-flight PR/branch** (searched + `archetype OR 305 OR doctrine`, all=merged/unrelated). So #305 is still at RFC/issue stage — + there is **no live branch collision**; coordination is forward-looking (write to be absorbed). +- #305's blueprint **renumbers and restructures** the whole doctrine `01..10-*.md` into a new + ~12-file layout (`00-constitution`, `04-folders-and-layering`, `06-package-graph-and-plugin-thinness` + (NEW), `11-fitness-registry`, `appendix/verdicts.generated.md`, …). Key #305 principles that + bind my entry: + 1. **Separate constitution (durable prose) from live state (generated).** → my archetype entry + must be durable archetype prose with **no frozen verdict tables** and **no dead + `../phase-0-research/*` citations** (which #305 is purging). + 2. **Fitness registry = single source of truth** that both prose and `check-*.ts` read; every + principle earns its place only with a **named, testable gate.** → back the deployment + archetype with named gate IDs (`F-DEPLOY-*`) so the entry slots straight into #305's registry. + 3. **Seed new-area gates as `reviewed`, not `gated`, until the packages exist** (#305 does exactly + this for its own new ch06 gate, "encode the LAW not the current package list"). → the + deployment packages are **future-wave** (#339–#343 not built yet), so seed `F-DEPLOY-*` as + `reviewed`. +- **Fit / stance:** add "Archetype 7 — Deployment Target Adapter" to the **current** + `06-archetypes.md` (append-only), written so #305's revamp absorbs it verbatim into the new + archetype chapter and its gate rows into `11-fitness-registry`. Record a cross-reference note so + #305 does not drop it during the renumber. This **extends** #305's structure (a new archetype + + named gates it will registry-ize) rather than conflicting with it. #338 does not touch the files + #305 renumbers other than the append to `06-archetypes.md`. + +## Doctrine framing question (for the plan to lock / PLAN-EVAL to ratify) + +The deployment target-adapter is a **cross-package composite**: an Integration-shaped +port + adapters core (Archetype 2 — `OsServicePort`/cloud-adapter + servy/systemd/aspire adapters) +consumed by a thin CLI router (Archetype 6). Two viable doctrine shapes: + +- **(A) New named "Archetype 7 — Deployment Target Adapter"** that explicitly *composes* A2's + port/adapter seam and A6's thin-router law (folds, does not duplicate). Pro: the epic calls it an + archetype; the four adapter slices #339/#340/#342/#343 get **one** named conformance target; it is + foundational and repeated. Con: archetypes are nominally "package shape" (A9) and this spans two + packages — mild tension, resolved by stating the composite explicitly. +- **(B) A specialization sub-section** under Archetype 2 ("Integration — deployment target + adapter subtype") plus a note under Archetype 6. Pro: strict A9 fidelity. Con: splits the pattern + across two doctrine locations; no single conformance anchor for the adapter slices. + +Recommendation: **(A)**, framed as a deployment specialization that composes A2 + A6. Locked in +plan; flagged in the open-decision sweep for PLAN-EVAL ratification (it is a doctrine-shape +judgment the evaluator should confirm, not a blocker). + +## jsr-audit surface scan + +- N/A for this wave — it is a **doctrine + harness-docs** change (`docs/architecture/doctrine/`, + `.llm/harness/`). No `packages/*` public surface, no `mod.ts`, no exports change. State recorded + per template. + +## Open questions + +- Archetype (A) vs (B) shape — recommendation (A); PLAN-EVAL to ratify. (Non-blocking.) +- Exact `F-DEPLOY-*` gate count/wording — plan proposes `F-DEPLOY-1` (7-op adapter contract) and + `F-DEPLOY-2` (no target business logic in command surface / thin-router). Seeded `reviewed`. + PLAN-EVAL may adjust IDs to align with #305's registry naming. +- Whether the archetype prose should name a future `deploy-core` package explicitly or stay + package-agnostic (encode the LAW, per #305). Plan: stay package-agnostic; name only the seam + (`OsServicePort`, cloud-adapter) and the op contract. From 8978c28f79d450b6d5613ba0f3f695f55b86ed56 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Fri, 3 Jul 2026 09:10:55 +0200 Subject: [PATCH 2/9] chore(harness): record PLAN-EVAL PASS_PLAN for deploy-s2 doctrine Doctrine-shape (A) ratified; 4 non-blocking Implement-phase fixes (F1 intro count, F2 no assignments-table row, F3 both matrix tables, F4 arch:check scope). Plan-Gate cleared. Refs #338 #327 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_012wKHquACkXnWPDgJYhhFjN --- .llm/tmp/run/deploy-s2-doctrine/plan-eval.md | 103 +++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 .llm/tmp/run/deploy-s2-doctrine/plan-eval.md diff --git a/.llm/tmp/run/deploy-s2-doctrine/plan-eval.md b/.llm/tmp/run/deploy-s2-doctrine/plan-eval.md new file mode 100644 index 000000000..833bdbb80 --- /dev/null +++ b/.llm/tmp/run/deploy-s2-doctrine/plan-eval.md @@ -0,0 +1,103 @@ +**[PHASE: PLAN-EVAL] [VERDICT: PASS_PLAN]** + +Run: `deploy-s2-doctrine` — slice #338 [Deploy-S2] of deployment epic #327. Evaluator session +separate from plan author. Reasoning: HIGH. This is a **plan gate**, not an impl review — no code is +expected to exist. Verdict: **PASS_PLAN** with four required, non-blocking Implement-phase fixes +(F1–F4) recorded below. The A-vs-B doctrine-shape choice is **ratified as (A)**, conditioned on F2. + +## Checklist results + +| Check | Result | Evidence / note | +| ----- | ------ | --------------- | +| Research current | PASS | Re-baselined to `origin/main` cf1ac47b; #337/PR#352 landed shape (`DeployTargetBaseSchema` + `WindowsDeployTargetSchema`) confirmed; #305 confirmed OPEN/RFC with no in-flight branch. | +| Anchors verified against real `06-archetypes.md` | PASS | I read the file: `## Archetype 6 — CLI / Tooling Package` (L191), `## How to choose` numbered 1–6 (L234–242), `## Archetype assignments for current packages` (L249), `## Archetype checklist for review` (L273) all present. Insert-after-6 / before How-to-choose is a clean fit; no renumber collision (1..6 → append 7). | +| Decisions locked | PASS | D1–D8 each carry a decision + rationale; unambiguous. | +| Open-decision sweep complete | PASS | 4-row table; all resolved or safe-to-defer; explicit "no decision marked must-resolve-now". A-vs-B correctly routed to PLAN-EVAL (it is a doctrine-shape judgment, an evaluator call). | +| Commit-slice list (<30; each names proof + gate + files) | PASS | 3 slices (doctrine / harness-3-surface / debt), each with Proves + Files + Gate. Well under 30. | +| Risk register | PASS | Risk Register + Risks + Drift Watch cover #305 orphaning, 3-surface drift, over-abstraction, gate-seed-as-gated. | +| Correct gate SET for a doctrine slice | PASS (with F4 wording fix) | Set = arch:check + docs fmt:check + 3-surface manual consistency + validate-claude-surface N/A. Set is right; the *evidence claim* for arch:check is overstated — see F4. | +| `validate-claude-surface.ts` N/A verified | PASS | Slice edits `docs/` + `.llm/harness/` only. `.llm/harness/` is NOT `.claude/`; no Claude-surface file is implied. N/A is correct. | +| Deferred scope explicit | PASS | Non-Scope covers: no impl, no `deploy-schema.ts` edit (#337 owns it), no doctrine renumber (#305 owns it), no `.claude/` change, no labels/umbrella. | +| #305 coordination stance | PASS | No live branch → no collision now; absorbable durable prose; gates seeded `reviewed` not `gated`; no frozen tables; no dead `../phase-0-research/*` citations; inline #305 cross-ref note; orthogonal to #305's package-*graph* chapter (this is package *shape*). | +| F-DEPLOY-* namespace fit | PASS | Gate-matrix reserves the `F--*` pattern and cites `F-SVC-*`/`F-PLG-*`; precedent `F-CLI-1…31` documented in the archetype file. `F-DEPLOY-*` conforms. | + +## A-vs-B ratification — RATIFY (A) + +**Ratified: (A) new named "Archetype 7 — Deployment Target Adapter" that composes A2 + A6.** + +Reasoning weighed both sides honestly: + +- Counter-argument for (B): the doctrine defines an archetype as a *per-package* selector ("every + `packages/*`/`plugins/*` package picks the smallest archetype that fits"), and it already models + specializations as **subtypes**, not new top-level archetypes — `sagas` is listed as + "3 — Runtime/Behavior with state-machine specialization", and the gate-matrix uses `subtype` rows + (F-13). That precedent leans toward (B). +- Decisive argument for (A): unlike `sagas` (one package), the deployment pattern is a genuine + **cross-package composite** — an A2-shaped `OsServicePort`/cloud-adapter core consumed by an A6 + thin CLI router. Neither A2 nor A6 alone captures it, so a B-style subtype would fragment the + pattern across two doctrine locations with **no single conformance anchor** for the four adapter + slices (#339/#340/#342/#343). The epic itself names it an archetype, and it is foundational and + repeated. One named conformance target has real operational value and is the cheaper long-run + doctrine. + +Condition on the ratification (folded into F2): (A) must be framed as a **named composite pattern**, +not as a 7th entry in the "pick the smallest that fits" *package* selector that a single package +would choose over its true shape. The plan already does this well (D1 + the Archetype section +"composes A2+A6, folds not duplicates"; Hidden Scope: "a deploy adapter that is only a CLI flow with +no port stays A6; Archetype 7 applies when the port/adapter seam + multi-target routing exist"). The +only place this can leak is the assignments table — see F2. + +## Required fixes (Implement phase; recorded, non-blocking to the plan gate) + +**F1 — Update the archetype count sentence.** `06-archetypes.md` L8–9 reads "This page defines +**six** archetypes". Adding Archetype 7 makes that stale. Slice 1's file list omits this edit. +`check-doctrine.ts` does **not** parse this markdown, so nothing will auto-catch it — add "seven" +(and the intro/​list count) to Slice 1 explicitly. + +**F2 — Resolve the assignments-table vs D7 tension.** Scope + the anchors table say Slice 1 adds a +"deploy target-adapter row" to `## Archetype assignments for current packages`, but D7 says stay +package-agnostic and no `deploy-core` package exists yet (deploy currently lives *inside* +`packages/cli`, which is Archetype 6). Adding a row naming a non-existent package contradicts both +D7 and the table's "current packages" scope. Resolve by either (a) omitting the assignments row for +this slice, or (b) adding a clearly-marked **future/pending** row (e.g. "future `deploy-core` → 7 +(not yet extracted; today folded in `cli`)"). Do **not** relabel `cli` off Archetype 6. This is the +one internal contradiction in the plan and must be settled before Slice 1. + +**F3 — Add Arch 7 to BOTH gate-matrix tables.** `archetype-gate-matrix.md` has two Arch-1..6 column +tables: `## Fitness Gates` (L15) **and** `## Other Gate Families` (L47). The plan's anchors table +names only the Fitness Gates table for the new Arch 7 column. To make the "three-surface +consistency" gate actually true, add an Arch 7 column to **both** tables (or state explicitly that +Other Gate Families inherits Arch 6's row for Arch 7). Otherwise the second table silently omits +Archetype 7. + +**F4 — Correct the `arch:check` evidence claim.** Verified: `deno task arch:check` = `deno task +deps:check && check-doctrine.ts --root `. `check-doctrine.ts` +walks a **package's TS source** (mod.ts, abstract classes, folder cardinality, casts) — it does +**not** read `06-archetypes.md` and **cannot** detect "dead links / AP-F ref breaks" in the doctrine +markdown. So the Fitness-Gates row claiming arch:check "runs clean after the append — no dead links, +no AP/F ref break introduced" **overstates** what the gate proves; running it is a regression sanity +that is simply *unaffected* by this markdown edit (and can even flake on the `deps:check` network +step, unrelated to the slice). The gate SET is still correct, but re-word the expected evidence: the +real proof for the doctrine/harness markdown is **`fmt:check` (scoped) + the manual three-surface +consistency read**; arch:check is only a "did not regress the evaluated packages" check. + +## Confirmations (good as written) + +- Anchors: all four `06-archetypes.md` anchors present and correctly targeted; append fits 1..6 + without renumber. Verified by direct read. +- Decision-order step 7 guard correctly prevents a plain-CLI deploy flow from mis-selecting 7 over 6 + (port + multi-target routing is the trigger). +- #305: no live branch (research search corroborated) → no merge collision now; forward-absorb + stance, `reviewed`-seeded gates, no frozen tables, no dead citations, cross-ref note — all sound + and consistent with #305's "encode the LAW, seed reviewed until packages exist" model. +- `validate-claude-surface.ts` N/A is correct — no `.claude/` file is touched or implied. +- Debt slice cross-links the existing `packages/cli — AP-1` "command registry/deploy target seams" + entry rather than duplicating; closing gate = `F-DEPLOY-1/2` promoted `reviewed→gated`. Correct. + +## Verdict + +**PASS_PLAN.** The plan is executable, correctly scoped, gate-set-correct, and coordinates soundly +with #305. Doctrine-shape choice **(A)** is ratified. F1–F4 are precise Implement-phase fixes (one +genuine internal contradiction in F2, three consistency/accuracy corrections) that do not block the +plan gate — apply them during Implement and verify via `fmt:check` + the three-surface consistency +read. From 778979732f8bd30aa733be31e1b6466f1f3d04d2 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Fri, 3 Jul 2026 09:17:24 +0200 Subject: [PATCH 3/9] =?UTF-8?q?docs(doctrine):=20add=20Archetype=207=20?= =?UTF-8?q?=E2=80=94=20Deployment=20Target=20Adapter=20(composes=20A2+A6)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Append a new "Archetype 7 — Deployment Target Adapter" entry to 06-archetypes.md: a composite archetype that folds Archetype 2 (OsServicePort + servy/systemd/aspire/deno-deploy adapters) and Archetype 6 (thin CLI router) per the pick-larger-fold-smaller rule. Names the uniform 7-op adapter contract, the thin-router + core-centralization law, and the DeployTargetBaseSchema (#337) config-extension rule. Updates the intro count to seven (F1), adds decision step 7, a clearly-marked future deploy-core assignments row without relabelling cli (F2), two review-checklist rows, and a #305 cross-reference note. Refs #338 #327 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_012wKHquACkXnWPDgJYhhFjN --- docs/architecture/doctrine/06-archetypes.md | 90 ++++++++++++++++++++- 1 file changed, 89 insertions(+), 1 deletion(-) diff --git a/docs/architecture/doctrine/06-archetypes.md b/docs/architecture/doctrine/06-archetypes.md index 54f02162f..66406e5eb 100644 --- a/docs/architecture/doctrine/06-archetypes.md +++ b/docs/architecture/doctrine/06-archetypes.md @@ -4,7 +4,7 @@ Axioms governed: A9. One folder layout for every package is wrong. A 200-line schema package does not need a `presentation/` layer. A runtime behavior -package cannot survive without one. This page defines six +package cannot survive without one. This page defines seven archetypes; every `packages/*` and `plugins/*` package picks the smallest archetype that fits, and the [folder structure doctrine](./05-folder-structure.md) governs how each archetype is @@ -229,6 +229,84 @@ Doctrine for this archetype: packages legitimately call into the CLI's flows programmatically. +## Archetype 7 — Deployment Target Adapter + +For the deployment feature: a **composite** archetype that ships one +uniform way to deploy a NetScript app to many *targets* (bare-metal +Windows/Linux, Docker/Compose, Deno Deploy, Aspire-driven cloud +runtimes). It is *not* a new package *shape* a single package picks +over its true archetype; it is a **named cross-package pattern** that +composes two existing archetypes and folds neither: + +- **Archetype 2 (Integration)** supplies the port/adapter core: a + package-owned `OsServicePort` (bare-metal — servy + systemd adapters) + plus cloud adapters (docker/compose/aca wrapping `aspire publish` / + `aspire deploy`; deno-deploy wrapping `deno deploy`). Each *target* + is one adapter behind the stable port — the target is the named + extension axis (A11), not a new abstraction layer. +- **Archetype 6 (CLI / Tooling)** supplies the presentation: `netscript + deploy ` parses input and routes to an adapter. The + command surface is a **thin router** — no target-specific business + logic lives in it. + +A9's "pick the larger, fold the smaller" applies: Archetype 7 is the +larger, named pattern that folds A2 and A6 for the deployment domain, +giving every adapter one conformance target. A deploy flow that is +*only* a CLI command with no port and a single target stays Archetype +6; Archetype 7 applies once the port/adapter seam *and* multi-target +routing exist. + +Minimum shape (a package-agnostic seam, not a fixed folder tree — the +core is Archetype 2, the router is Archetype 6): + +``` +/ ← Archetype 2 core + ports/ + os-service-port.ts ← OsServicePort (bare-metal seam) + adapters/ ← one file per target + servy-os-service.ts ← bare-metal (Windows) + systemd-os-service.ts ← bare-metal (Linux) + aspire-.ts ← wraps aspire publish/deploy + deno-deploy.ts ← wraps deno deploy + application/ + deploy-target-registry.ts ← target → adapter, closed-on-key + +/…/features/deploy/ ← Archetype 6 thin router + deploy-group.ts ← routes ; no target logic +``` + +Doctrine for this archetype: + +- **Uniform adapter contract.** Every target adapter implements the same + op set — `plan`/`emit`, `up`, `down`, `status`, `logs`, `rollback`, + `secrets`. A target implements the subset it supports; Aspire-driven + adapters delegate `up`/`plan` to the Aspire CLI rather than + reimplementing it (A7 — wrap upstream, do not reinvent). +- **Target config extends the shared base.** Each target's config member + spreads `DeployTargetBaseSchema` (the `@netscript/config` deployment + base contract). A target adds only its own fields. No per-target + config base-class hierarchy (A5 — composition over inheritance). +- **Thin router, core-centralized conventions.** The command surface + only parses and routes. Convention-bearing primitives — health + gating, OTEL wiring, secrets handling, rollback — live in the **core**, + shared across targets, never re-implemented per target (plugin-thinness + / core-centralization law). +- **Crash boundaries are explicit (A13).** Bare-metal activation is + health-gated and paired with `rollback`; cloud `rollback` maps to the + platform-native mechanism — it is not silently a no-op. +- **The port is justified, not premature (A11).** A second adapter is + foreseeable by construction (servy + systemd + cloud), so the + `OsServicePort` seam is warranted; do not add a target-specific base + class where an adapter behind the port suffices. + +> **#305 cross-reference.** This entry is durable archetype prose so the +> doctrine revamp (#305) can absorb it verbatim into the revamped +> archetype chapter and lift its `F-DEPLOY-*` gates into the fitness +> registry. It names the LAW (the seam + the op contract), not a concrete +> `deploy-core` package — deploy today lives inside `packages/cli` +> (Archetype 6) and the core is extracted in a later wave (deployment +> epic #327, slices #339–#343). + ## How to choose Decision order: @@ -240,6 +318,9 @@ Decision order: 4. Is the package's *primary product* a fluent DSL? → Archetype 4. 5. Is the package a *first-party plugin*? → Archetype 5. 6. Does the package ship a *binary* the user runs? → Archetype 6. +7. Does it deploy an app to *multiple targets* behind a port/adapter + seam with a thin CLI router? → Archetype 7 (composite; a single-target + CLI deploy flow with no port stays Archetype 6). If two archetypes apply (e.g. a runtime package that also publishes a DSL), pick the *larger* archetype. Layers from the smaller one @@ -256,6 +337,7 @@ archetypes. | `sagas` | 3 — Runtime/Behavior with state-machine specialization | | `fresh`, `fresh-ui`, `sdk`, `service`, `contracts`, `plugin` | 4 — DSL/Builder | | `cli` | 6 — CLI/Tooling | +| _future_ `deploy-core` (not yet extracted; deploy today folded in `cli` / A6) | 7 — Deployment Target Adapter (composite) | | `shared` | Special — see below. | | `plugins/*` | 5 — Plugin Package | @@ -281,3 +363,9 @@ identifiers (`CorrelationId`, `RunId`, `EventId`). `state/` in a Small Contract package). - [ ] If two archetypes seemed to apply, the package picked the larger one and folded the smaller in. +- [ ] A deployment package that composes A2 + A6 is declared + Archetype 7, and every target is an adapter behind the shared + port (not a target base-class hierarchy). +- [ ] The deploy command surface is a thin router — no + target-specific business logic; health, OTEL, secrets, and + rollback live in the core. From dc592e545dbbb8287ca3833f25c5d7d1b2bcf63b Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Fri, 3 Jul 2026 09:20:28 +0200 Subject: [PATCH 4/9] =?UTF-8?q?docs(harness):=20add=20Archetype=207=20surf?= =?UTF-8?q?aces=20=E2=80=94=20archetype=20file,=20decision=20row,=20gate?= =?UTF-8?q?=20matrix?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add the harness surfaces for Archetype 7 (Deployment Target Adapter) in lockstep with the doctrine entry: a new ARCHETYPE-7-deploy-target-adapter.md (composition, uniform 7-op contract, R-DEPLOY rules, F-DEPLOY gates), a decision-order row in archetypes/README.md, and an Arch 7 column in BOTH archetype-gate-matrix.md tables (Fitness Gates and Other Gate Families) per F3. F-DEPLOY-1/2 are seeded `reviewed` (not `gated`) since the deployment packages (#339–#343) are unbuilt. Refs #338 #327 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_012wKHquACkXnWPDgJYhhFjN --- .../ARCHETYPE-7-deploy-target-adapter.md | 123 ++++++++++++++++++ .llm/harness/archetypes/README.md | 21 +-- .llm/harness/gates/archetype-gate-matrix.md | 66 ++++++---- 3 files changed, 174 insertions(+), 36 deletions(-) create mode 100644 .llm/harness/archetypes/ARCHETYPE-7-deploy-target-adapter.md diff --git a/.llm/harness/archetypes/ARCHETYPE-7-deploy-target-adapter.md b/.llm/harness/archetypes/ARCHETYPE-7-deploy-target-adapter.md new file mode 100644 index 000000000..9ee2314c7 --- /dev/null +++ b/.llm/harness/archetypes/ARCHETYPE-7-deploy-target-adapter.md @@ -0,0 +1,123 @@ +# Archetype 7 — Deployment Target Adapter + +> A **composite** archetype for the deployment feature. It is not a package shape a single package +> picks over its true archetype; it is a named cross-package pattern that **composes** Archetype 2 +> (Integration — port/adapter core) and Archetype 6 (CLI / Tooling — thin router), folding neither. +> Doctrine source: +> `docs/architecture/doctrine/06-archetypes.md#archetype-7--deployment-target-adapter`. + +## Status + +Future-wave. The deployment core and its adapters are not built yet — deploy today lives inside +`packages/cli` (Archetype 6). This archetype exists so the four adapter slices of deployment epic +#327 (#339 systemd, #340 deno-deploy, #342 docker/compose, #343 aca) have a single named conformance +target. Its archetype-specific gates `F-DEPLOY-*` are seeded **`reviewed`** (see the gate matrix), +not `gated`, until the packages exist. + +## Doctrine Reference + +- Axioms: A2, A5, A7, A9, A11, A13. +- Primary sections: + - `docs/architecture/doctrine/06-archetypes.md#archetype-7--deployment-target-adapter` + - `docs/architecture/doctrine/06-archetypes.md#archetype-2--integration` (the port/adapter core) + - `docs/architecture/doctrine/06-archetypes.md#archetype-6--cli--tooling-package` (the thin + router) + - `docs/architecture/doctrine/09-anti-patterns-and-fitness-functions.md` +- Composed archetypes: `ARCHETYPE-2-integration.md`, `ARCHETYPE-6-cli-tooling.md`. +- Config contract: `@netscript/config` `DeployTargetBaseSchema` (landed by #337). + +## When This Archetype Applies + +Select Archetype 7 when a deployment feature deploys an app to **multiple targets** behind a +**port/adapter seam** with a **thin CLI router**. A deploy flow that is only a CLI command with no +port and a single target stays Archetype 6. The trigger is: the `OsServicePort`/cloud-adapter seam +**and** multi-target routing both exist. + +## Composition + +- **Core = Archetype 2.** A package-owned `OsServicePort` (bare-metal — servy + systemd adapters) + plus cloud adapters (docker/compose/aca wrapping `aspire publish`/`aspire deploy`; deno-deploy + wrapping `deno deploy`). Each target is one adapter behind the stable port; the **target** is the + named extension axis (A11), resolved through a closed-on-key `deploy-target-registry`. +- **Router = Archetype 6.** `netscript deploy ` parses input and routes to an + adapter. The command surface is a thin router — no target-specific business logic (Archetype 6 v2 + rules R-A6-N5/N7 and its F-CLI gates still bind the router package). + +Because Archetype 7 folds A2 and A6, a package or feature that conforms must satisfy the composed +archetype's own gates: the core satisfies the Archetype 2 universal gates; the router satisfies the +Archetype 6 universal + F-CLI gates. The `F-DEPLOY-*` gates below are additive. + +## Uniform Adapter Contract + +Every target adapter implements the same op set; a target implements the subset it supports: + +| Op | Meaning | +| ------------- | ---------------------------------------------------------------------------- | +| `plan`/`emit` | Compute/emit the deployment artifact/plan without mutating the target. | +| `up` | Create or update the deployment. Aspire-driven adapters delegate to Aspire. | +| `down` | Tear the deployment down. | +| `status` | Report current deployment state. | +| `logs` | Stream/fetch runtime logs. | +| `rollback` | Revert to the previous good state (bare-metal: health-gated; cloud: native). | +| `secrets` | Manage target secret material through the core, not per-target ad-hoc code. | + +## Rules (R-DEPLOY-N*) + +| Rule | Statement | Gate | +| ---------- | ------------------------------------------------------------------------------------------------------------------- | ---------- | +| R-DEPLOY-1 | Every target adapter implements the uniform 7-op contract (subset allowed; Aspire adapters delegate `up`/`plan`). | F-DEPLOY-1 | +| R-DEPLOY-2 | No target-specific business logic in the command surface; the deploy router only parses and routes. | F-DEPLOY-2 | +| R-DEPLOY-3 | Convention-bearing primitives (health gating, OTEL, secrets, rollback) live in the core, shared across all targets. | F-DEPLOY-2 | +| R-DEPLOY-4 | Each target config member spreads `DeployTargetBaseSchema`; no per-target config base-class hierarchy (A5). | F-DEPLOY-1 | +| R-DEPLOY-5 | The `OsServicePort`/cloud-adapter seam is justified by ≥ 2 foreseeable adapters (A11); no premature port. | F-DEPLOY-1 | + +## Fitness Gates + +Archetype-specific gates, seeded **`reviewed`** until the deployment packages (#339–#343) exist, +then promoted to `gated`: + +| Gate | Asserts | Detection | +| ---------- | ------------------------------------------------------------------------------------------------------- | ------------------- | +| F-DEPLOY-1 | Each registered target adapter implements the uniform 7-op contract (or an explicitly-declared subset). | AST + registry scan | +| F-DEPLOY-2 | The deploy command surface contains no target-specific business logic; conventions live in the core. | import graph + AST | + +These extend (do not replace) the universal F-* family and the composed archetypes' gates (Archetype +2 universal gates on the core; Archetype 6 universal + F-CLI gates on the router). + +## Skills to Activate + +- `netscript-doctrine` +- `netscript-harness` (when the run is harnessed) +- `aspire` for Aspire-driven cloud adapters +- `jsr-audit` for any slice touching a package `mod.ts`, `deno.json` exports, or JSDoc + +## Read First + +1. `docs/architecture/doctrine/06-archetypes.md#archetype-7--deployment-target-adapter`. +2. `ARCHETYPE-2-integration.md` (the port/adapter core) and `ARCHETYPE-6-cli-tooling.md` (the + router). +3. `@netscript/config` `deploy-schema.ts` — `DeployTargetBaseSchema` (the config-extension base). +4. The deployment epic #327 spec and the target adapter slice under implementation (#339–#343). +5. Relevant debt entries (the `deployment — Archetype-7 core-centralization + F-DEPLOY seed` entry + and the existing `packages/cli — AP-1` command-registry/deploy-target-seams entry). + +## Anti-Patterns to Watch For + +- **AP-11** — a target-specific base class where an adapter behind the port suffices; premature port + before a second adapter is foreseeable (here it always is: servy + systemd + cloud). +- **Thin-router violation** — target business logic leaking into the command surface (R-DEPLOY-2). +- **Convention duplication** — health/OTEL/secrets/rollback re-implemented per target instead of + centralized in the core (R-DEPLOY-3). +- **Config base-class hierarchy** — inheriting target config instead of spreading + `DeployTargetBaseSchema` (R-DEPLOY-4). + +## Concept of Done + +- The core exposes `OsServicePort` (+ cloud adapters) and a closed-on-key target registry; +- every target adapter implements the uniform 7-op contract (or a declared subset); +- the deploy command surface is a thin router with no target-specific business logic; +- health, OTEL, secrets, and rollback are centralized in the core; +- every target config member spreads `DeployTargetBaseSchema`; +- the composed Archetype 2 and Archetype 6 gates pass on the core and router respectively; +- `F-DEPLOY-1`/`F-DEPLOY-2` pass (or are `reviewed` with manual evidence while packages are + unbuilt). diff --git a/.llm/harness/archetypes/README.md b/.llm/harness/archetypes/README.md index a0128cd92..539a84cca 100644 --- a/.llm/harness/archetypes/README.md +++ b/.llm/harness/archetypes/README.md @@ -10,17 +10,20 @@ Doctrine source: `docs/architecture/doctrine/06-archetypes.md`. Pick the smallest archetype that fits: -| Question | Archetype | -| ------------------------------------------------------------------------------- | --------------------------------- | -| Does it only publish types, schemas, and small invariants? | `ARCHETYPE-1-small-contract.md` | -| Does it wrap an external system behind package-owned ports/adapters? | `ARCHETYPE-2-integration.md` | -| Does it own long-running stateful behavior, lifecycle, or supervised execution? | `ARCHETYPE-3-runtime-behavior.md` | -| Is the primary product a fluent DSL or builder API? | `ARCHETYPE-4-dsl-builder.md` | -| Is it a first-party package under `plugins/*`? | `ARCHETYPE-5-plugin.md` | -| Does it ship a binary or command-line flow? | `ARCHETYPE-6-cli-tooling.md` | +| Question | Archetype | +| --------------------------------------------------------------------------------------- | -------------------------------------- | +| Does it only publish types, schemas, and small invariants? | `ARCHETYPE-1-small-contract.md` | +| Does it wrap an external system behind package-owned ports/adapters? | `ARCHETYPE-2-integration.md` | +| Does it own long-running stateful behavior, lifecycle, or supervised execution? | `ARCHETYPE-3-runtime-behavior.md` | +| Is the primary product a fluent DSL or builder API? | `ARCHETYPE-4-dsl-builder.md` | +| Is it a first-party package under `plugins/*`? | `ARCHETYPE-5-plugin.md` | +| Does it ship a binary or command-line flow? | `ARCHETYPE-6-cli-tooling.md` | +| Does it deploy an app to multiple targets behind a port/adapter seam + thin CLI router? | `ARCHETYPE-7-deploy-target-adapter.md` | If two archetypes apply, choose the larger one and fold the smaller concerns inside it. Do not split -one package across two archetypes. +one package across two archetypes. Archetype 7 is a **composite** that folds Archetype 2 and +Archetype 6 for the deployment feature; a single-target CLI deploy flow with no port stays Archetype +6. ## Scope Overlays diff --git a/.llm/harness/gates/archetype-gate-matrix.md b/.llm/harness/gates/archetype-gate-matrix.md index 8c206f98b..52eec5ce3 100644 --- a/.llm/harness/gates/archetype-gate-matrix.md +++ b/.llm/harness/gates/archetype-gate-matrix.md @@ -10,29 +10,34 @@ Legend: - `subtype`: required for archetype subtypes that own the relevant behavior. - `n/a`: not normally applicable. +Archetype 7 (Deployment Target Adapter) is a **composite**: it folds Archetype 2 (the port/adapter +core) and Archetype 6 (the thin CLI router). Its Arch 7 column is therefore the **union** of the A2 +and A6 columns — the core satisfies the Archetype 2 gates, the router satisfies the Archetype 6 +gates. Its own archetype-specific gates are `F-DEPLOY-*` (see below). + ## Fitness Gates -| Gate | Arch 1 | Arch 2 | Arch 3 | Arch 4 | Arch 5 | Arch 6 | -| --------------------------------- | -------- | -------- | -------- | -------- | -------- | -------- | -| F-1 File-size lint | required | required | required | required | required | required | -| F-2 Helper-reinvention scan | n/a | required | required | required | n/a | required | -| F-3 Layering check | n/a | required | required | required | required | required | -| F-4 Inheritance audit | n/a | required | required | required | n/a | required | -| F-5 Public surface audit | required | required | required | required | required | required | -| F-6 JSR publishability | required | required | required | required | required | required | -| F-7 Doc-score gate | required | required | required | required | required | required | -| F-8 Workspace lib check | required | required | required | required | required | required | -| F-9 Permission decl check | n/a | required | required | required | required | required | -| F-10 Test-shape audit | required | required | required | required | required | required | -| F-11 Forbidden-folder lint | required | required | required | required | required | required | -| F-12 Naming-convention lint | required | required | required | required | required | required | -| F-13 Saga/runtime invariants | n/a | n/a | required | n/a | subtype | n/a | -| F-14 Console-log lint | required | required | required | required | required | n/a | -| F-15 Re-export-upstream lint | required | required | required | required | required | required | -| F-16 Folder-cardinality lint | required | required | required | required | required | required | -| F-17 Abstract-derived co-location | required | required | required | required | required | required | -| F-18 Sub-barrel lint | required | required | required | required | required | required | -| F-19 Scoped source gate runners | required | required | required | required | required | required | +| Gate | Arch 1 | Arch 2 | Arch 3 | Arch 4 | Arch 5 | Arch 6 | Arch 7 | +| --------------------------------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | +| F-1 File-size lint | required | required | required | required | required | required | required | +| F-2 Helper-reinvention scan | n/a | required | required | required | n/a | required | required | +| F-3 Layering check | n/a | required | required | required | required | required | required | +| F-4 Inheritance audit | n/a | required | required | required | n/a | required | required | +| F-5 Public surface audit | required | required | required | required | required | required | required | +| F-6 JSR publishability | required | required | required | required | required | required | required | +| F-7 Doc-score gate | required | required | required | required | required | required | required | +| F-8 Workspace lib check | required | required | required | required | required | required | required | +| F-9 Permission decl check | n/a | required | required | required | required | required | required | +| F-10 Test-shape audit | required | required | required | required | required | required | required | +| F-11 Forbidden-folder lint | required | required | required | required | required | required | required | +| F-12 Naming-convention lint | required | required | required | required | required | required | required | +| F-13 Saga/runtime invariants | n/a | n/a | required | n/a | subtype | n/a | n/a | +| F-14 Console-log lint | required | required | required | required | required | n/a | required | +| F-15 Re-export-upstream lint | required | required | required | required | required | required | required | +| F-16 Folder-cardinality lint | required | required | required | required | required | required | required | +| F-17 Abstract-derived co-location | required | required | required | required | required | required | required | +| F-18 Sub-barrel lint | required | required | required | required | required | required | required | +| F-19 Scoped source gate runners | required | required | required | required | required | required | required | ## Archetype-specific Gates @@ -43,14 +48,21 @@ universal F-* family above. Future archetypes may publish their own gate IDs in the same namespace pattern (e.g. `F-SVC-*`, `F-PLG-*`). +Archetype 7 (Deployment Target Adapter) introduces archetype-specific gates **F-DEPLOY-1** (each +target adapter implements the uniform 7-op contract) and **F-DEPLOY-2** (no target-specific business +logic in the command surface; conventions live in the core), documented in +`archetypes/ARCHETYPE-7-deploy-target-adapter.md` §"Fitness Gates". They are seeded **`reviewed`** +(not `gated`) until the deployment packages (#339–#343) exist, then promoted to `gated`. They extend +(do not replace) the universal F-* family and the composed A2/A6 gates. + ## Other Gate Families -| Gate family | Arch 1 | Arch 2 | Arch 3 | Arch 4 | Arch 5 | Arch 6 | -| -------------------------- | -------- | -------- | -------- | -------- | -------- | -------- | -| Static gates | required | required | required | required | required | required | -| Runtime/Aspire validation | n/a | optional | required | optional | required | optional | -| Browser validation | n/a | n/a | n/a | subtype | n/a | n/a | -| Consumer import validation | optional | required | required | required | required | required | +| Gate family | Arch 1 | Arch 2 | Arch 3 | Arch 4 | Arch 5 | Arch 6 | Arch 7 | +| -------------------------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | +| Static gates | required | required | required | required | required | required | required | +| Runtime/Aspire validation | n/a | optional | required | optional | required | optional | required | +| Browser validation | n/a | n/a | n/a | subtype | n/a | n/a | n/a | +| Consumer import validation | optional | required | required | required | required | required | required | ## Phase A Reporting From d644ebf45f953718e1933294bb205b23bf9434b2 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Fri, 3 Jul 2026 09:28:20 +0200 Subject: [PATCH 5/9] docs(debt): record Archetype-7 core-centralization + F-DEPLOY seed debt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Append `deployment — Archetype-7 core-centralization + F-DEPLOY seed` (DEPLOY-ARCHETYPE-7-CORE-SEED) to arch-debt.md: tracks the future deploy-core extraction that will own the centralized health/OTEL/secrets/rollback primitives and the target registry, plus the F-DEPLOY-1/2 reviewed->gated promotion once deployment packages (#339-#343) land. Cross-links (does not duplicate) the existing packages/cli - AP-1 "command registry/deploy target seams" restructure entry. Owner: deployment epic #327; closing gate: F-DEPLOY-1/2 promoted gated in all three surfaces. Refs #338 #327 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_012wKHquACkXnWPDgJYhhFjN --- .llm/harness/debt/arch-debt.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/.llm/harness/debt/arch-debt.md b/.llm/harness/debt/arch-debt.md index 0e8c4aaa1..1332f8140 100644 --- a/.llm/harness/debt/arch-debt.md +++ b/.llm/harness/debt/arch-debt.md @@ -1833,3 +1833,35 @@ match the merged exemplars). IMPL-EVAL must not FAIL a slice for retaining eithe - **Gate:** Close when `netscript db generate` completes DB-less codegen in a deno-only environment (no aspire CLI / .NET / docker) and the static suites can invoke the CLI command directly instead of the standalone `deno task db:generate` workaround. + +## deployment — Archetype-7 core-centralization + F-DEPLOY seed (`deploy-archetype-7-core-seed`) + +- **ID:** `DEPLOY-ARCHETYPE-7-CORE-SEED` +- **Reason:** Doctrine Archetype 7 (Deployment Target Adapter) names a package-agnostic LAW — the + `OsServicePort`/cloud-adapter seam, the uniform 7-op adapter contract, and the thin-router / + core-centralization rule — but the deployment **core** that would own the convention-bearing + primitives (health gating, OTEL, secrets, rollback) and the target registry does **not exist + yet**. Deploy today lives inside `packages/cli` (Archetype 6, `src/public/features/deploy/`). The + archetype's archetype-specific gates `F-DEPLOY-1` (uniform 7-op contract) and `F-DEPLOY-2` (no + target business logic in the command surface) are therefore seeded **`reviewed`**, not `gated`, + across the doctrine (`06-archetypes.md`), the harness archetype file + (`ARCHETYPE-7-deploy-target-adapter.md`), and the gate matrix. +- **Why deferred:** Extracting a deployment core and its adapters is the work of deployment epic + #327 slices #339 (systemd) / #340 (deno-deploy) / #342 (docker/compose) / #343 (aca). Promoting + the gates to `gated` before those packages exist would red CI against unbuilt code. This entry + tracks both the future core-centralization obligation and the `reviewed → gated` promotion. +- **Cross-link:** The eventual `OsServicePort` extraction out of the CLI deploy feature ties into + the existing `packages/cli — AP-1 / doctrine verdict Restructure` entry (Wave 6 "command + registry/deploy target seams"); do not duplicate that restructure debt — the deployment core + extraction is its downstream continuation. +- **Owner:** Deployment epic #327. +- **Target:** Phase 1 of #327 (first landed target adapter, #339+). +- **Linked plan:** `.llm/tmp/run/deploy-s2-doctrine/plan.md` (Slice 3); + `docs/architecture/doctrine/06-archetypes.md#archetype-7--deployment-target-adapter`. +- **Created:** 2026-07-03 +- **Status:** open, DEBT_ACCEPTED — `F-DEPLOY-1/2` seeded `reviewed` while the deployment packages + are unbuilt. +- **Gate:** Close when the deployment core owns the centralized health/OTEL/secrets/rollback + primitives and the target registry, every landed target adapter satisfies the uniform 7-op + contract, and `F-DEPLOY-1`/`F-DEPLOY-2` are promoted from `reviewed` to `gated` in all three + surfaces (doctrine, harness archetype file, gate matrix). From f3c050b57bc96561b218ce215453e372dad81cf2 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Fri, 3 Jul 2026 09:28:56 +0200 Subject: [PATCH 6/9] chore(harness): record deploy-s2 worklog + commit shas (run artifacts) Refs #338 #327 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_012wKHquACkXnWPDgJYhhFjN --- .llm/tmp/run/deploy-s2-doctrine/commits.md | 6 ++ .llm/tmp/run/deploy-s2-doctrine/worklog.md | 78 ++++++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 .llm/tmp/run/deploy-s2-doctrine/commits.md create mode 100644 .llm/tmp/run/deploy-s2-doctrine/worklog.md diff --git a/.llm/tmp/run/deploy-s2-doctrine/commits.md b/.llm/tmp/run/deploy-s2-doctrine/commits.md new file mode 100644 index 000000000..bca4a01a0 --- /dev/null +++ b/.llm/tmp/run/deploy-s2-doctrine/commits.md @@ -0,0 +1,6 @@ +# Commits — deploy-s2-doctrine (#338) + +- d2b8ae12: docs(deploy): [Deploy-S2] research + plan for target-adapter archetype doctrine entry (run docs; planning-only) +- 287f3544: docs(doctrine): add Archetype 7 — Deployment Target Adapter (composes A2+A6) [Slice 1] +- 72d055cf: docs(harness): add Archetype 7 surfaces — archetype file, decision row, gate matrix [Slice 2] +- c9845951: docs(debt): record Archetype-7 core-centralization + F-DEPLOY seed debt [Slice 3] diff --git a/.llm/tmp/run/deploy-s2-doctrine/worklog.md b/.llm/tmp/run/deploy-s2-doctrine/worklog.md new file mode 100644 index 000000000..2fa6b0714 --- /dev/null +++ b/.llm/tmp/run/deploy-s2-doctrine/worklog.md @@ -0,0 +1,78 @@ +# Worklog — deploy-s2-doctrine (#338 [Deploy-S2]) + +Implementer: Claude Opus 4.8 (HIGH). Executing the PASS_PLAN plan + F1–F4 corrections. +Branch `feat/deploy-s2-doctrine` in worktree `.claude/worktrees/deploy-s2`. + +## PLAN-EVAL corrections applied + +- **F1** — updated the intro count sentence in `06-archetypes.md` from "six" to "seven" archetypes + (`check-doctrine.ts` does not parse this markdown; hand-applied). +- **F2** — did NOT add a `deploy-core` row to the "current packages" assignments table as a present + package. Added a clearly-marked `_future_ deploy-core (not yet extracted; deploy today folded in + cli / A6)` row instead; `cli` remains Archetype 6 (not relabelled). D7 package-agnostic stance + preserved. +- **F3** — added an **Arch 7** column to BOTH `archetype-gate-matrix.md` tables (`## Fitness Gates` + and `## Other Gate Families`), not only the first. +- **F4** — did NOT rely on `arch:check` to prove doctrine markdown link/ref integrity (it only walks + package TS source). Real proof recorded below is `arch:check` regression-clean + a manual + three-surface consistency read. The scoped docs `fmt:check` is a pre-existing baseline caveat (see + Gate results). + +## Gate results + +### Slice 1 — Doctrine: Archetype 7 entry (`06-archetypes.md`) + +- `deno task arch:check` → **exit 0**, FAIL=0 across all evaluated package roots (only pre-existing + WARN/INFO on package TS source, none introduced by this markdown edit). Confirms no doctrine-lint + regression. Per F4, arch:check does NOT parse `06-archetypes.md`, so this is a "did-not-regress the + evaluated packages" signal, not a link-integrity proof for the markdown. +- Scoped docs fmt: `run-deno-fmt.ts --root docs/architecture/doctrine --ext md` → reports reflow + findings on 4 files, **including three I never touched** (`02-public-surface.md`, + `08-runtime-state-failure.md`, `10-codebase-verdict-and-handoff.md`). Verified via `git stash` that + the untouched baseline `06-archetypes.md` (still reading "six") already fails `deno fmt --check`: + the doctrine corpus is intentionally hand-wrapped narrow (~55–62 cols) and `deno fmt` wants to + reflow it to 80 cols. This is pre-existing directory-wide baseline drift, NOT introduced by this + slice. Per AGENTS/F4 (raw Markdown reflow is not a package-quality verdict) and the explicit + instruction not to run the mutating repo-wide `deno task fmt`, the inserted prose was hand-wrapped + to match the file's existing narrow style so it adds no new drift class. **Not a red on this + slice.** +- Manual doctrine read: Archetype 7 section present after Archetype 6; intro count "seven"; decision + step 7 added; future `deploy-core` assignments row added (cli unchanged); two checklist rows added; + `#305` cross-reference note present. Consistent. + +### Slice 2 — Harness surfaces (archetype file + README + gate matrix) + +- New `.llm/harness/archetypes/ARCHETYPE-7-deploy-target-adapter.md`; decision-order row in + `archetypes/README.md`; Arch 7 column in **both** gate-matrix tables (Fitness Gates + Other Gate + Families) plus the F-DEPLOY prose (F3). +- `deno fmt --check` on the three edited harness files → after formatting, **exit 0** (clean). + Unlike the hand-wrapped doctrine dir, `.llm/harness/` markdown is `deno fmt`-conformant at + lineWidth 100, so the mutating `deno fmt` was run on exactly these three files (not repo-wide). +- Three-surface consistency read: doctrine `06-archetypes.md` (Archetype 7 section + decision step 7 + + assignments row), `archetypes/README.md` (decision row + composite note), and + `gate-matrix.md` (Arch 7 in both tables + F-DEPLOY-1/2 seeded `reviewed`) all name Archetype 7 and + `F-DEPLOY-*` consistently. **Consistent.** + +### Slice 3 — Arch-debt entry + +- Appended `## deployment — Archetype-7 core-centralization + F-DEPLOY seed` + (`DEPLOY-ARCHETYPE-7-CORE-SEED`) to `.llm/harness/debt/arch-debt.md`: records the future + `deploy-core` centralization obligation + the `F-DEPLOY-1/2` `reviewed → gated` promotion, owner + = deployment epic #327, target = Phase 1 (#339+), closing gate = gates promoted `gated` in all + three surfaces. Cross-links (does not duplicate) the existing `packages/cli — AP-1` "command + registry/deploy target seams" restructure entry. +- Debt-registry format: entry matches the `## — ` shape with + ID/Reason/Why-deferred/Cross-link/Owner/Target/Linked-plan/Created/Status/Gate fields, consistent + with sibling entries. Hand-wrapped to ≤100 cols matching sibling style. +- fmt caveat: `arch-debt.md` Markdown is NOT in the repo `deno.json` fmt `include` (only + `packages/**/*.ts,tsx`) and is pervasively baseline-dirty (reflow findings across L140–1790 from + prior contributors' entries). Running the mutating whole-file `deno fmt` would reflow hundreds of + unrelated lines, so it was NOT run; my entry is hand-wrapped clean instead. This markdown is not a + repo fmt gate. + +## Summary of PLAN-EVAL corrections + +All four applied: **F1** (six→seven), **F2** (future/pending assignments row, cli not relabelled), +**F3** (Arch 7 in both gate-matrix tables), **F4** (arch:check evidence reworded; real proof = +three-surface consistency read + scoped-file fmt on the fmt-governed harness files; doctrine + +arch-debt Markdown fmt drift is pre-existing baseline, not a slice regression). From d87dfbef52232e29689a76808c95bb9d7eddb6b4 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Fri, 3 Jul 2026 09:32:09 +0200 Subject: [PATCH 7/9] docs(doctrine): reconcile Archetype 7 with the shipped 3-op deploy seed The #342 PLAN-EVAL surfaced that main already ships a 3-op DeployTargetPort (build/install/uninstall) plus a WindowsServiceDeployTarget stub in packages/cli (commit 3137e455, an unrelated command-registry slice), which the Archetype 7 doctrine read as if no port existed. Per the epic #327 supervisor reconciliation (contract-reconciliation.md): the 7-op lifecycle stays canonical; the shipped port is the current placeholder seed. - 06-archetypes.md: add a "Shipped seed" note acknowledging the existing DeployTargetPort/WindowsServiceDeployTarget seed, its build->plan/emit, install->up, uninstall->down mapping, and that status/logs/rollback/secrets are net-new; verb-vocabulary lock deferred to the first real adapter (#339/#340). No contract change, no renumber. - arch-debt.md (DEPLOY-ARCHETYPE-7-CORE-SEED): fold in the 3-op -> 7-op expansion + windows-service stub migrate/retire obligation; closing gate = F-DEPLOY-1 promoted gated. Refs #338 #327 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_012wKHquACkXnWPDgJYhhFjN --- .llm/harness/debt/arch-debt.md | 12 ++++++++++++ docs/architecture/doctrine/06-archetypes.md | 13 +++++++++++++ 2 files changed, 25 insertions(+) diff --git a/.llm/harness/debt/arch-debt.md b/.llm/harness/debt/arch-debt.md index 1332f8140..6f60d6721 100644 --- a/.llm/harness/debt/arch-debt.md +++ b/.llm/harness/debt/arch-debt.md @@ -1854,6 +1854,18 @@ match the merged exemplars). IMPL-EVAL must not FAIL a slice for retaining eithe the existing `packages/cli — AP-1 / doctrine verdict Restructure` entry (Wave 6 "command registry/deploy target seams"); do not duplicate that restructure debt — the deployment core extraction is its downstream continuation. +- **Seed expansion (3-op → 7-op):** A placeholder port already ships on main — the 3-op + `DeployTargetPort` (`build`/`install`/`uninstall`, all optional) plus its stub adapter + `WindowsServiceDeployTarget` (key `windows-service`) in `packages/cli`, landed by commit + `3137e455` (an unrelated command-registry slice, not this epic). It maps to the canonical + lifecycle as `build → plan`/`emit`, `install → up`, `uninstall → down`, and lacks + `status`/`logs`/`rollback`/`secrets`. The epic must expand this seed to the full 7-op + `OsServicePort`/cloud-adapter contract across #339–#343 and migrate/retire the `windows-service` + stub — never entrench the 3-op surface. Verb-vocabulary lock (keep `build`/`install`/`uninstall`, + adopt `up`/`down`, or a hybrid) is deferred to the first real adapter (#339/#340); closing gate + for this obligation = `F-DEPLOY-1` promoted `gated`. Authoritative reconciliation: + `.llm/tmp/run/deploy-s2-doctrine/contract-reconciliation.md` (epic #327 supervisor decision, + surfaced by the #342 PLAN-EVAL). - **Owner:** Deployment epic #327. - **Target:** Phase 1 of #327 (first landed target adapter, #339+). - **Linked plan:** `.llm/tmp/run/deploy-s2-doctrine/plan.md` (Slice 3); diff --git a/docs/architecture/doctrine/06-archetypes.md b/docs/architecture/doctrine/06-archetypes.md index 66406e5eb..18f42cd0d 100644 --- a/docs/architecture/doctrine/06-archetypes.md +++ b/docs/architecture/doctrine/06-archetypes.md @@ -307,6 +307,19 @@ Doctrine for this archetype: > (Archetype 6) and the core is extracted in a later wave (deployment > epic #327, slices #339–#343). +> **Shipped seed.** A placeholder port already ships on main: the 3-op +> `DeployTargetPort` (`build` / `install` / `uninstall`, all optional) +> and its stub reference adapter `WindowsServiceDeployTarget` (key +> `windows-service`) under `packages/cli` (landed by commit `3137e455`, +> an unrelated command-registry slice — not this epic). It maps into the +> canonical lifecycle above as `build → plan`/`emit`, `install → up`, +> `uninstall → down`; `status`, `logs`, `rollback`, and `secrets` are +> net-new ops the seed does not yet have. The 7-op contract is canonical +> and the seed is a stub the epic expands to the full +> `OsServicePort`/cloud-adapter surface; the final verb vocabulary +> (keep `build`/`install`/`uninstall`, adopt `up`/`down`, or a hybrid) +> locks at the first real adapter (#339/#340). + ## How to choose Decision order: From 6565e91e73cbcbfcaf4ba114f339982b2f4ba904 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Fri, 3 Jul 2026 09:32:25 +0200 Subject: [PATCH 8/9] chore(harness): record Slice 5 sha in deploy-s2 commits log Refs #338 #327 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_012wKHquACkXnWPDgJYhhFjN --- .llm/tmp/run/deploy-s2-doctrine/commits.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.llm/tmp/run/deploy-s2-doctrine/commits.md b/.llm/tmp/run/deploy-s2-doctrine/commits.md index bca4a01a0..4a2e3833e 100644 --- a/.llm/tmp/run/deploy-s2-doctrine/commits.md +++ b/.llm/tmp/run/deploy-s2-doctrine/commits.md @@ -4,3 +4,4 @@ - 287f3544: docs(doctrine): add Archetype 7 — Deployment Target Adapter (composes A2+A6) [Slice 1] - 72d055cf: docs(harness): add Archetype 7 surfaces — archetype file, decision row, gate matrix [Slice 2] - c9845951: docs(debt): record Archetype-7 core-centralization + F-DEPLOY seed debt [Slice 3] +- 1d981a70: docs(doctrine): reconcile Archetype 7 with the shipped 3-op deploy seed [Slice 5] From e4ed72903b391e24cf1f2205ae58cf4f5fe94ed0 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Fri, 3 Jul 2026 09:43:21 +0200 Subject: [PATCH 9/9] docs(harness): record op-contract reconciliation + IMPL-EVAL PASS trail [Deploy-S2] Force-add the epic-supervisor op-contract reconciliation decision (7-op lifecycle stays canonical; shipped 3-op DeployTargetPort seed acknowledged), the IMPL-EVAL brief, and the separate-session PASS verdict, so the paths cited in the committed doctrine + arch-debt entry resolve. Refs #338 #327 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_012wKHquACkXnWPDgJYhhFjN --- .../contract-reconciliation.md | 61 ++++++++++ .llm/tmp/run/deploy-s2-doctrine/eval-brief.md | 61 ++++++++++ .../run/deploy-s2-doctrine/impl-eval-opus.md | 109 ++++++++++++++++++ 3 files changed, 231 insertions(+) create mode 100644 .llm/tmp/run/deploy-s2-doctrine/contract-reconciliation.md create mode 100644 .llm/tmp/run/deploy-s2-doctrine/eval-brief.md create mode 100644 .llm/tmp/run/deploy-s2-doctrine/impl-eval-opus.md diff --git a/.llm/tmp/run/deploy-s2-doctrine/contract-reconciliation.md b/.llm/tmp/run/deploy-s2-doctrine/contract-reconciliation.md new file mode 100644 index 000000000..806f9a7ec --- /dev/null +++ b/.llm/tmp/run/deploy-s2-doctrine/contract-reconciliation.md @@ -0,0 +1,61 @@ +# Deploy op-contract reconciliation (epic #327 supervisor decision) + +Surfaced by the **#342 PLAN-EVAL FAIL_PLAN** (finding B1): main ships a 3-op deploy +port while #338's ratified doctrine specifies a 7-op contract. This note is the +authoritative reconciliation. It is an **internal architecture decision** by the +epic #327 supervisor (the #338 owner) — not a user product decision. Both the #338 +doctrine finalization and the #342 replan consume this note. + +## Facts (verified firsthand against main / worktree source) + +- **Shipped seed (main):** `packages/cli/src/kernel/domain/deploy/deploy-target-port.ts` + defines `DeployTargetPort` with a **3-op** surface — `build | install | uninstall` + (all optional) — plus `DeployTargetRequest`/`DeployTargetResult`. The reference + adapter `windows-service-deploy-target.ts` (`WindowsServiceDeployTarget`, + key `windows-service`) is a **stub**: each op resolves a canned message and + delegates no real work. Landed by commit **`3137e455`** (2026-06-17), an unrelated + command-registry slice — **not** #338, and **not** part of the deployment epic design. +- **Ratified doctrine (#338):** Archetype 7 defines a **7-op** uniform contract — + `plan`/`emit` · `up` · `down` · `status` · `logs` · `rollback` · `secrets` — behind + an `OsServicePort` (bare-metal) + cloud-adapter seam, adapters implementing the subset + they support, gates seeded `reviewed`. +- **#342 error:** its research misattributed the shipped 3-op port to #338 and then + demoted the ratified 7-op doctrine to "stale corpus," conforming the flagship Deno + Deploy adapter to 3-op. That inverts the authority (code stub over designed doctrine) + and is not #342's call to make in a marquee slice. + +## Decision + +1. **The 7-op lifecycle is the canonical epic contract.** `plan`/`emit` · `up` · `down` + · `status` · `logs` · `rollback` · `secrets` stands as the designed north star. + Adapters implement the subset they support; `F-DEPLOY-*` stay seeded `reviewed`. + #342 does **not** get to demote it. +2. **The shipped 3-op `DeployTargetPort` is the current *seed* skeleton**, implementing + the `build/install/uninstall` ≈ `plan-emit / up / down` subset. It is real but a + placeholder (stub adapter, no behavior). Doctrine must **acknowledge it**, not pretend + no port exists and not call it stale. +3. **Verb-vocabulary lock is deferred to the first real adapter (#339/#340).** The epic + expands the seed `DeployTargetPort` → the full 7-op `OsServicePort`/cloud-adapter + contract; the final canonical verb names (keep `build/install/uninstall`, adopt + `up/down`, or a hybrid) lock at that impl. Until then doctrine records the mapping: + `build → plan/emit`, `install → up`, `uninstall → down`; `status`/`logs`/`rollback`/ + `secrets` are net-new lifecycle ops the seed does not yet have. +4. **Reconciliation is recorded as arch-debt** (the deployment core-centralization entry, + #338 Slice 3): "seed `DeployTargetPort` (3-op stub, `3137e455`) → expand to 7-op + `OsServicePort`/cloud-adapter contract across #339–#343; migrate/retire the + `windows-service` stub." Closing gate = `F-DEPLOY-1` promoted `gated`. + +## Actions + +- **#338 (in-flight impl, PR #357):** additive follow-up — (a) one prose line in + Archetype 7 acknowledging the existing shipped `DeployTargetPort`/`WindowsServiceDeployTarget` + seed + the verb map; (b) fold the 3-op→7-op expansion into the Slice 3 arch-debt entry. + No renumber, no contract change — the 7-op doctrine stays canonical. +- **#342 (replan):** correct the misattribution (port is main's `3137e455`, not #338's); + conform the Deno Deploy adapter to the **7-op** doctrine (implement its supported subset — + Deno Deploy has no `install/uninstall`-on-host; it maps `up`→`deno deploy`, `status`/`logs` + →platform API, `rollback`→platform mechanism); where it touches the registry, extend the + seed port toward the contract, never entrench 3-op. Apply S-1 (name/commit Archetype 7 once + #338 lands), S-2 (re-baseline S1 schema vs merged main), S-3 (drop the "#337 not merged" + premise — it is merged). The two NEEDS-USER items (CLI-push-vs-GitHub-push default; CI + non-interactive `deno deploy` auth) remain user-surfaced and non-blocking to design. diff --git a/.llm/tmp/run/deploy-s2-doctrine/eval-brief.md b/.llm/tmp/run/deploy-s2-doctrine/eval-brief.md new file mode 100644 index 000000000..9e6016de7 --- /dev/null +++ b/.llm/tmp/run/deploy-s2-doctrine/eval-brief.md @@ -0,0 +1,61 @@ +# IMPL-EVAL brief — #338 [Deploy-S2] Archetype 7 doctrine (separate session) + +You are the **separate-session evaluator** for a docs/doctrine harness slice. You did NOT +implement this; evaluate the BUILT artifact adversarially, then reproduce the applicable +quality gate. Write a verdict file and end with a single line `result: PASS_IMPL` or +`result: FAIL_IMPL` (+ blocking findings). + +## What was built + +Branch `feat/deploy-s2-doctrine` (PR #357, DRAFT), off `origin/main`. It authors a **new +Archetype 7 — Deployment Target Adapter** across the three harness archetype surfaces + a +debt entry, for the deployment epic #327. Commits: `287f3544` (doctrine), `72d055cf` +(harness surfaces), `c9845951` (debt), `1d981a70` (reconciliation follow-up). + +## Files to read (worktree: C:\Dev\repos\netscript-framework\.claude\worktrees\deploy-s2) + +- `docs/architecture/doctrine/06-archetypes.md` — the Archetype 7 section (~L232+), the + "seven archetypes" intro count, the `## How to choose` decision step 7, the + `## Archetype assignments for current packages` row (must be marked future/pending, NOT + a relabel of `cli`), and the checklist rows. +- `.llm/harness/archetypes/ARCHETYPE-7-deploy-target-adapter.md` +- `.llm/harness/archetypes/README.md` (decision-order row) +- `.llm/harness/gates/archetype-gate-matrix.md` (Arch 7 must be in BOTH tables + F-DEPLOY prose) +- `.llm/harness/debt/arch-debt.md` (`DEPLOY-ARCHETYPE-7-CORE-SEED` entry) +- `.llm/tmp/run/deploy-s2-doctrine/contract-reconciliation.md` — the supervisor's op-contract + reconciliation decision (authoritative). The doctrine MUST conform to it. +- Ground truth for the reconciliation: `packages/cli/src/kernel/domain/deploy/deploy-target-port.ts` + (shipped 3-op `DeployTargetPort`) and `windows-service-deploy-target.ts` (stub adapter). + +## Adversarial checks (the built artifact) + +1. **Reconciliation is correct and present.** Archetype 7 prose must acknowledge the shipped + 3-op `DeployTargetPort` + `WindowsServiceDeployTarget` seed (commit `3137e455`) with the verb + map `build→plan/emit · install→up · uninstall→down`, and state `status`/`logs`/`rollback`/ + `secrets` are net-new. The **7-op lifecycle must remain the canonical contract** — verify the + doctrine did NOT get demoted to 3-op. The arch-debt entry must carry the 3-op→7-op expansion + + stub-retire obligation with a closing gate (`F-DEPLOY-1` promoted `gated`). +2. **Three-surface consistency.** Archetype 7 is present and mutually coherent in + `06-archetypes.md`, the `ARCHETYPE-7-*.md` harness file, and `archetype-gate-matrix.md` + (both tables). Decision order + assignments updated. No dangling refs. +3. **PLAN-EVAL fixes F1–F4 held.** F1 intro says "seven". F2 assignments row is future/pending, + `cli` not relabelled. F3 Arch 7 in BOTH gate-matrix tables. F4 no reliance on `arch:check` for + markdown link integrity. +4. **Doctrine-shape sanity.** Archetype 7 is a genuine cross-package composite (A2 port/adapter + + A6 thin router), package-agnostic except the intentional seed reference; gates seeded `reviewed` + (correct for future-wave), not `gated`. +5. **No scope leak.** No product/adapter code, no `.claude/` config/skills/hooks, no `deploy-schema.ts` + edit, no doctrine renumber. `validate-claude-surface.ts` correctly N/A. + +## Quality gate to reproduce (docs slice — NO scaffold.runtime) + +- `deno task arch:check` → expect exit 0 (no regression; it does NOT parse doctrine markdown, so + it is a no-regression signal not a link proof). +- Scoped fmt on the fmt-governed harness files only: + `deno run --allow-read --allow-run .llm/tools/run-deno-fmt.ts --root .llm/harness --ext md` + → expect clean on the edited files. (The doctrine dir + arch-debt.md are baseline-dirty and NOT + in the repo fmt include; do NOT treat repo-wide `deno fmt --check` as this slice's verdict — see + the F4 caveat in the worklog.) +- Manual three-surface consistency read (the real proof). + +Do not mark PR #357 ready; return the verdict only. diff --git a/.llm/tmp/run/deploy-s2-doctrine/impl-eval-opus.md b/.llm/tmp/run/deploy-s2-doctrine/impl-eval-opus.md new file mode 100644 index 000000000..70a719367 --- /dev/null +++ b/.llm/tmp/run/deploy-s2-doctrine/impl-eval-opus.md @@ -0,0 +1,109 @@ +# IMPL-EVAL (Opus 4.8, separate session) — #338 [Deploy-S2] Archetype 7 doctrine + +**Verdict: PASS_IMPL** + +Branch `feat/deploy-s2-doctrine` (PR #357, DRAFT). Evaluated the built artifact adversarially +against the eval brief + authoritative `contract-reconciliation.md`, reproduced the docs-slice +quality gate, and performed a manual three-surface consistency read. Did not edit any +doctrine/harness file; did not mark the PR ready. + +## Reconciliation correctness (most-important check) — PASS + +- **7-op lifecycle remains CANONICAL** everywhere. `plan`/`emit` · `up` · `down` · `status` · + `logs` · `rollback` · `secrets` is the uniform contract in the doctrine op table + (`06-archetypes.md` L280–284), the harness archetype op table (`ARCHETYPE-7-*.md` L54–62), + R-DEPLOY-1 ("uniform 7-op contract"), and the debt entry ("uniform 7-op adapter contract"). + The doctrine was NOT demoted to 3-op. +- **Shipped 3-op seed acknowledged, framed as a stub to expand — not the contract.** Doctrine + L310–321 adds a "Shipped seed" block naming the 3-op `DeployTargetPort` + (`build`/`install`/`uninstall`, all optional) and stub `WindowsServiceDeployTarget` + (key `windows-service`), landed by `3137e455` (unrelated command-registry slice, not the epic), + with the verb map **`build → plan`/`emit`, `install → up`, `uninstall → down`** and + `status`/`logs`/`rollback`/`secrets` explicitly net-new. Verified firsthand against ground-truth + source on the branch: `packages/cli/src/kernel/domain/deploy/deploy-target-port.ts` (exactly the + 3-op `build|install|uninstall` surface) and `windows-service-deploy-target.ts` (canned-message + stub delegating no real work). The doctrine's description matches the code precisely. +- **Arch-debt carries the 3-op→7-op expansion + stub-retire obligation.** + `DEPLOY-ARCHETYPE-7-CORE-SEED` (arch-debt.md L1848–1859) records the seed, the same verb map, + the "expand to full 7-op `OsServicePort`/cloud-adapter contract across #339–#343 and + migrate/retire the `windows-service` stub — never entrench the 3-op surface" obligation, + deferred verb-vocabulary lock (#339/#340), and **closing gate = `F-DEPLOY-1` promoted `gated`**. + Cites the reconciliation note by path. Faithful to `contract-reconciliation.md` decisions 1–4. + +## Three-surface consistency — PASS + +Archetype 7 is present and mutually coherent across all three surfaces plus the decision-order +README: + +- `06-archetypes.md`: intro "seven archetypes" (L7); full Archetype 7 section (L232–321); + decision step 7 (L334–336); future/pending assignments row; checklist rows (L379–384). +- `ARCHETYPE-7-deploy-target-adapter.md`: future-wave status, composition (A2 core + A6 router), + 7-op contract table, R-DEPLOY-1..5, F-DEPLOY-1/2 seeded `reviewed`. (It does not restate the + 3-op seed line — acceptable: it is the conformance north-star; the seed acknowledgment correctly + lives in the doctrine prose + debt entry per the reconciliation action items.) +- `archetype-gate-matrix.md`: Arch 7 column in BOTH tables (Fitness Gates L20–39; Other Gate + Families L59–64); composite-union explanation; F-DEPLOY-1/2 prose seeded `reviewed` (L50–55). +- `archetypes/README.md`: decision-order row for Archetype 7 (L21) + composite note (L24–26). + +No dangling refs among the doctrine surfaces. + +## PLAN-EVAL F1–F4 held — PASS + +- **F1** — intro says "seven archetypes" (L7). Held. +- **F2** — assignments row is future/pending: `cli` → `6 — CLI/Tooling` (L352) is intact; + `_future_ deploy-core (not yet extracted; deploy today folded in cli / A6)` → Archetype 7 + (L353). `cli` was NOT relabelled. Held. +- **F3** — Arch 7 present in BOTH gate-matrix tables. Held. +- **F4** — no reliance on `arch:check` for markdown link integrity; worklog documents that + `arch:check` only walks package TS and the real proof is the manual three-surface read. Held. + +## Doctrine-shape sanity — PASS + +Archetype 7 is a genuine cross-package composite (A2 port/adapter core + A6 thin router, folding +neither), package-agnostic except the intentional seed reference, with gates seeded `reviewed` +(correct for future-wave), not `gated`. R-DEPLOY-1..5 and AP mappings are coherent. + +## No scope leak — PASS + +Changed files vs merge-base (`44d7945`): `ARCHETYPE-7-deploy-target-adapter.md` (A), +`archetypes/README.md` (M), `debt/arch-debt.md` (M), `gates/archetype-gate-matrix.md` (M), +`docs/architecture/doctrine/06-archetypes.md` (M), plus committed run artifacts. No product/adapter +code, no `.claude/` config/skills/hooks, no `deploy-schema.ts` edit, no doctrine renumber. +`validate-claude-surface.ts` correctly N/A (no Claude-surface change). + +## Quality gate reproduction (docs slice — no scaffold.runtime) + +- **`deno task arch:check` → exit 0.** FAIL=0 across all package roots; only pre-existing + WARN/INFO on package TS source (export-default AP-19, file-size A8/AP-9, A9/A12 INFO). No + regression introduced by this markdown slice. +- **Scoped fmt `run-deno-fmt.ts --root .llm/harness --ext md` → exit 1, 14 findings, but the + three fmt-governed files this slice authored/edited are CLEAN** (ARCHETYPE-7 file, archetypes + README, gate-matrix are all absent from the findings). The 14 findings are pre-existing baseline + drift (ARCHETYPE-1..6, lessons/*, profiles/*, templates/*, workflow/*). `arch-debt.md` appears, + but the brief pre-declares it baseline-dirty and out of the repo fmt include, and the specific + finding is on an unrelated pre-existing entry (the `_aspire-compat.mjs` reason line), not the + slice's inserted DEPLOY-ARCHETYPE-7 block. Per the F4 caveat, repo-wide/baseline-dirty fmt is not + this slice's verdict. Not a red on this slice. +- Manual three-surface consistency read: PASS (above). + +## Non-blocking finding (informational) + +- `.llm/tmp/run/deploy-s2-doctrine/contract-reconciliation.md` is **gitignored / not committed** + on the branch (confirmed via `git check-ignore` + `git ls-files`), whereas its sibling run + artifacts (`plan.md`, `worklog.md`, `research.md`, etc.) were force-committed. The debt entry and + doctrine both cite this path as the "authoritative reconciliation," so once merged the citation + points at a repo-absent file. This is a traceability nit only — the reconciliation's *content* is + fully and faithfully absorbed into the committed doctrine prose + debt entry, so no + doctrine-correctness or reconciliation-fidelity failure. Recommend (optional) force-adding the + note for parity with the other committed run artifacts, or leaving it as an internal supervisor + note. Does not block. + +## Conclusion + +The 7-op lifecycle stands as the canonical contract; the shipped 3-op seed is correctly +acknowledged and framed as a stub to expand; the arch-debt entry carries the full 3-op→7-op +expansion + stub-retire obligation with the `F-DEPLOY-1 gated` closing gate; PLAN-EVAL F1–F4 all +held; three-surface consistency is intact; scope is clean; the applicable quality gates reproduce +green for this slice. Do not mark PR #357 ready (evaluator does not promote). + +result: PASS_IMPL