From 79012c4fda9c6887e3debc6155f45948c5badf9f Mon Sep 17 00:00:00 2001
From: jared <jared@swansoncloud.com>
Date: Thu, 16 Jul 2026 15:39:35 -0400
Subject: [PATCH 1/4] os-sdlc: design mapped into concept-node reference docs +
 OVERVIEW v0.2

Decompose the 2026-07-16 design session into nine independent-context
nodes under plugins/os-sdlc/reference/, with OVERVIEW.md rewritten as
the central concept map + index. Also fixes the dangling
matt-pocock-skills-v1.1-notes.md reference (notes live in the vault as
matt-pocock-skills-v1-1-changes.md; ADR-0037 affected-paths cleaned).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VgG2g9ooqbnBiZYGAonGYG
---
 ...ugin-not-a-separate-cc-sdlc-marketplace.md |   2 +-
 plugins/os-sdlc/OVERVIEW.md                   | 180 +++++++-----------
 .../reference/agent-design-principles.md      |  52 +++++
 .../os-sdlc/reference/deterministic-gates.md  |  53 ++++++
 plugins/os-sdlc/reference/horizon.md          |  65 +++++++
 plugins/os-sdlc/reference/never-ask-twice.md  |  76 ++++++++
 plugins/os-sdlc/reference/pipeline-stages.md  |  68 +++++++
 plugins/os-sdlc/reference/plugin-factory.md   |  53 ++++++
 .../reference/self-improvement-loops.md       |  66 +++++++
 .../reference/spec-and-ticket-layer.md        |  59 ++++++
 .../os-sdlc/reference/worktree-parallelism.md |  49 +++++
 11 files changed, 612 insertions(+), 111 deletions(-)
 create mode 100644 plugins/os-sdlc/reference/agent-design-principles.md
 create mode 100644 plugins/os-sdlc/reference/deterministic-gates.md
 create mode 100644 plugins/os-sdlc/reference/horizon.md
 create mode 100644 plugins/os-sdlc/reference/never-ask-twice.md
 create mode 100644 plugins/os-sdlc/reference/pipeline-stages.md
 create mode 100644 plugins/os-sdlc/reference/plugin-factory.md
 create mode 100644 plugins/os-sdlc/reference/self-improvement-loops.md
 create mode 100644 plugins/os-sdlc/reference/spec-and-ticket-layer.md
 create mode 100644 plugins/os-sdlc/reference/worktree-parallelism.md

diff --git a/docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md b/docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md
index 2c6e681..281743f 100644
--- a/docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md
+++ b/docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md
@@ -4,7 +4,7 @@ date: 2026-07-14
 status: Accepted
 supersedes:
 superseded-by:
-affected-paths: [plugins/os-sdlc/, docs/matt-pocock-skills-v1.1-notes.md]
+affected-paths: [plugins/os-sdlc/]
 affected-components: [os-sdlc, os-backlog, os-adr, os-vault]
 ---
 
diff --git a/plugins/os-sdlc/OVERVIEW.md b/plugins/os-sdlc/OVERVIEW.md
index cada49e..bc5d9bf 100644
--- a/plugins/os-sdlc/OVERVIEW.md
+++ b/plugins/os-sdlc/OVERVIEW.md
@@ -1,127 +1,87 @@
-# os-sdlc — overview (launching point, v0.1)
+# os-sdlc — overview & concept map (v0.2)
 
-Status: scaffold only. No skills/agents/hooks/scripts are implemented yet — this
-document exists to anchor a follow-up brainstorming session, not to lock a design.
+_Last updated: 2026-07-16. Status: design mapped, no implementation yet._
+_This is the single entry point: an AI pointed here loads only the reference/
+nodes its task needs, following the map below._
 
 ## Why this plugin exists
 
-Matt Pocock (mattpocock/skills) shipped a v1.1 lifecycle update (2026-07-14) that
-turned his skill set from a planning tool into a full grill → to-spec → to-tickets →
-implement → code-review → commit pipeline. Separately, `~/dev/delta-refinery` runs a
-heavier, DB-backed, multi-level pipeline (System Design → Behavioral Design →
-Architecture → Slicer → Requirements) with named agent roles per level and a
-Pre/Post/Handoff pattern for resumable multi-agent work.
+Blend two proven inputs into one harness-driven SDLC "factory":
 
-`os-sdlc` is where cc-os adapts the good parts of both — Matt's lightweight linear
-lifecycle and Delta Refinery's structured multi-level handoff discipline — into the
-existing os-* family, wired to `os-backlog` (tickets/tracker) and `os-adr` (decision
-gate), rather than reinventing either. See
-[docs/adr/0037](../../docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md)
-for why this is a plugin inside cc-os rather than a separate `cc-sdlc` marketplace.
+- **Matt Pocock's v1.1 skill lifecycle** (wayfinder/grill → to-spec → to-tickets →
+  implement → code-review → commit) — lightweight, linear, skill-shaped. Notes:
+  SecondBrain vault note `matt-pocock-skills-v1-1-changes.md`.
+- **DeltaRefinery** (`~/dev/delta-refinery`) — the user's prior multi-level pipeline.
+  Retrospective (2026-07-16): keep its virtues — everything deterministic is
+  mechanical; single-job agents with minimal read/communicate/tool surfaces;
+  hook-run tests (the programmer never runs its own tests). Drop its failure
+  modes — headless-run allotment cost, and per-example TDD granularity (batch to
+  one-ticket grain instead).
 
-## Scope: not just skills
+Placement and scope are decided in
+[docs/adr/0037](../../docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md):
+a plugin inside cc-os carrying skills + agents + hooks + reference + scripts,
+composing with `os-backlog` (git issues — Planka retired by ADR-0042), `os-adr`,
+`os-vault`, and `os-context` rather than reinventing any of them.
 
-Unlike most current cc-os plugins, `os-sdlc` is expected to carry all of:
-- **skills/** — the lifecycle verbs (`review` is the first: cherry-picks Matt's
-  standards-conformance + spec-fidelity + Fowler refactor-smell axes into a new
-  `/os-sdlc:review`, coexisting with the existing generic `/code-review`).
-- **agents/** — named roles for pipeline stages, in the spirit of Delta Refinery's
-  per-level agent rosters, sized down to what a lightweight harness actually needs.
-- **hooks/** — session/state wiring where a deterministic check beats a skill.
-- **reference/** — general best-practice material by language/framework/pattern that
-  pipeline stages can pull from (not client- or project-specific — that stays in the
-  vault).
-- **scripts/** — mechanical CLI tooling supporting the above (candidate for the
-  ADR-0025 lib/+bin/ Ruby structure once real logic exists).
+## Concept map
 
-## Working philosophy this plugin should encode
+Each node is an independent context in `reference/`. Edges are "design here
+constrains/feeds design there." Decomposing a node into tickets = grill its
+"Open questions" section, then `to-spec` → `to-tickets` as usual.
 
-Carried over verbatim from the brainstorming that led here, because it's the design
-target, not just a preference:
+```mermaid
+graph TD
+    ST[spec-and-ticket-layer] --> PS[pipeline-stages]
+    PS --> DG[deterministic-gates]
+    PS --> AD[agent-design-principles]
+    PS --> WP[worktree-parallelism]
+    DG --> PF[plugin-factory]
+    PS -.blocked stage.-> NAT[never-ask-twice]
+    NAT <--> SIL[self-improvement-loops]
+    SIL --> PF
+    PS -.deferred.-> HZ[horizon]
+    WP -.deferred.-> HZ
+    NAT -.mobbin.-> HZ
+```
 
-- **Draft-then-refine over get-it-perfect-up-front.** Autoresearch-style loop: draft
-  an idea, implement a first pass, audit process and outcome, hypothesize an
-  improvement, iterate. Applies to both the artifacts os-sdlc produces (specs,
-  tickets, code) and to os-sdlc's own design.
-- **Goal is throughput at trust, not just automation.** The target is being able to
-  automate large chunks of the dev process for big upcoming projects — "move at the
-  speed of thought" — which requires the pipeline to be trustworthy enough at each
-  stage that skipping human review of that stage is safe, not just fast.
-- **Composability with the rest of cc-os is a hard constraint**, not a nice-to-have:
-  os-sdlc must interoperate with `os-backlog` (tickets), `os-adr` (decisions),
-  `os-vault` (cross-project knowledge) — ADR-023's "os-* plugins cooperate" bet
-  applies here directly.
+## Index
 
-## Known inputs for the follow-up brainstorming session
+| Node | Status | One-liner |
+|---|---|---|
+| [spec-and-ticket-layer](reference/spec-and-ticket-layer.md) | settled direction | Git issues (Forgejo/GitHub per tracker key) are the durable spec layer; Pocock verbs map onto it |
+| [pipeline-stages](reference/pipeline-stages.md) | direction | The v1 tracer bullet: `/implement` → test-writer → red-assert → programmer → green-assert → reviewer → human merge |
+| [deterministic-gates](reference/deterministic-gates.md) | settled | Hooks, not agents, run tests/lint; red/green asserted mechanically; green command pluggable per project |
+| [agent-design-principles](reference/agent-design-principles.md) | settled | Single job, minimal tool allowlist (programmer: no Bash), settled facts in via prompt, minimum out via return format |
+| [worktree-parallelism](reference/worktree-parallelism.md) | direction | Worktree-per-spec, sequential tickets within a spec, parallel across specs, human merge gate |
+| [never-ask-twice](reference/never-ask-twice.md) | direction | The agency mechanism: two-tier lookup → mint-time scope classification → audit promotion; decision-category autonomy labels |
+| [self-improvement-loops](reference/self-improvement-loops.md) | direction | Session audits, ADR audits, eval harnesses, skill-lint — each catches a different drift |
+| [plugin-factory](reference/plugin-factory.md) | direction | Same factory builds plugins from a PRD; the eval harness is the green command |
+| [horizon](reference/horizon.md) | horizon | Wake-on-trigger, Herdr controller, router agent, Mobbin — preserved intent, explicitly out of v1 |
 
-- Matt Pocock v1.1 lifecycle notes: `docs/matt-pocock-skills-v1.1-notes.md`.
-- Delta Refinery structure (facts gathered this session, not yet written up as a
-  standalone doc): 5-level `PipelineRunner`/`PipelineOrchestrator`, per-level agent
-  rosters under `.claude/agents/{prd,functional_spec,technical_spec,requirements}/`,
-  intra-level in-memory `Handoff` + inter-level DB-persisted `Artifact#structured_content`
-  for resumability, two composition roots (`HeadwatersComposition` full pipeline vs.
-  `ProductionComposition` requirement-level-only).
-- Existing cc-os pieces this must integrate with: `os-backlog` (capture/list/route),
-  `os-adr` (find/create/init/migrate), `os-vault` (query/write/onboard-project).
-- Open question carried into the brainstorm: how much of Delta Refinery's
-  resumable-handoff machinery is worth adopting now vs. deferred until a concrete
-  multi-session pipeline actually needs it (avoid building it ahead of a real need).
+## Working philosophy (design target, not preference)
 
-## ADW taxonomy input (2026-07-14 session)
+- **Draft-then-refine over get-it-perfect-up-front** — applies to the factory's
+  artifacts and to the factory itself.
+- **Throughput at trust, not just automation** — a stage is done when skipping
+  human review of it is *safe*; trust is earned in units and made durable
+  (see never-ask-twice).
+- **Three actors** (vault note `agentic-sdlc-ai-developer-workflow-taxonomy.md`):
+  every stage first asks whether it needs **code** (deterministic, free),
+  **engineer** (fixed start/end gates), or **agent** (judgment) — never default
+  to agent.
+- **Composability with os-* siblings is a hard constraint** (ADR-023).
 
-Cross-project methodology reference, not repo-specific: see the vault note
-`agentic-sdlc-ai-developer-workflow-taxonomy.md` (SecondBrain) — a taxonomy of AI Developer
-Workflow (ADW) structures from IndyDevDan's "Forget Loop Engineering" video (mermaid diagrams
-included, with `[dan]`/`[jrs]` provenance tags separating his claims from cc-os-specific
-extrapolation). Read it before designing os-sdlc's pipeline shape; the plan below is the
-repo-specific slice of that broader taxonomy.
+## Build sequencing
 
-Three actors of value creation apply directly to os-sdlc's component design: **code**
-(deterministic, free, most reliable — lint/format/test/CI/ticket-state transitions),
-**engineer** (the two fixed constraints: prompting/planning at the start, reviewing at the
-end), **agent** (judgment work: planning, building, scouting). Every os-sdlc pipeline stage
-should be built by first asking which of the three actors it actually needs — don't default
-to "agent" for something code or a human gate should own.
+v1 = the tracer bullet in [pipeline-stages](reference/pipeline-stages.md),
+triggered manually, walked by hand once before wiring into skills/hooks/agents.
+Everything in [horizon](reference/horizon.md) stays unbuilt until the interactive
+factory is trusted. Open items live per-node in each doc's "Open questions" —
+this file carries none.
 
-## First-iteration build plan: a single tracer-bullet ADW
+## Sources
 
-Per the vault note's escalation ladder, and per standing tracer-bullet convention, the first
-build target is the smallest complete loop, not the software factory. Scope:
-
-**One worktree, one pipeline**: `ticket intake → build agent → lint/format/test (hooks) →
-engineer review → ship`. Sandboxes, N-way worktree fan-out, the hotfix ADW, and the software
-factory router are explicitly deferred — documented in the vault note, not built here.
-
-Step by step:
-
-1. **Ticket intake** (code, not agent). Reuse `os-backlog` as the trigger: a card moving to
-   `Doing` (or a linked Forgejo issue via `/to-tickets`) is the pipeline's entry point. No new
-   ticketing system — os-sdlc consumes os-backlog's state, per ADR-0037's composability
-   constraint.
-2. **Build agent** (agent, minimal tools). New `os-sdlc` agent definition: system prompt scoped
-   to "write/modify code to satisfy the spec," tool grants limited to `Read`/`Write`(/`Edit`) —
-   no `Bash`. It cannot run tests or linting itself; it only ever sees pass/fail feedback handed
-   back to it.
-3. **Lint/format/test gate** (code, via hooks — delta-refinery-style Pre/Post/Handoff, not a
-   skill-embedded step). A `PostToolUse`-style hook (or a small script the pipeline invokes
-   between agent turns) runs the project's lint/format/test commands after each build-agent
-   turn. On failure, the failing output is fed back into the *same* build-agent session as the
-   next turn's context (per Dan's separation-of-concerns principle). On pass, advance.
-4. **Engineer review** (human gate). Standard PR/diff review — no change from how review works
-   today; the pipeline's job is to get a clean, tested diff in front of the engineer, not to
-   replace this gate.
-5. **Ship** (code). Merge + whatever this repo's existing deploy path is — os-sdlc does not
-   own deploy; it hands off a mergeable, reviewed change.
-
-Each step above should be walked by hand first (per Dan's second tip) before being wired into
-skills/hooks/agents — run the lint/test loop manually against a real small change, confirm the
-feedback-loop shape works, *then* automate it.
-
-## Not decided yet (do not assume in implementation)
-
-- Which of Matt's skills get adopted as-is vs. adapted vs. skipped, beyond `review`.
-- Whether `implement` is adopted as a thin router as-is, or redesigned as a
-  Delta-Refinery-style level with named sub-roles.
-- Whether `wayfinder` (multi-issue planning for big-plan decomposition) subsumes or
-  sits alongside a Delta-Refinery-style level structure.
-- Any hook or agent definitions — none exist yet.
+- Vault: `matt-pocock-skills-v1-1-changes.md`, `agentic-sdlc-ai-developer-workflow-taxonomy.md`
+- Repo: ADR-0037 (placement), ADR-0042 (git-issues-only backlog), `~/dev/delta-refinery`
+- Tracked follow-ups: cc-os Forgejo issues #71 (audit criteria), #72 (skill-lint), #73 (worktree tracker resolution)
diff --git a/plugins/os-sdlc/reference/agent-design-principles.md b/plugins/os-sdlc/reference/agent-design-principles.md
new file mode 100644
index 0000000..de7ddde
--- /dev/null
+++ b/plugins/os-sdlc/reference/agent-design-principles.md
@@ -0,0 +1,52 @@
+# agent design principles
+
+_Status: settled — as of 2026-07-16_
+_Connects to: [pipeline-stages](pipeline-stages.md), [deterministic-gates](deterministic-gates.md), [overview](../OVERVIEW.md)_
+
+## Purpose
+
+Fixes the shape every os-sdlc agent definition must follow: one job, minimal reads, minimal
+tools, minimal returns. Load this before writing or reviewing any `agents/*.md` definition in
+this plugin.
+
+## Design
+
+- **One clearly-defined job per agent.** It reads only what it needs for that job; it returns
+  the minimum under an explicit return format, so the next stage's context stays clean rather
+  than accumulating everything every prior stage touched.
+- **Minimal tool allowlists via `tools:` frontmatter** in `agents/*.md`. The
+  programmer/build agent gets `Read`/`Write`/`Edit` only — no `Bash`. This is a deliberate
+  `[jrs]` decision in the vault taxonomy note, stronger than IndyDevDan's "separate
+  invocation" stance: rather than merely running build and test in separate agent
+  invocations, the build agent is architecturally incapable of running tests or shells at
+  all. No `WebFetch`/MCP/other-plugin tools unless the specific job needs them. Effect
+  observed in DeltaRefinery: agents scoped this tightly were more focused, cheaper per
+  invocation, and faster — the constraint is a feature, not friction.
+- **Settled facts travel in via the spawn prompt** — an agent never "re-reads what the
+  orchestrator already read." The orchestrating stage resolves context once and hands the
+  agent exactly what it needs in the prompt itself.
+- **Inter-stage state travels via small on-disk handoff artifacts** — a file-based analog of
+  DeltaRefinery's in-memory `Handoff` (intra-level) and DB-persisted `Artifact` (inter-level).
+  os-sdlc keeps this lightweight (files, not a database) because v1 is a single-session
+  tracer-bullet pipeline, not DeltaRefinery's multi-session resumable system.
+- **Model tiering:** mechanical work → haiku; judgment work → sonnet; hard reasoning → opus.
+  Applied per-agent-definition, not per-pipeline — a test-writer doing mechanical
+  transcription of ticket acceptance criteria into test stubs is a different tier than a
+  reviewer judging spec alignment.
+
+## Open questions
+
+- Concrete handoff artifact file format (plain markdown, JSON, frontmatter'd markdown) —
+  not yet chosen.
+- Whether DeltaRefinery-style persisted resumability is needed before multi-session
+  pipelines actually exist. Per the standing "don't build ahead of need" convention (see
+  [pipeline-stages](pipeline-stages.md)'s tracer-bullet framing), this stays undecided until a
+  real multi-session use case shows up.
+
+## Sources
+
+- SecondBrain vault: `agentic-sdlc-ai-developer-workflow-taxonomy.md` (`[jrs]` tool-allowlist
+  stance vs. `[dan]` separate-invocation stance)
+- `~/dev/delta-refinery` (Handoff/Artifact pattern this generalizes from)
+- `plugins/os-sdlc/OVERVIEW.md`
+- 2026-07-16 design session (this doc's origin)
diff --git a/plugins/os-sdlc/reference/deterministic-gates.md b/plugins/os-sdlc/reference/deterministic-gates.md
new file mode 100644
index 0000000..763fd0c
--- /dev/null
+++ b/plugins/os-sdlc/reference/deterministic-gates.md
@@ -0,0 +1,53 @@
+# deterministic gates
+
+_Status: settled — as of 2026-07-16_
+_Connects to: [pipeline-stages](pipeline-stages.md), [agent-design-principles](agent-design-principles.md), [plugin-factory](plugin-factory.md), [overview](../OVERVIEW.md)_
+
+## Purpose
+
+States the core rule that keeps os-sdlc's trust model cheap: agents never self-certify their
+own work, hooks do. Load this when designing any pipeline stage that checks correctness, or
+when wiring hook events for os-sdlc.
+
+## Design
+
+- **Core rule: agents never run tests/lint/format.** Hooks do — either Stop/SubagentStop
+  hooks, or a between-turn pipeline script. This is the mechanism, not just a preference: it
+  is what makes "red→green" something the pipeline *proves* rather than something an agent
+  *claims*, at zero additional LLM cost.
+- On failure, the failing output is injected into the same agent's next turn as context — not
+  routed to a different agent, so the agent that wrote the code gets the direct feedback loop.
+  A max-iteration counter escalates to the human after N failed attempts, rather than looping
+  indefinitely.
+- **Red-assert and green-assert gates** (defined in
+  [pipeline-stages](pipeline-stages.md)) are the two concrete applications of this rule in the
+  v1 pipeline: red-assert proves the tests actually exercise unbuilt behavior, green-assert
+  proves the implementation actually satisfies them.
+- **Pluggable green command.** A per-project config value — proposed home: next to the
+  tracker key in `.cc-os/config` — names the command that proves work green: `rake test` +
+  rubocop for a Rails app, the eval harness for a cc-os plugin itself. This one indirection is
+  what lets the same factory drive arbitrarily different project types without os-sdlc knowing
+  anything about their toolchains.
+- **Three-actors framing** (from the SecondBrain vault note
+  `agentic-sdlc-ai-developer-workflow-taxonomy.md`, IndyDevDan): **code** (deterministic,
+  free, most reliable), **engineer** (fixed start/end points — prompting and reviewing),
+  **agent** (judgment, most expensive and most variable). Every stage in os-sdlc is designed
+  by first asking which actor it actually needs — the default is never "agent."
+  Test-execution and lint/format are unambiguously **code**-actor work; routing them through
+  an agent would be strictly worse on cost, reliability, and speed.
+
+## Open questions
+
+- Exact hook events to use (Stop/SubagentStop) vs. a pipeline-invoked script called between
+  agent turns — a runtime/implementation choice, not yet made.
+- Where the max-iteration count lives (hook config, `.cc-os/config`, or hardcoded per stage)
+  and what the escalation-to-human path looks like concretely.
+
+## Sources
+
+- SecondBrain vault: `agentic-sdlc-ai-developer-workflow-taxonomy.md` (three-actors framing,
+  IndyDevDan)
+- `~/dev/delta-refinery` (Pre/Post/Handoff pattern this generalizes from)
+- `plugins/os-sdlc/OVERVIEW.md`
+- ADR-0037, ADR-0042
+- 2026-07-16 design session (this doc's origin)
diff --git a/plugins/os-sdlc/reference/horizon.md b/plugins/os-sdlc/reference/horizon.md
new file mode 100644
index 0000000..e8ff8a5
--- /dev/null
+++ b/plugins/os-sdlc/reference/horizon.md
@@ -0,0 +1,65 @@
+# horizon
+
+_Status: horizon — explicitly not being built yet; this doc exists to keep these OUT of v1 scope while preserving the design intent — as of 2026-07-16_
+_Connects to: [pipeline-stages](pipeline-stages.md), [worktree-parallelism](worktree-parallelism.md), [never-ask-twice](never-ask-twice.md), [overview](../OVERVIEW.md)_
+
+## Purpose
+
+Parks the ideas that shaped the 2026-07-16 design session but are deliberately excluded
+from v1, so they don't get silently reintroduced as scope creep and don't get lost either.
+Load this when scoping any future os-sdlc milestone, or when a v1 stage's design seems to be
+straining toward one of these — that strain is expected; the boundary is intentional.
+
+## Design
+
+- **Wake-on-trigger.** An issue state change (e.g. label added, ticket moved to "ready")
+  wakes the pipeline instead of a human running `/implement` manually. v1 is deliberately
+  manual — the factory is developed and iterated within interactive sessions until it's
+  trusted to run autonomously. Autonomy is earned the same way [never-ask-twice](never-ask-twice.md)
+  describes for individual decisions, applied here to the pipeline's own trigger.
+- **Herdr integration** (https://herdr.dev/docs/, socket API at
+  https://herdr.dev/docs/socket-api/). A small deterministic controller — no LLM — opens
+  panes, starts interactive Claude Code sessions, sends stage prompts (send_keys-style),
+  detects completion, reads the result, and triggers the next stage. Rationale: Anthropic
+  now charges extra time allotment for headless runs, so driving automated coding through
+  headless mode would eat into the allotment the Max plan's coding was bought for; Herdr-driven
+  *interactive* sessions bill as normal usage instead, preserving that allotment for other
+  purposes (e.g. a future Hermes integration). **Load-bearing unknown to spike before leaning
+  on this at all: does the Herdr socket API give reliable "agent finished" detection, or only
+  heuristic pane-scraping?** If it's only heuristic scraping, completion-detection false
+  positives/negatives could silently corrupt pipeline stage transitions — this needs to be
+  proven, not assumed, before Herdr becomes load-bearing infrastructure.
+- **Router agent** dispatching tickets to specialized pipelines (chore/bug/feature/hotfix,
+  each with a different stage shape). Deferred until v1's single pipeline shape is proven
+  insufficient — matches the ladder described in the SecondBrain vault taxonomy note; adding
+  a router before it's needed would be exactly the premature-granularity mistake
+  [pipeline-stages](pipeline-stages.md) already rejected once (the seam-creator/implementor
+  split).
+- **Mobbin UX decision-tree seeding.** See [never-ask-twice](never-ask-twice.md) — a
+  pre-seeded convention library (mobbin.com) for the UI-flow decision category, letting
+  front-end decisions start at `semi` autonomy instead of `hitl`. Horizon because it depends
+  on the category-autonomy mechanism existing and being trusted first.
+- **End-state vision** (verbatim intent from the user, 2026-07-16): plan alongside the AI in
+  one window; when ready, work is delegated, automatically prioritized, decomposed, and
+  worked until complete or blocked; blockages are resolved immediately AND minted into
+  ADRs/best practices/conventions so that next time the AI confidently picks the obvious path
+  or presents a narrowed choice; the factory self-improves over time and agents take agency
+  as confidence in their decisions is earned.
+
+## Open questions
+
+- Whether wake-on-trigger and Herdr integration are actually separable milestones (wake-on-trigger
+  could plausibly ship without Herdr, using headless mode at the accepted allotment cost) or
+  whether they're coupled in practice.
+- What "trusted to run autonomously" concretely means as an exit criterion for v1 — likely an
+  ask-rate threshold fed by [never-ask-twice](never-ask-twice.md)'s audits, but not yet defined.
+- Whether the router-agent ladder rungs (chore/bug/feature/hotfix) match the vault taxonomy
+  note's categories exactly or need adjustment once real ticket volume exists.
+
+## Sources
+
+- Herdr docs: https://herdr.dev/docs/, https://herdr.dev/docs/socket-api/
+- SecondBrain vault: taxonomy/ladder note (chore/bug/feature/hotfix router categories)
+- mobbin.com (design-pattern library)
+- ADR-0037
+- 2026-07-16 design session (this doc's origin, including verbatim end-state vision)
diff --git a/plugins/os-sdlc/reference/never-ask-twice.md b/plugins/os-sdlc/reference/never-ask-twice.md
new file mode 100644
index 0000000..3c326a9
--- /dev/null
+++ b/plugins/os-sdlc/reference/never-ask-twice.md
@@ -0,0 +1,76 @@
+# never ask twice
+
+_Status: direction — as of 2026-07-16_
+_Connects to: [self-improvement-loops](self-improvement-loops.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [horizon](horizon.md), [overview](../OVERVIEW.md)_
+
+## Purpose
+
+The agency mechanism, and the most important node in this reference set. States the
+operating principle that lets the factory earn autonomy over time instead of asking the
+human the same question on every run. Load this before designing any blocked-stage
+behavior, any human-input point in the pipeline, or ADR-0037's follow-on formalization ADR.
+
+## Design
+
+- **Operating principle: the factory never asks the human the same question twice.** Trust
+  is earned in units, and every unit is made durable and reusable. Goal state: the human is
+  only presented options when the factory genuinely needs direction — not because a decision
+  that was already made once was forgotten.
+- No new storage system and no literal decision-tree engine. The "tree" is the existing ADR
+  corpus plus vault conventions; os-sdlc adds only wiring on top of os-adr and os-vault.
+  Three thin pieces:
+  1. **Two-tier lookup at block time.** Before any question reaches the human, the blocked
+     stage runs a mandatory, mechanical chain: `/os-adr:find` over the repo's ADRs first,
+     then `/os-vault:query` over `domain/`/`tool/`/`convention/` facets. Only a genuine miss
+     on both tiers produces a human-facing question.
+  2. **Scope classification at mint time.** When the human unblocks a stage by answering,
+     the factory asks one follow-up: "does this generalize beyond this repo?" No → record a
+     repo-local ADR only. Yes → a vault convention note becomes the source of truth, and the
+     repo ADR records the local adoption with a link back to it. The ask is not complete
+     until the record exists — an answered-but-unrecorded question is the failure mode this
+     whole mechanism exists to prevent.
+  3. **Promotion by audit, not memory.** A decision minted local that later blocks a second
+     project is a recurrence — visible across blocked-stage logs, not tracked live. A
+     periodic audit (see [self-improvement-loops](self-improvement-loops.md)) sees the
+     recurrence and promotes the answer to a vault convention.
+- **Decision-category autonomy labels**, generalized from individual tickets to decision
+  *categories* (e.g. dependency choice, schema-migration approach, UI flow pattern):
+  - `afk-ready` + a covering record → proceed and cite the record.
+  - `semi` → proceed, but flag the decision in the stage report for human review.
+  - `hitl`, or no coverage at all → stop and ask.
+  Promotion and demotion of categories happens only in periodic audits, never mid-run.
+- **Cross-project answer, worked example:** a decision minted while building rails app A
+  should be available when building rails app B. Repo ADRs are deliberately project-local
+  (they record local adoption, not universal truth); the vault is the cross-project layer.
+  os-sdlc doesn't change this split — it adds the lookup chain, the mint ritual, and the
+  audit-driven promotion path on top of it.
+- **Honest limit:** this mechanism guarantees the *plumbing* — a decision recorded once is
+  findable everywhere it applies — not the *judgment* that the agent applies the right
+  convention in an ambiguous case. Judgment quality is proven only by accumulated audits.
+  Expect the ask-rate to fall as categories graduate from `hitl`/`semi` to `afk-ready`; a
+  category that graduates too early gets demoted, with the ADR trail showing exactly which
+  decision went wrong and why.
+- **Mobbin** (mobbin.com, a design-pattern reference library) as a future pre-seeded
+  convention library for the UI-flow decision category — would let front-end decisions start
+  at `semi` instead of `hitl` from day one. This is horizon-scoped (see
+  [horizon](horizon.md)) but validates that the category-autonomy frame generalizes to
+  externally-sourced conventions, not just self-mined ones.
+- This mechanism spans os-sdlc, os-adr, and os-vault jointly and gets its own ADR when
+  formalized — it is not owned by any single plugin.
+
+## Open questions
+
+- Block-report format: what a blocked stage writes when it stops to ask (must carry enough
+  context for the two-tier lookup to be re-run later without re-asking).
+- Where decision-category labels live (ADR frontmatter? a small config file? vault note
+  frontmatter?) and who assigns the initial label for a brand-new category.
+- Audit cadence for promotion/demotion (tied to [self-improvement-loops](self-improvement-loops.md)'s
+  ADR-audit loop, but not yet fixed).
+
+## Sources
+
+- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
+- os-adr `find`/`create` skills; os-vault `query`/`write` skills
+- SecondBrain vault: taxonomy/ladder note (referenced by [horizon](horizon.md))
+- mobbin.com (design-pattern library, horizon reference)
+- 2026-07-16 design session (this doc's origin)
diff --git a/plugins/os-sdlc/reference/pipeline-stages.md b/plugins/os-sdlc/reference/pipeline-stages.md
new file mode 100644
index 0000000..241d713
--- /dev/null
+++ b/plugins/os-sdlc/reference/pipeline-stages.md
@@ -0,0 +1,68 @@
+# pipeline stages
+
+_Status: direction — as of 2026-07-16_
+_Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [worktree-parallelism](worktree-parallelism.md), [overview](../OVERVIEW.md)_
+
+## Purpose
+
+Defines the v1 tracer-bullet pipeline shape for `/implement <ticket>`: the ordered stages,
+which actor (code/engineer/agent) owns each, and the two decisions that keep the pipeline at
+one-agent-one-job grain. Load this before designing any pipeline stage, skill, or agent
+definition for os-sdlc.
+
+## Design
+
+Manually triggered by `/implement <ticket>`. Stages, in order:
+
+1. **Ticket intake** (code) — reads the issue via the `os-backlog` tracker key
+   (`.cc-os/config`); no new ticketing system, per ADR-0037's composability constraint.
+2. **Test-writer agent** — writes failing tests from the ticket, nothing else.
+3. **Red-assert gate** (deterministic hook) — runs the suite; it MUST fail. A pass here means
+   vacuous tests or the feature already exists — either way the pipeline halts rather than
+   proceeding on a false signal.
+4. **Programmer agent** — makes the tests pass. One agent, not a seam-creator/implementor
+   split.
+5. **Green-assert gate** (deterministic hook) — suite + lint must pass. Failures are
+   auto-fed back into the same programmer's next turn; a max-iterations cap escalates to the
+   human rather than looping forever.
+6. **Reviewer agent** — two ordered checks: first tests align with the spec/ticket, then code
+   aligns with both tests and spec. Order matters — misaligned tests invalidate a "code passes
+   tests" result.
+7. **Cleanup & report** (agent/code mix) — trims scratch artifacts, produces a summary for the
+   human.
+8. **Human merge gate** — v1 has no automated merge; see
+   [worktree-parallelism](worktree-parallelism.md).
+
+Two decisions fix the grain of this pipeline:
+
+- **One programmer agent, not seam-creator/implementor.** The seam is not a judgment
+  boundary — splitting it adds a handoff and context loss for no trust gain. This is exactly
+  the over-granularity DeltaRefinery suffered from. Revisit only if audits show programmers
+  entangling design decisions to cheat tests (i.e., gaming the green-assert gate instead of
+  solving the ticket).
+- **Refactor is not a standing stage.** The reviewer's critique triggers a correction loop —
+  re-invoking the programmer with findings — using the same feedback mechanism as a failing
+  gate, rather than a dedicated pipeline stage.
+
+Grain: one ticket, one vertical slice. TDD is internal to the stage (test-writer then
+programmer within one ticket's run), never orchestrated per-example from outside — that
+per-example granularity was a DeltaRefinery downside being deliberately dropped.
+
+## Open questions
+
+- Skill/agent naming for each stage (test-writer, programmer, reviewer) — must follow the
+  cc-os naming convention before anything ships.
+- Whether a cheap tests-vs-spec review should run *before* the programmer stage in later
+  versions, to catch misaligned tests before paying for implementation.
+- Whether Pocock's `implement` skill is adopted as a thin router over these stages, or
+  redesigned from scratch.
+
+## Sources
+
+- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
+- ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
+- `plugins/os-sdlc/OVERVIEW.md`
+- SecondBrain vault: `agentic-sdlc-ai-developer-workflow-taxonomy.md`,
+  `matt-pocock-skills-v1-1-changes.md`
+- `~/dev/delta-refinery` (prior art, principles kept/dropped as noted above)
+- 2026-07-16 design session (this doc's origin)
diff --git a/plugins/os-sdlc/reference/plugin-factory.md b/plugins/os-sdlc/reference/plugin-factory.md
new file mode 100644
index 0000000..4b3ec4e
--- /dev/null
+++ b/plugins/os-sdlc/reference/plugin-factory.md
@@ -0,0 +1,53 @@
+# plugin factory
+
+_Status: direction — as of 2026-07-16_
+_Connects to: [deterministic-gates](deterministic-gates.md), [self-improvement-loops](self-improvement-loops.md), [pipeline-stages](pipeline-stages.md), [overview](../OVERVIEW.md)_
+
+## Purpose
+
+States that os-sdlc is the same factory cc-os uses to build its own `os-*` plugins, not a
+separate meta-tool — and how that reflexive use case is possible without a second pipeline.
+Load this before scaffolding a new `os-*` plugin, or before designing anything that looks
+like a "plugin builder" separate from the ticket pipeline in
+[pipeline-stages](pipeline-stages.md).
+
+## Design
+
+- **The same factory builds cc-os plugins from a PRD.** This works because the green command
+  is pluggable per project (see [deterministic-gates](deterministic-gates.md)): for a normal
+  application repo it's `rake test` + lint; for an AiDD-type project (a cc-os plugin) **the
+  eval harness IS the test suite**. TDD becomes eval-driven development — write the eval,
+  watch it fail for the right reason, build the skill until it passes — with no separate
+  pipeline, no special-cased plugin-building mode. The pipeline stages in
+  [pipeline-stages](pipeline-stages.md) run unchanged; only the green-command config value
+  differs.
+- **Plugins self-evolve after they ship.** Once a plugin exists, its own operation becomes
+  input back into the same factory: audits of sessions it participated in (loop a),
+  ADR-corpus audits touching its decisions (loop b), its own eval-harness regressions (loop
+  c), and direct user feedback all generate improvement tickets. Those tickets re-enter
+  factory intake exactly like any other ticket — a plugin is never "done," it's a standing
+  client of its own factory. See [self-improvement-loops](self-improvement-loops.md) for the
+  four loops that produce this feedback.
+- This closes the loop cc-os has been running informally (build a plugin, notice drift in
+  use, fix it in a follow-up session) into something the factory itself can drive
+  end-to-end: PRD → spec → tickets → implement → ship → audit → new tickets.
+
+## Open questions
+
+- PRD template for plugins specifically — likely narrower than a general product PRD (needs
+  to name: the eval harness location, the green command, which existing `os-*` plugins it
+  composes with per ADR-0037's composability constraint).
+- Eval-first scaffolding: the red-assert analog for eval-driven development — does
+  `to-tickets`/`/implement` need a variant stage that writes the eval scenario before the
+  skill exists, mirroring the test-writer stage in [pipeline-stages](pipeline-stages.md)?
+- How improvement tickets are auto-generated from audit findings — format, who/what creates
+  the issue (a code-actor script parsing an audit report, or an agent stage), and how
+  duplicate/overlapping findings across the four loops get deduplicated before hitting the
+  tracker.
+
+## Sources
+
+- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
+- `plugins/os-sdlc/OVERVIEW.md`
+- `plugins/os-vault/eval/`, `plugins/os-adr/eval/`, `plugins/os-context/eval/`
+- 2026-07-16 design session (this doc's origin)
diff --git a/plugins/os-sdlc/reference/self-improvement-loops.md b/plugins/os-sdlc/reference/self-improvement-loops.md
new file mode 100644
index 0000000..14ee7ca
--- /dev/null
+++ b/plugins/os-sdlc/reference/self-improvement-loops.md
@@ -0,0 +1,66 @@
+# self improvement loops
+
+_Status: direction — as of 2026-07-16_
+_Connects to: [never-ask-twice](never-ask-twice.md), [plugin-factory](plugin-factory.md), [overview](../OVERVIEW.md)_
+
+## Purpose
+
+Names the four periodic audit loops that keep the factory (and the plugins it builds)
+honest over time, and which of them already exist vs. are new. Load this before designing
+any audit skill, before scoping ADR-audit work, or before wiring an improvement-ticket
+generator into the factory.
+
+## Design
+
+Four loops, each catching a different kind of drift. None of them fire mid-run — all are
+periodic, out-of-band audits, deliberately kept separate from the pipeline itself so an
+audit's own cost/latency never blocks a ticket.
+
+- **a. Session audits** (exists) — os-context's biweekly IRL audit. Catches behavior drift
+  in how sessions actually run. Needs rework per cc-os Forgejo issue #71: current criteria
+  don't catch expensive-model overuse where delegation or determinism would cut cost with no
+  quality drop — a gap directly relevant to os-sdlc's actor-choice discipline (see
+  [deterministic-gates](deterministic-gates.md)'s code/engineer/agent framing).
+- **b. ADR audits** (new, proposed 2026-07-16) — catches corpus drift, the counterpart to
+  session audits but aimed at the decision record itself rather than session transcripts.
+  Periodically audits the ADR corpus for: stale decisions, missed promotions to the vault
+  (a local ADR that should have graduated per
+  [never-ask-twice](never-ask-twice.md)'s promotion-by-audit step but didn't), and
+  scope-classification judgment calls that slipped through at mint time. A wrong mint-time
+  call is treated as a delay, not a loss — anything missed gets caught in the next ADR
+  audit, so the loop is self-correcting rather than requiring the mint-time call to be
+  perfect.
+- **c. Eval harnesses** (exists — autoresearch pattern, already running for os-vault,
+  os-adr, os-context) — catches capability regression. Functions as "the AI version of TDD"
+  for plugin-type projects: a plugin's eval suite is the thing that must stay green across
+  changes, the same role a test suite plays for application code (see
+  [plugin-factory](plugin-factory.md) for the eval-as-green-command connection).
+- **d. Skill-lint** (new, cc-os Forgejo issue #72) — catches skill-authoring drift. os-context
+  lints `SKILL.md` files for progressive disclosure on complex tasks and reasonable file
+  sizes, keeping agent context windows lean as the skill corpus grows.
+
+Together, these four loops are:
+- the **promotion engine** for [never-ask-twice](never-ask-twice.md) — (b) is the mechanism
+  that actually performs the audit-driven promotion that mechanism depends on;
+- the **self-evolution channel** for [plugin-factory](plugin-factory.md) — (a), (c), and (d)
+  are exactly the inputs that turn into improvement tickets fed back into factory intake.
+
+## Open questions
+
+- ADR-audit criteria: what specifically counts as "stale," how missed promotions are
+  detected mechanically (diffing local ADRs against vault convention notes?), and cadence.
+- Whether ADR audits live in os-context (alongside the existing session-audit skill) or in
+  os-adr (alongside `find`/`create`/`migrate`) — an ownership question, not yet settled.
+- Whether (a)-(d) should share a common audit-report format so
+  [plugin-factory](plugin-factory.md)'s improvement-ticket generator can consume all four
+  uniformly, or whether each stays bespoke.
+
+## Sources
+
+- os-context `audit-sessions` skill (existing biweekly IRL audit)
+- cc-os Forgejo issue #71 (session-audit rework, expensive-model overuse)
+- cc-os Forgejo issue #72 (skill-lint)
+- `plugins/os-vault/eval/`, `plugins/os-adr/eval/`, `plugins/os-context/eval/` (autoresearch
+  eval harnesses)
+- ADR-0037
+- 2026-07-16 design session (this doc's origin)
diff --git a/plugins/os-sdlc/reference/spec-and-ticket-layer.md b/plugins/os-sdlc/reference/spec-and-ticket-layer.md
new file mode 100644
index 0000000..ed74d35
--- /dev/null
+++ b/plugins/os-sdlc/reference/spec-and-ticket-layer.md
@@ -0,0 +1,59 @@
+# spec and ticket layer
+
+_Status: settled direction — as of 2026-07-16_
+_Connects to: [pipeline-stages](pipeline-stages.md), [worktree-parallelism](worktree-parallelism.md), [never-ask-twice](never-ask-twice.md), [overview](../OVERVIEW.md)_
+
+## Purpose
+
+States where specs and tickets live and how a plan becomes an increment `/implement` can
+consume. Load this before designing `to-spec`, `to-tickets`, or any skill that reads/writes
+issue-tracker state for os-sdlc.
+
+## Design
+
+- **Git issues are the durable spec layer.** Forgejo (via `tea`) or GitHub (via `gh`),
+  resolved per-project by the os-backlog tracker key in `.cc-os/config`
+  (`forgejo:owner/repo`, `github:owner/repo`, or `repo:path` — ADR-0042). Planka is retired;
+  there is no separate os-sdlc storage for specs or tickets.
+- **Composability constraint (ADR-0037):** os-sdlc consumes `os-backlog` rather than
+  reinventing ticketing. Ticket intake, creation, and listing go through os-backlog's
+  `issue-create`/`issues` CLI wrappers, not a parallel os-sdlc data model.
+- **Pocock lifecycle mapping**, adapted to the git-issues substrate:
+  - **wayfinder** — big plans, new ideas. Free-form exploration, not yet tracker-shaped.
+  - **grill-with-docs** — sharpens or decomposes a plan further where user direction is
+    genuinely needed (see [never-ask-twice](never-ask-twice.md) for when a question should
+    instead be answered by lookup rather than posed here).
+  - **to-spec** — publishes the sharpened plan to the issue tracker as a spec-bearing issue
+    (or epic-equivalent) — the durable artifact other stages read from.
+  - **to-tickets** — decomposes the spec into feature-specific, independently-implementable
+    increments, each its own issue, tracer-bullet style (same shape as the existing
+    `to-issues` skill, but scoped to a published spec rather than an ad hoc plan).
+  - **`/implement`** — consumes exactly one ticket into the [pipeline-stages](pipeline-stages.md)
+    pipeline. One ticket in, one worktree/branch out (see
+    [worktree-parallelism](worktree-parallelism.md)).
+- The tracker is the single source of truth for spec *and* ticket state — no shadow status
+  file. Stage reports (pipeline-stages) update the issue via comments/labels rather than a
+  separate os-sdlc-owned record.
+- Spec and ticket content structure is intentionally not fixed yet (see Open questions) —
+  the mapping above fixes *where* things live and *what stage produces them*, not their
+  internal template.
+
+## Open questions
+
+- Which Pocock skills (wayfinder, grill-with-docs, to-spec, to-tickets) are adopted
+  near-verbatim vs. adapted for the git-issues substrate vs. skipped entirely.
+- Whether wayfinder subsumes or sits alongside a DeltaRefinery-style level structure
+  (DeltaRefinery decomposed work into explicit levels; Pocock's wayfinder is looser).
+- Concrete spec issue template (sections, required fields) and ticket issue template
+  (acceptance criteria shape, tracer-bullet slice size).
+- Whether `to-tickets` reuses the existing `to-issues` skill directly or needs its own
+  spec-aware variant.
+
+## Sources
+
+- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
+- ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
+- `plugins/os-sdlc/OVERVIEW.md`
+- SecondBrain vault: `matt-pocock-skills-v1-1-changes.md`
+- `plugins/os-backlog/` (tracker key, `issue-create`/`issues` CLI, `to-issues` skill)
+- 2026-07-16 design session (this doc's origin)
diff --git a/plugins/os-sdlc/reference/worktree-parallelism.md b/plugins/os-sdlc/reference/worktree-parallelism.md
new file mode 100644
index 0000000..e27e27d
--- /dev/null
+++ b/plugins/os-sdlc/reference/worktree-parallelism.md
@@ -0,0 +1,49 @@
+# worktree parallelism
+
+_Status: direction — as of 2026-07-16_
+_Connects to: [pipeline-stages](pipeline-stages.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [horizon](horizon.md), [overview](../OVERVIEW.md)_
+
+## Purpose
+
+Defines how os-sdlc scopes concurrency: worktree-per-spec, sequential tickets within a spec,
+parallelism across specs. Load this when designing worktree lifecycle automation or any
+multi-ticket/multi-spec orchestration for os-sdlc.
+
+## Design
+
+- **Worktree-per-spec.** Tickets belonging to one spec run sequentially inside a single
+  worktree — this avoids intra-spec merge conflicts entirely, since only one pipeline run is
+  ever touching that worktree's files at a time.
+- **Parallelism happens across specs**, not within one. Multiple specs, each with its own
+  worktree and its own sequential ticket queue, can run concurrently to keep overall progress
+  rolling without any single spec's pipeline blocking another's.
+- **Merge is a human gate in v1** — consistent with [pipeline-stages](pipeline-stages.md)'s
+  final stage. No automated merge choreography yet.
+- **Tiered isolation ladder** (from the vault taxonomy note): no isolation → single worktree →
+  N parallel worktrees → full sandbox. os-sdlc v1 sits at "single worktree" per spec; a router
+  agent that picks the isolation tier per task is explicitly deferred until a concrete case
+  proves it's needed — not built ahead of that need.
+- **Known bug — cc-os Forgejo issue #73:** `.cc-os/config` is untracked, so worktrees don't
+  inherit the tracker key, and `os-backlog` issue-create fails inside them. This blocks
+  ticket-intake (stage 1 of [pipeline-stages](pipeline-stages.md)) from working inside a
+  worktree today. The factory needs a native fix — either walking up to the owning repo root
+  to find the config, or provisioning `.cc-os/config` at worktree-creation time.
+
+## Open questions
+
+- Whether Pocock's `wayfinder:map` tags should drive merge choreography — check the vault
+  note `matt-pocock-skills-v1-1-changes.md` when designing this; not yet evaluated against
+  os-sdlc's spec/ticket model.
+- Worktree lifecycle automation: who creates a worktree for a new spec, who cleans it up after
+  merge, and what triggers each.
+- Branch naming convention for spec-level and (if they ever become worth it) per-ticket
+  branches under a spec branch.
+
+## Sources
+
+- SecondBrain vault: `agentic-sdlc-ai-developer-workflow-taxonomy.md` (tiered isolation
+  ladder), `matt-pocock-skills-v1-1-changes.md` (wayfinder:map)
+- cc-os Forgejo issue #73 (`.cc-os/config` untracked, worktree tracker-key inheritance bug)
+- ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
+- `plugins/os-sdlc/OVERVIEW.md`
+- 2026-07-16 design session (this doc's origin)

From 4cc524b3a505de0fd1474ca32a397b912470b9f4 Mon Sep 17 00:00:00 2001
From: jared <jared@swansoncloud.com>
Date: Thu, 16 Jul 2026 16:08:23 -0400
Subject: [PATCH 2/4] =?UTF-8?q?os-sdlc:=20observability=20node,=20ADR=20co?=
 =?UTF-8?q?py-tag-audit=20pattern,=20to-issues=E2=86=92to-tickets=20rename?=
 =?UTF-8?q?=20adopted?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- reference/pipeline-observability.md: new tenth concept node (run exhaust,
  predefined lifespans via os-doc-hygiene, copy-tag-audit pattern)
- self-improvement-loops: ADR-audit mechanics via vault-copy hook + virgin-tag
- spec-and-ticket-layer: to-tickets confirmed as Pocock v1.1 rename of
  to-issues (leftover skill removed from ~/.agents/skills)
- OVERVIEW: map + index updated, grill queue recorded
- repo docs: live /to-issues references swapped to /to-tickets

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VgG2g9ooqbnBiZYGAonGYG
---
 CLAUDE.md                                     |  2 +-
 docs/implementation-status.md                 |  2 +-
 docs/implementation-status/os-backlog.md      |  6 +--
 docs/issue-workflow.md                        | 10 ++--
 plugins/os-backlog/skills/route/SKILL.md      |  2 +-
 plugins/os-sdlc/OVERVIEW.md                   | 12 +++++
 .../reference/pipeline-observability.md       | 46 +++++++++++++++++++
 plugins/os-sdlc/reference/pipeline-stages.md  |  5 +-
 .../reference/self-improvement-loops.md       | 13 ++++--
 .../reference/spec-and-ticket-layer.md        |  9 ++--
 10 files changed, 86 insertions(+), 21 deletions(-)
 create mode 100644 plugins/os-sdlc/reference/pipeline-observability.md

diff --git a/CLAUDE.md b/CLAUDE.md
index d44fe99..2cd2da2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -108,7 +108,7 @@ next signal is production IRL session audits.
 
 ## Issue tracking
 
-Issues (created via `/to-issues`) live on self-hosted Forgejo (`jared/cc-os`), queried with
+Issues (created via `/to-tickets`) live on self-hosted Forgejo (`jared/cc-os`), queried with
 the `tea` CLI — not GitHub/`gh`. See `docs/issue-workflow.md`.
 
 ## OpenSpec workflow
diff --git a/docs/implementation-status.md b/docs/implementation-status.md
index 405b967..9ae56fb 100644
--- a/docs/implementation-status.md
+++ b/docs/implementation-status.md
@@ -61,7 +61,7 @@ entry is in the leaf file named.
   (ADR-0031) + three new prompt files; `/readonly` decided as plan-mode convention, no
   skill (ADR-0030); os-doc-hygiene `file_length` scanner signal shipped (issue #25 part 1);
   this file distilled to index+PD (issue #25 parts 2–3, ADR-0032). os-backlog slice 7
-  shipped: SessionStart injection note + /to-issues tracker routing (issue #16); board-id
+  shipped: SessionStart injection note + /to-tickets tracker routing (issue #16); board-id
   cache via BoardResolver (issue #22); slice 8 — Operations board + tracker-routing rubric
   category + ADR-0033 canonizing Planka-state/git-issues-spec (issue #17); route inspect
   issue-shape classification + split-by-kind default (issue #26); cross-project filing
diff --git a/docs/implementation-status/os-backlog.md b/docs/implementation-status/os-backlog.md
index 2cbdf14..d91c46e 100644
--- a/docs/implementation-status/os-backlog.md
+++ b/docs/implementation-status/os-backlog.md
@@ -73,8 +73,8 @@ column ownership).
   (`hooks/session_start.py` + `hooks/hooks.json`, os-adr-style plugin-local hook): WHEN→THEN
   rules for capture / routing / promotion / column ownership / autonomy labels, ADR-0029
   semantics (the issue body's "afk-ready → Review" was wrong — caught in Codex review),
-  rules only, zero board state, ~447 tokens. `/to-issues` (global skill,
-  `~/.agents/skills/to-issues/`) gained a destination-tracker step reading the
+  rules only, zero board state, ~447 tokens. `to-issues` (now `to-tickets`; global skill,
+  then at `~/.agents/skills/to-issues/`) gained a destination-tracker step reading the
   `.cc-os/config` tracker key; the `planka:`/unset default publishes slices as git issues
   on the repo remote + one Planka pointer card (spec/state boundary preserved — human gate
   decided 2026-07-13). `Backlog::Tracker.issues_destination` + 6 routing tests.
@@ -89,7 +89,7 @@ column ownership).
   IRL audit (recurring)" (card `1818310715438531668`, P2 + semi, first progress comment
   `1818310889929966683`; recurrence contract: comment + move back to Backlog, never Done).
   Tracker-routing convention canonized as **ADR-0033** (Planka = state / git issues = specs,
-  tracker key grammar, pointer + promotion rules; cites route/to-issues/session-start
+  tracker key grammar, pointer + promotion rules; cites route/to-tickets/session-start
   rather than restating). os-context audit rubric gained category 8 `tracker-routing`
   (capture/route/promote compliance only). Bug found live and fixed: label color fallback
   only rescued `Planka::ValidationError`, but Planka rejects unknown colors as HTTP 400
diff --git a/docs/issue-workflow.md b/docs/issue-workflow.md
index 34f653f..e90c070 100644
--- a/docs/issue-workflow.md
+++ b/docs/issue-workflow.md
@@ -1,8 +1,10 @@
 # Issue workflow (Forgejo + tea)
 
-_Last updated: 2026-06-30._
+_Last updated: 2026-07-16._
 
-How issues created by the `/to-issues` skill get tracked and implemented in this repo.
+Note (2026-07-16): the `/to-issues` skill was renamed to `/to-tickets` in Matt Pocock's v1.1 skill set.
+
+How issues created by the `/to-tickets` skill get tracked and implemented in this repo.
 
 ## Tracker
 
@@ -33,7 +35,7 @@ tea issues <N> --repo jared/cc-os     # view one issue's body
 
 ## Implement
 
-There is **no auto-trigger and no `/grab` command**. Issues from `/to-issues` are written as independently-grabbable tracer-bullet slices. To implement:
+There is **no auto-trigger and no `/grab` command**. Issues from `/to-tickets` are written as independently-grabbable tracer-bullet slices. To implement:
 
 1. Pick the next **unblocked** issue (check the "Blocked by" line in the body — slices often form a linear chain).
 2. Hand it to a coding session: _"implement issue #N from forgejo jared/cc-os"_.
@@ -48,4 +50,4 @@ tea issues close <N> --repo jared/cc-os
 
 ## Caveat
 
-The Matt-Pocock `to-issues` / `triage` skills default to **GitHub** and were never wired to this Forgejo/`tea` backend for cc-os (no `docs/agents/` config, no `.scratch/`). Re-running them assumes GitHub. Running `/setup-matt-pocock-skills` and describing the `tea`/Forgejo workflow would wire them to the right tracker.
+The Matt-Pocock `to-tickets` (formerly `to-issues`) / `triage` skills default to **GitHub** and were never wired to this Forgejo/`tea` backend for cc-os (no `docs/agents/` config, no `.scratch/`). Re-running them assumes GitHub. Running `/setup-matt-pocock-skills` and describing the `tea`/Forgejo workflow would wire them to the right tracker.
diff --git a/plugins/os-backlog/skills/route/SKILL.md b/plugins/os-backlog/skills/route/SKILL.md
index 66075d4..9ea342d 100644
--- a/plugins/os-backlog/skills/route/SKILL.md
+++ b/plugins/os-backlog/skills/route/SKILL.md
@@ -9,7 +9,7 @@ Register a project's issue tracker: figure out what already exists, propose wher
 Planka = state, git issues = specs (ADR-0033, `docs/adr/0033-tracker-routing-planka-is-state-git-issues-are-specs.md`) — the ADR is the canonical statement; the operative routing rules are:
 
 - **WHEN** the project's work is mostly ephemeral tasks, small fixes, or process/coordination (state: backlog/next/doing/review/done, nothing needing a durable written spec) → `planka:<board>`.
-- **WHEN** work is specified as text that must survive and be referenced (features, migrations, architecture-level changes, tracer-bullet slices from `/to-issues`, PRDs from `/to-prd`) → `forgejo:<owner>/<repo>` or `github:<owner>/<repo>`.
+- **WHEN** work is specified as text that must survive and be referenced (features, migrations, architecture-level changes, tracer-bullet slices from `/to-tickets`, PRDs from `/to-prd`) → `forgejo:<owner>/<repo>` or `github:<owner>/<repo>`.
 - **WHEN** a project already tracks issues in-repo (`docs/issues/`, `ISSUES.md`) and wants to stay there → `repo:<path>` (the escape hatch).
 - **WHEN** a code effort needs both state tracking and a durable spec → card-as-pointer + issue-chain-as-spec: the Planka card is a pointer (title + link) into the git issue chain holding the spec; never duplicate spec text into the card description.
 - **WHEN** a Planka-tracked effort accretes significant code/design decisions in card comments → flag promotion to the user (open a git issue chain for the spec, turn the card into a pointer); never promote silently.
diff --git a/plugins/os-sdlc/OVERVIEW.md b/plugins/os-sdlc/OVERVIEW.md
index bc5d9bf..453c275 100644
--- a/plugins/os-sdlc/OVERVIEW.md
+++ b/plugins/os-sdlc/OVERVIEW.md
@@ -37,8 +37,10 @@ graph TD
     PS --> AD[agent-design-principles]
     PS --> WP[worktree-parallelism]
     DG --> PF[plugin-factory]
+    PS --> PO[pipeline-observability]
     PS -.blocked stage.-> NAT[never-ask-twice]
     NAT <--> SIL[self-improvement-loops]
+    PO --> SIL
     SIL --> PF
     PS -.deferred.-> HZ[horizon]
     WP -.deferred.-> HZ
@@ -54,6 +56,7 @@ graph TD
 | [deterministic-gates](reference/deterministic-gates.md) | settled | Hooks, not agents, run tests/lint; red/green asserted mechanically; green command pluggable per project |
 | [agent-design-principles](reference/agent-design-principles.md) | settled | Single job, minimal tool allowlist (programmer: no Bash), settled facts in via prompt, minimum out via return format |
 | [worktree-parallelism](reference/worktree-parallelism.md) | direction | Worktree-per-spec, sequential tickets within a spec, parallel across specs, human merge gate |
+| [pipeline-observability](reference/pipeline-observability.md) | direction | What a run writes down (exhaust), where it lives, predefined lifespans (os-doc-hygiene); copy-tag-audit pattern feeds the loops |
 | [never-ask-twice](reference/never-ask-twice.md) | direction | The agency mechanism: two-tier lookup → mint-time scope classification → audit promotion; decision-category autonomy labels |
 | [self-improvement-loops](reference/self-improvement-loops.md) | direction | Session audits, ADR audits, eval harnesses, skill-lint — each catches a different drift |
 | [plugin-factory](reference/plugin-factory.md) | direction | Same factory builds plugins from a PRD; the eval harness is the green command |
@@ -80,6 +83,15 @@ Everything in [horizon](reference/horizon.md) stays unbuilt until the interactiv
 factory is trusted. Open items live per-node in each doc's "Open questions" —
 this file carries none.
 
+**Grill queue** (decided 2026-07-16): the critical path is
+[spec-and-ticket-layer](reference/spec-and-ticket-layer.md) →
+[pipeline-stages](reference/pipeline-stages.md) — grill in that order first.
+Then [never-ask-twice](reference/never-ask-twice.md) +
+[self-improvement-loops](reference/self-improvement-loops.md) (can run in
+parallel with pipeline build; NAT's formalization ADR is independent), then
+[horizon](reference/horizon.md). The remaining nodes' open questions are
+implementation-time calls, not grill material.
+
 ## Sources
 
 - Vault: `matt-pocock-skills-v1-1-changes.md`, `agentic-sdlc-ai-developer-workflow-taxonomy.md`
diff --git a/plugins/os-sdlc/reference/pipeline-observability.md b/plugins/os-sdlc/reference/pipeline-observability.md
new file mode 100644
index 0000000..2ce64b2
--- /dev/null
+++ b/plugins/os-sdlc/reference/pipeline-observability.md
@@ -0,0 +1,46 @@
+# pipeline observability
+
+_Status: direction — as of 2026-07-16_
+_Connects to: [pipeline-stages](pipeline-stages.md), [self-improvement-loops](self-improvement-loops.md), [never-ask-twice](never-ask-twice.md), [overview](../OVERVIEW.md)_
+
+## Purpose
+
+Defines what a pipeline run writes down — its exhaust — where it goes, and how long it
+lives. The self-improvement loops and the never-ask-twice promotion mechanism are only as
+good as this exhaust; it was implicit in the original design and is made explicit here.
+Load this before designing any run report, audit input, or blocked-stage log.
+
+## Design
+
+- **Every run emits exhaust**: stages executed, actor per stage, gate outcomes (red/green,
+  iterations consumed), blocked-stage reports (the questions the pipeline could not
+  auto-resolve — [never-ask-twice](never-ask-twice.md)'s raw input), and a human-facing
+  summary. This is the feed the loops in
+  [self-improvement-loops](self-improvement-loops.md) consume.
+- **Every exhaust artifact has a predefined lifespan** (composes with os-doc-hygiene):
+  run-scoped scratch dies with the worktree; run reports persist on the ticket; anything
+  durable gets *promoted* to its proper home (ADR, vault note, issue comment) rather than
+  accumulating as clutter. No unbounded log directories.
+- **Copy → tag → audit pattern** (deterministic where possible, per the three-actor test):
+  the write side is a hook (code actor), the review side is the periodic audit (agent
+  actor). Reference case — ADRs: the ADR-writing skill becomes a named agent whose hook
+  copies every new ADR into the vault at write time; the ADR audit then reads only *virgin*
+  (untagged) vault copies, keeps the durable ones, revises for clarity where needed, and
+  tags them audited — the next round checks only new virgin ADRs. The same pattern
+  generalizes to other streams (blocked-stage reports, run reports): mechanical capture at
+  write time, audit consumes the untagged backlog, tagging marks progress.
+
+## Open questions
+
+- Run-report format and home: an issue comment on the ticket (durable, in-tracker, visible
+  at merge review) vs. a file artifact — leaning issue comment.
+- Lifespan policy per artifact class (scratch / run report / blocked-stage report) and how
+  os-doc-hygiene enforces it.
+- Which exhaust stream gets the copy-tag-audit hook first (ADRs are the obvious pilot).
+
+## Sources
+
+- 2026-07-16 design session — user-identified gap ("I assumed this mechanism was baked into
+  the concept") + the ADR copy-tag-audit proposal
+- os-doc-hygiene plugin (lifespan enforcement)
+- ADR-0037
diff --git a/plugins/os-sdlc/reference/pipeline-stages.md b/plugins/os-sdlc/reference/pipeline-stages.md
index 241d713..e05131c 100644
--- a/plugins/os-sdlc/reference/pipeline-stages.md
+++ b/plugins/os-sdlc/reference/pipeline-stages.md
@@ -1,7 +1,7 @@
 # pipeline stages
 
 _Status: direction — as of 2026-07-16_
-_Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [worktree-parallelism](worktree-parallelism.md), [overview](../OVERVIEW.md)_
+_Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [worktree-parallelism](worktree-parallelism.md), [pipeline-observability](pipeline-observability.md), [overview](../OVERVIEW.md)_
 
 ## Purpose
 
@@ -29,7 +29,8 @@ Manually triggered by `/implement <ticket>`. Stages, in order:
    aligns with both tests and spec. Order matters — misaligned tests invalidate a "code passes
    tests" result.
 7. **Cleanup & report** (agent/code mix) — trims scratch artifacts, produces a summary for the
-   human.
+   human. What gets written, where, and for how long is defined in
+   [pipeline-observability](pipeline-observability.md).
 8. **Human merge gate** — v1 has no automated merge; see
    [worktree-parallelism](worktree-parallelism.md).
 
diff --git a/plugins/os-sdlc/reference/self-improvement-loops.md b/plugins/os-sdlc/reference/self-improvement-loops.md
index 14ee7ca..eabc262 100644
--- a/plugins/os-sdlc/reference/self-improvement-loops.md
+++ b/plugins/os-sdlc/reference/self-improvement-loops.md
@@ -1,7 +1,7 @@
 # self improvement loops
 
 _Status: direction — as of 2026-07-16_
-_Connects to: [never-ask-twice](never-ask-twice.md), [plugin-factory](plugin-factory.md), [overview](../OVERVIEW.md)_
+_Connects to: [never-ask-twice](never-ask-twice.md), [plugin-factory](plugin-factory.md), [pipeline-observability](pipeline-observability.md), [overview](../OVERVIEW.md)_
 
 ## Purpose
 
@@ -29,7 +29,11 @@ audit's own cost/latency never blocks a ticket.
   scope-classification judgment calls that slipped through at mint time. A wrong mint-time
   call is treated as a delay, not a loss — anything missed gets caught in the next ADR
   audit, so the loop is self-correcting rather than requiring the mint-time call to be
-  perfect.
+  perfect. Proposed mechanics (2026-07-16, user): the copy-tag-audit pattern from
+  [pipeline-observability](pipeline-observability.md) — a hook copies every new ADR into
+  the vault at write time; the audit reads only *virgin* (untagged) copies, keeps the
+  durable ones, revises for clarity, tags them audited; the next round checks only new
+  virgin ADRs. This makes the capture side deterministic and the audit's workload bounded.
 - **c. Eval harnesses** (exists — autoresearch pattern, already running for os-vault,
   os-adr, os-context) — catches capability regression. Functions as "the AI version of TDD"
   for plugin-type projects: a plugin's eval suite is the thing that must stay green across
@@ -47,8 +51,9 @@ Together, these four loops are:
 
 ## Open questions
 
-- ADR-audit criteria: what specifically counts as "stale," how missed promotions are
-  detected mechanically (diffing local ADRs against vault convention notes?), and cadence.
+- ADR-audit criteria: what specifically counts as "stale" and "durable," and cadence.
+  (Mechanical detection is now sketched via the copy-tag-audit pattern above — remaining
+  question is the judgment rubric the audit applies to each virgin ADR.)
 - Whether ADR audits live in os-context (alongside the existing session-audit skill) or in
   os-adr (alongside `find`/`create`/`migrate`) — an ownership question, not yet settled.
 - Whether (a)-(d) should share a common audit-report format so
diff --git a/plugins/os-sdlc/reference/spec-and-ticket-layer.md b/plugins/os-sdlc/reference/spec-and-ticket-layer.md
index ed74d35..7cb8fc7 100644
--- a/plugins/os-sdlc/reference/spec-and-ticket-layer.md
+++ b/plugins/os-sdlc/reference/spec-and-ticket-layer.md
@@ -26,8 +26,9 @@ issue-tracker state for os-sdlc.
   - **to-spec** — publishes the sharpened plan to the issue tracker as a spec-bearing issue
     (or epic-equivalent) — the durable artifact other stages read from.
   - **to-tickets** — decomposes the spec into feature-specific, independently-implementable
-    increments, each its own issue, tracer-bullet style (same shape as the existing
-    `to-issues` skill, but scoped to a published spec rather than an ad hoc plan).
+    increments, each its own issue, tracer-bullet style. Confirmed 2026-07-16: this is
+    Pocock's v1.1 *rename* of `to-issues` ("a spec defines the destination; tickets are the
+    journey"), not a sibling — the leftover `to-issues` skill was removed the same day.
   - **`/implement`** — consumes exactly one ticket into the [pipeline-stages](pipeline-stages.md)
     pipeline. One ticket in, one worktree/branch out (see
     [worktree-parallelism](worktree-parallelism.md)).
@@ -46,8 +47,6 @@ issue-tracker state for os-sdlc.
   (DeltaRefinery decomposed work into explicit levels; Pocock's wayfinder is looser).
 - Concrete spec issue template (sections, required fields) and ticket issue template
   (acceptance criteria shape, tracer-bullet slice size).
-- Whether `to-tickets` reuses the existing `to-issues` skill directly or needs its own
-  spec-aware variant.
 
 ## Sources
 
@@ -55,5 +54,5 @@ issue-tracker state for os-sdlc.
 - ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
 - `plugins/os-sdlc/OVERVIEW.md`
 - SecondBrain vault: `matt-pocock-skills-v1-1-changes.md`
-- `plugins/os-backlog/` (tracker key, `issue-create`/`issues` CLI, `to-issues` skill)
+- `plugins/os-backlog/` (tracker key, `issue-create`/`issues` CLI)
 - 2026-07-16 design session (this doc's origin)

From 5c18ba696f71f19497e0fa5cfb6c170f4d6ea09d Mon Sep 17 00:00:00 2001
From: jared <jared@swansoncloud.com>
Date: Thu, 16 Jul 2026 16:18:28 -0400
Subject: [PATCH 3/4] os-sdlc: reviewer is a named agent with hook-assembled
 context packet

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VgG2g9ooqbnBiZYGAonGYG
---
 plugins/os-sdlc/reference/pipeline-stages.md | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/plugins/os-sdlc/reference/pipeline-stages.md b/plugins/os-sdlc/reference/pipeline-stages.md
index e05131c..3f1443e 100644
--- a/plugins/os-sdlc/reference/pipeline-stages.md
+++ b/plugins/os-sdlc/reference/pipeline-stages.md
@@ -25,9 +25,18 @@ Manually triggered by `/implement <ticket>`. Stages, in order:
 5. **Green-assert gate** (deterministic hook) — suite + lint must pass. Failures are
    auto-fed back into the same programmer's next turn; a max-iterations cap escalates to the
    human rather than looping forever.
-6. **Reviewer agent** — two ordered checks: first tests align with the spec/ticket, then code
-   aligns with both tests and spec. Order matters — misaligned tests invalidate a "code passes
-   tests" result.
+6. **Reviewer agent** — a *named agent* (not a skill), so its tool surface is minimal and
+   its context never leaks into the orchestrator's (see
+   [agent-design-principles](agent-design-principles.md)). It reads only a hook-assembled
+   context packet — test status from the green-assert gate (passing, unless max-iterations
+   escalated), a mechanically generated diff, and the spec/ticket — gathered into one
+   document by a code-actor hook before the agent is invoked; the reviewer runs nothing
+   itself. Two ordered checks: first tests align with the spec/ticket, then code aligns
+   with both tests and spec. Order matters — misaligned tests invalidate a "code passes
+   tests" result. ADR-0037's `/os-sdlc:review` (standards-conformance + spec-fidelity +
+   Fowler refactor smells) is satisfied by this same agent; if standalone review of an
+   arbitrary diff is wanted outside a pipeline run, a thin skill wrapper dispatches the
+   agent with a hand-assembled packet — one reviewer, two entry points.
 7. **Cleanup & report** (agent/code mix) — trims scratch artifacts, produces a summary for the
    human. What gets written, where, and for how long is defined in
    [pipeline-observability](pipeline-observability.md).

From 23fa2fbdbd8a00a633ca4bf6c354c0b44f907e83 Mon Sep 17 00:00:00 2001
From: jared <jared@swansoncloud.com>
Date: Thu, 16 Jul 2026 16:23:45 -0400
Subject: [PATCH 4/4] os-sdlc: /implement is a skill-as-orchestrator over the
 agent pipeline

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VgG2g9ooqbnBiZYGAonGYG
---
 plugins/os-sdlc/reference/pipeline-stages.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/plugins/os-sdlc/reference/pipeline-stages.md b/plugins/os-sdlc/reference/pipeline-stages.md
index 3f1443e..10e21c6 100644
--- a/plugins/os-sdlc/reference/pipeline-stages.md
+++ b/plugins/os-sdlc/reference/pipeline-stages.md
@@ -64,8 +64,11 @@ per-example granularity was a DeltaRefinery downside being deliberately dropped.
   cc-os naming convention before anything ships.
 - Whether a cheap tests-vs-spec review should run *before* the programmer stage in later
   versions, to catch misaligned tests before paying for implementation.
-- Whether Pocock's `implement` skill is adopted as a thin router over these stages, or
-  redesigned from scratch.
+- Shape settled 2026-07-16: `/implement` (or our custom successor) is a *skill acting as
+  orchestrator* — slash commands are the user-invocable layer, agents aren't. The skill
+  triggers the agent pipeline, watches over it, adjusts to surprises, and keeps the user
+  in the loop on progress/results. Remaining question: how much of Pocock's `implement`
+  wording survives vs. a from-scratch orchestrator prompt.
 
 ## Sources