@hecer/yoke 1.5.1 → 1.6.1

package/docs/superpowers/plans/2026-08-20-automatic-ui-design-gate.md

@@ -0,0 +1,59 @@
+# Automatic UI Design Gate Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan.
+
+**Goal:** Automatically run Yoke's existing design scanner inside configured UI-project loops while preserving current behavior for non-UI and already-configured projects.
+
+**Architecture:** Add one deterministic local detector, one default-preserving config section, and a small verifier adapter over the existing scanner. Thread that verifier through the serial and parallel loop gate contracts in the same position and evidence model as existing mechanical gates.
+
+**Tech Stack:** TypeScript, Zod, Vitest, existing design scanner and loop abstractions.
+
+---
+
+## Task 1: Detect UI projects with explained evidence
+
+**Files:** `src/retrofit/ui-detect.ts`, `src/retrofit/detect.ts`, `tests/retrofit/ui-detect.test.ts`, `tests/retrofit/detect.test.ts`
+
+1. Add failing tests for supported dependencies, `.tsx`, `.jsx`, `.vue`, `.svelte`, `.astro`, an existing smoke-flow config, non-UI TypeScript, and ignored dependency/generated/fixture/Yoke directories.
+2. Implement bounded traversal of normal source roots and package manifests. Return `{ detected, signals }` with stable, human-readable signals.
+3. Attach UI evidence to Retrofit detection without changing existing agent detection semantics.
+4. Run the detector tests.
+
+## Task 2: Add default-preserving design configuration
+
+**Files:** `src/retrofit/config.ts`, `src/retrofit/command.ts`, `tests/retrofit/config.test.ts`, `tests/retrofit/integration.test.ts`
+
+1. Add failing schema tests for `mode: off|auto|on`, positive integer `max`, invalid values, and omitted design config.
+2. Add optional `design` to the config type and schema. Do not place it in the universal legacy default.
+3. During new/retrofit setup, write `{ mode: 'auto', max: 4 }` only when UI detection succeeds and no user design choice exists.
+4. Include the detector's evidence in setup output and test that an existing `off`, `on`, or custom budget is preserved.
+5. Run config and Retrofit integration tests.
+
+## Task 3: Adapt design scan results to a mechanical gate
+
+**Files:** `src/scan/gate.ts`, `src/scan/design.ts`, `src/cli.ts`, `tests/scan/gate.test.ts`, `tests/scan/design.test.ts`
+
+1. Add failing tests for pass/fail at a configured budget, stable finding names, bounded preview text, and a full artifact path for overflow details.
+2. Extract only shared result formatting from the standalone command; do not change its public output or scanner weights.
+3. Implement a verifier adapter that runs `scanDir`, returns the existing verify-result contract, and writes full findings through the existing artifact helper.
+4. Run scan tests and a CLI design-scan regression test.
+
+## Task 4: Thread the gate through serial and parallel loops
+
+**Files:** `src/loop/run-command.ts`, `src/loop/loop.ts`, `src/loop/worker-contracts.ts`, `src/loop/worker.ts`, `src/loop/parallel-command.ts`, `src/loop/parallel.ts`, `src/loop/dispatcher.ts`, `src/loop/parallel-adapters.ts`, `src/output/types.ts`, matching `tests/loop/*.test.ts`
+
+1. Add failing serial tests showing order `criteria -> verify -> design -> perf -> audit` and proving omitted or `off` design leaves the old call sequence unchanged.
+2. Add failing worker and dispatcher tests for design evidence, stage-specific failure, retry/quality-rerun behavior, and cancellation.
+3. Extend gate stage unions, callbacks, evidence, and output phases with `design`; make the verifier optional throughout.
+4. Construct the verifier in `run-command` for `on`, for detected `auto`, and never for `off` or missing config.
+5. Run all loop tests, then `rtk npm run lint`.
+
+## Task 5: Verify setup-to-loop behavior
+
+**Files:** `tests/retrofit/integration.test.ts`, `tests/loop/run-command.test.ts`
+
+1. Add an integration fixture for a detected UI project and one for a non-UI project.
+2. Prove Retrofit writes auto config only to the UI fixture and the next loop run selects the design verifier only there.
+3. Prove `mode: on` overrides failed detection and `mode: off` overrides successful detection.
+4. Run `rtk npm exec -- vitest run tests/retrofit tests/scan tests/loop`.
+

package/docs/superpowers/plans/2026-08-20-capability-skills-and-context.md

@@ -0,0 +1,51 @@
+# Capability Skills and Context Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan.
+
+**Goal:** Add the prose, domain, codebase-design, merge-resolution, and agent-writing capabilities identified in the source review, with durable terminology context and clear attribution.
+
+**Architecture:** Keep capabilities as independent Canon packages selected through the manifest. Use resource files for evaluation material, keep `.yoke/context` as the durable project source of truth, and connect prose review to documentation workflows without making style a release gate.
+
+**Tech Stack:** Markdown skill packages, TypeScript context loader, YAML manifest, Vitest, provenance audit tools.
+
+---
+
+## Task 1: Import and adapt `no-ai-slop`
+
+**Files:** `canon/skills/no-ai-slop/SKILL.md`, `canon/skills/no-ai-slop/eval.md`, `canon/ATTRIBUTION.md`, `canon/manifest.yaml`, `tests/canon/real-canon.test.ts`
+
+1. Run a read-only provenance audit on the upstream package and record unknown signals as unknown.
+2. Add failing real-Canon assertions for the package, its `eval.md` reference, auto invocation, and Peter Yang/MIT attribution.
+3. Import the upstream workflow and evaluation checklist. Adapt only the trigger wording, Yoke paths, and the precise-domain-term exception; preserve Edit and Detect modes and prohibit authorship guesses.
+4. Run the package tests and a second read-only provenance audit on the local package.
+
+## Task 2: Add the four complementary capabilities
+
+**Files:** `canon/skills/domain-modeling/SKILL.md`, `canon/skills/codebase-design/SKILL.md`, `canon/skills/resolving-merge-conflicts/SKILL.md`, `canon/skills/writing-for-agents/SKILL.md`, `canon/ATTRIBUTION.md`, `canon/manifest.yaml`, `tests/canon/real-canon.test.ts`
+
+1. Add failing assertions for all four skill ids, frontmatter, auto invocation, and source attribution where material is adapted from Matt Pocock's repository.
+2. Write `domain-modeling` around terminology discovery, scenario checks, code comparison, glossary updates, and the existing ADR threshold.
+3. Write `codebase-design` around deep modules, small interfaces, real seams, public-interface tests, and local change.
+4. Write `resolving-merge-conflicts` around current-operation discovery, commit/spec evidence, preservation of both compatible intents, scoped checks, and no implicit abort.
+5. Write `writing-for-agents` around observable outcomes, concrete paths and commands, bounded context, explicit triggers, and deduplicated durable instructions.
+6. Validate Canon and run the real-Canon tests.
+
+## Task 3: Add glossary-aware project context
+
+**Files:** `canon/context/GLOSSARY.md`, `src/retrofit/context-actions.ts`, `src/context/context.ts`, `src/context/command.ts`, `tests/retrofit/context-actions.test.ts`, `tests/context/context.test.ts`, `tests/context/command.test.ts`
+
+1. Add failing tests that Retrofit introduces `GLOSSARY.md` with `ifAbsent`, existing context is unchanged, and `CONTEXT-MAP.md` is loaded only when present.
+2. Add a concise glossary template for canonical terms, aliases, rejected terms, and concrete examples.
+3. Extend context loading and formatted prompt context with bounded glossary content and optional bounded context-map content.
+4. Extend context status output so required glossary state and optional context-map state are distinguishable.
+5. Run the context and context-action tests.
+
+## Task 4: Connect prose quality to documentation workflows
+
+**Files:** `canon/skills/document-release/SKILL.md`, `canon/roles/docs.yaml`, `CONTRIBUTING.md`, `tests/canon/real-canon.test.ts`
+
+1. Add failing assertions that documentation release guidance invokes `no-ai-slop` evaluation without turning it into a mechanical pass/fail gate.
+2. Update the skill and docs role to request minimal voice-preserving edits and explicit reporting of observed patterns.
+3. Use the new skill in Detect mode on changed prose, then Edit mode only where a listed pattern is actually present.
+4. Run Canon validation and provenance-audit the changed documentation set.
+

package/docs/superpowers/plans/2026-08-20-complete-skill-packages-and-invocation.md

@@ -0,0 +1,59 @@
+# Complete Skill Packages and Invocation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan.
+
+**Goal:** Install every Canon skill as a complete, safe resource package and preserve explicit automatic or manual invocation intent across Claude, Codex, and Gemini.
+
+**Architecture:** Extend the parsed Canon manifest with a defaulted invocation policy, enumerate package files once behind a fail-closed boundary, and make every provider planner consume the same normalized package model. Extend Retrofit actions only enough to preserve byte content and executable intent; provider-specific policy remains generated output, not Canon source.
+
+**Tech Stack:** TypeScript, Zod, YAML, Vitest, Node filesystem APIs.
+
+---
+
+## Task 1: Add invocation policy to the manifest contract
+
+**Files:** `src/canon/manifest.ts`, `tests/canon/manifest.test.ts`, `tests/canon/real-canon.test.ts`, `canon/manifest.yaml`
+
+1. Add failing tests proving omitted `invocation` parses as `auto`, `manual` parses, and unknown values fail.
+2. Add `InvocationSchema = z.enum(['auto', 'manual'])` and default `invocation` to `auto` on each skill entry.
+3. Add explicit `invocation` values to every real Canon skill and assert the real manifest has no implicit entries.
+4. Run `rtk npm exec -- vitest run tests/canon/manifest.test.ts tests/canon/real-canon.test.ts`.
+
+## Task 2: Enumerate and validate complete skill packages
+
+**Files:** `src/canon/skill-package.ts`, `src/canon/validate.ts`, `tests/canon/skill-package.test.ts`, `tests/canon/validate.test.ts`
+
+1. Write failing tests for stable relative-path ordering, nested Markdown and binary resources, executable metadata, symlink rejection, path escape rejection, unsupported node types, duplicate normalized targets, and missing relative Markdown references.
+2. Implement `enumerateSkillPackage(canonDir, skill)` returning immutable records with `relativePath`, `content: Buffer`, and `executable`.
+3. Normalize separators to `/`, resolve every candidate beneath the skill root, use `lstat` to reject links and special files, and never follow a path outside the root.
+4. Extend Canon validation to enumerate each package and validate local relative Markdown links without fetching HTTP links or validating anchors.
+5. Run `rtk npm exec -- vitest run tests/canon/skill-package.test.ts tests/canon/validate.test.ts` and `rtk npm run yoke -- validate canon`.
+
+## Task 3: Let Retrofit actions preserve package bytes and executable intent
+
+**Files:** `src/retrofit/plan.ts`, `src/retrofit/apply.ts`, `tests/retrofit/apply.test.ts`
+
+1. Add failing tests for a binary action, unchanged binary content, and executable-mode preservation where the platform supports it.
+2. Change write actions to accept `string | Uint8Array` and optional `executable`; retain string-only JSON merge and carry-preserved behavior with explicit guards.
+3. Compare and write buffers without UTF-8 conversion. Apply executable bits on non-Windows after the atomic content write.
+4. Run `rtk npm exec -- vitest run tests/retrofit/apply.test.ts`.
+
+## Task 4: Generate provider-specific skill outputs
+
+**Files:** `src/retrofit/skill-actions.ts`, `src/retrofit/planners/claude.ts`, `src/retrofit/planners/codex.ts`, `src/retrofit/planners/gemini.ts`, `tests/retrofit/planners/claude.test.ts`, `tests/retrofit/planners/codex.test.ts`, `tests/retrofit/planners/gemini.test.ts`
+
+1. Add fixtures containing nested Markdown and a binary resource, plus one manual skill.
+2. Add failing Claude tests for complete package copying and `disable-model-invocation: true` only on generated manual `SKILL.md` frontmatter.
+3. Add failing Codex tests for complete copying and generated or merged `agents/openai.yaml` with `policy.allow_implicit_invocation` matching the manifest.
+4. Add failing Gemini tests for copied resources, unchanged command generation, manual command-only behavior, and a compact auto-skill index that excludes manual skills.
+5. Implement shared action generation from the package enumerator. Ensure generated policy files cannot silently conflict with a Canon-provided file.
+6. Run all three planner test files.
+
+## Task 5: Prove backward compatibility end to end
+
+**Files:** `tests/retrofit/integration.test.ts`, `tests/canon/real-canon.test.ts`
+
+1. Add an integration test that an existing one-file skill installs byte-for-byte as before.
+2. Add an integration test that one resource-bearing skill installs its referenced resource for all three agents.
+3. Run `rtk npm exec -- vitest run tests/canon tests/retrofit` and `rtk npm run lint`.
+

package/docs/superpowers/plans/2026-08-20-windows-reliability-and-release.md

@@ -0,0 +1,67 @@
+# Windows Reliability and 1.6.0 Release Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan.
+
+**Goal:** Make provider-process termination and cleanup reliable under Windows suite load, then document, package, and publish the verified 1.6.0 release.
+
+**Architecture:** Preserve scoped PID ownership and fail-closed records. Treat `taskkill` success as a termination request, then confirm that the recorded PID is gone with a bounded wait before removing ownership evidence or allowing cleanup. Release only one commit through the documented GitHub and npm channels.
+
+**Tech Stack:** Node child processes, Windows `taskkill`, Vitest, npm, GitHub CLI, Git.
+
+---
+
+## Task 1: Reproduce and pin the Windows race
+
+**Files:** `tests/agents/provider-process.test.ts`, `tests/agents/provider-process-record-failure.test.ts`, `tests/loop/watchdog.test.ts`
+
+1. Record the isolated baseline: both provider-process files pass together, establishing that the failure depends on suite load rather than basic semantics.
+2. Run the affected files repeatedly and run the full suite with verbose failure output. Capture whether time is spent before `close`, during `taskkill`, or in temporary-directory removal.
+3. Add a failing watchdog unit test where `taskkill` returns zero while the injected liveness probe remains true for two polls; termination must not yet be confirmed.
+4. Add a failing provider test that completion after cancellation leaves neither a live recorded PID nor a removable-directory race.
+
+## Task 2: Confirm termination before releasing ownership
+
+**Files:** `src/loop/watchdog.ts`, `src/agents/process.ts`, `tests/loop/watchdog.test.ts`, `tests/agents/provider-process.test.ts`
+
+1. Extend `killProcessTreeForCleanup` on Windows with an injectable liveness probe and bounded 25 ms polling after successful `taskkill`.
+2. Return `true` only when the PID is confirmed absent; return `false` when the bounded confirmation expires. Keep POSIX process-group behavior unchanged.
+3. In `startProviderProcess`, preserve the ownership record whenever confirmation is false; remove it only on natural close without requested termination or confirmed termination.
+4. Ensure stdin is closed before the first termination request and force escalation remains bounded and PID-scoped.
+5. Run watchdog and provider-process tests ten times. Do not add a process-name kill or unconditional record deletion.
+
+## Task 3: Run the complete quality ladder
+
+**Files:** all changed source and tests
+
+1. Run focused Canon, Retrofit, context, scan, loop, and agent suites.
+2. Run `rtk npm run lint` and `rtk npm run yoke -- validate canon`.
+3. Run `rtk npm test` at least twice on Windows and check for remaining `yoke-provider-*` temporary directories or owned provider processes after each run.
+4. Fix only attributable failures and repeat the narrowest failing test before returning to the full suite.
+
+## Task 4: Update release documentation with the new prose skills
+
+**Files:** `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `docs/PUBLISHING.md`
+
+1. Update README behavior, examples, skill count/table, complete-package installation, invocation policy, `unslop-ui` versus `no-ai-slop`, UI auto detection, and glossary context.
+2. Document package resources and invocation-policy authoring in CONTRIBUTING; add a 1.6.0 changelog entry and only adjust publishing guidance when the actual workflow changed.
+3. Run `no-ai-slop` Detect mode over changed prose, make only supported voice-preserving edits, then run the global read-only provenance audit.
+4. Run `rtk npm run docs:update` and `rtk npm run docs:check`.
+
+## Task 5: Synchronize and verify 1.6.0 metadata
+
+**Files:** `package.json`, `package-lock.json`, `canon/manifest.yaml`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, `gemini-extension.json`, generated README metadata
+
+1. Set every documented release field to `1.6.0` and regenerate lock and documentation metadata through project scripts.
+2. Run `rtk npm run prepublishOnly` and inspect `npm pack --dry-run` output for required skill resources, especially `no-ai-slop/eval.md`.
+3. Review `rtk git diff --check`, `rtk git status`, and the release diff; exclude `.omo/` and unrelated user files.
+4. Commit the verified implementation and metadata on `main`.
+
+## Task 6: Publish and verify both channels
+
+**Files:** no further source edits after the release commit
+
+1. Push `main`, create annotated tag `v1.6.0` at the verified commit, and push the tag.
+2. Create the GitHub Release from that tag and verify its URL and commit.
+3. Publish `@hecer/yoke@1.6.0` to npm. If npm alone requires an operator OTP, stop that channel and report it precisely.
+4. Verify `git ls-remote`, the GitHub Release, `npm view @hecer/yoke version`, and package contents all resolve to 1.6.0.
+

package/docs/superpowers/specs/2026-06-28-baustein-e-context-layer-design.md

@@ -1,146 +1,146 @@
-# Baustein E — Context Layer (durable cross-session context)
-
-**Status:** Design approved 2026-06-28
-**Component:** Yoke (🐂)
-**Relates to:** [[harness-project-goal]], [[harness-stack-decisions]], [[harness-loop-technique]]
-
-## Problem & Goal
-
-The dev.to article ("A Claude Code Skills Stack") frames a three-layer division of labor:
-**gstack decides → GSD stabilizes context → Superpowers executes.** Yoke today has the
-Decision layer (ported gstack roles) and a strong Execution layer (superpowers methodology +
-the Ralph loop), but it never built the **Context layer** — GSD's actual contribution:
-durable, cross-session artifacts that prevent specification drift.
-
-Concretely, the loop's [`buildClaudePrompt`](../../../src/loop/runner.ts) injects **only the
-current story + its acceptance criteria**. Every fresh-context iteration starts blind to the
-project's overall goal, the decisions already made, and the gotchas already learned. Over many
-iterations this is exactly where drift leaks in. The user's own auto-memory does this job by
-hand; the harness should give its users the same thing.
-
-**Goal:** a durable Context layer — three markdown files under `.yoke/context/` that the loop
-**reads before each iteration** and **writes decisions back to**, plus a skill so interactive
-(non-loop) sessions honor the same files. This closes the spec-drift hole and completes the
-third leg of the article's model.
-
-## Key Decisions (locked)
-
-| Decision | Choice |
-|---|---|
-| Scope | Loop **and** interactive sessions (retrofit scaffolds for all 3 agents) |
-| Write-back | **Hybrid**: loop deterministically auto-logs decisions; agents enrich `DECISIONS`/`KNOWLEDGE` via the skill |
-| Files location | `.yoke/context/` (agent-agnostic shared state, like `.yoke/prd.yaml`) |
-| Config | None new — injection auto-on when files present; prompt bound is a constant |
-| Backwards-compat | No `.yoke/context/` → loop prompt is byte-identical to today |
-| Out of scope | Routing/priority fix (separate Baustein F), structured decision schema, cross-file linking |
-
-## The three files — `.yoke/context/`
-
-| File | Role | Writer |
-|------|------|--------|
-| `PROJECT.md` | North star: goal, constraints, **non-goals**, success criteria | Human/brainstorm authored; retrofit scaffolds a template. Read-only input. |
-| `DECISIONS.md` | Append-only ADR ledger | Loop auto-appends per completed+verified story; agents append in interactive work. |
-| `KNOWLEDGE.md` | Gotchas, conventions, reusable learnings | Agent/human maintained via the skill. |
-
-The files are plain markdown — no schema, no required structure beyond `DECISIONS.md`'s
-append format (so the loop can append unambiguously). Missing or partial files are valid:
-the layer degrades gracefully (an absent file contributes nothing to the prompt).
-
-## Architecture
-
-### New module — `src/context/context.ts`
-Pure and unit-testable, structured like `src/loop/prd.ts`:
-
-- `loadContext(dir): ProjectContext` — read the three files if present; missing → empty strings. Never throws on absence.
-- `formatForPrompt(ctx, maxChars): string` — render a "Project context" block, **tail-bounding** each file to `maxChars` (constant, ~2 KB) so a large ledger can't blow up the prompt. Returns `''` when all three are empty.
-- `appendDecision(dir, entry): { rollback: () => void }` — append a `DECISIONS.md` entry and return a rollback that restores the prior file content (captured before the write). Creates the file if absent.
-
-`ProjectContext = { project: string; decisions: string; knowledge: string }`.
-
-A decision entry is formatted as:
-```
-## <YYYY-MM-DD> — <story-id>: <title>
-<one-line summary>
-```
-The date comes from the Node runtime at loop time (the loop is normal Node, not a Workflow
-script — `Date` is available).
-
-### Loop read — `src/loop/runner.ts`
-`buildClaudePrompt(story, context?)` and `buildReviewPrompt(story, context?)` gain an optional
-pre-formatted `context` string. When present, a "Project context" section is inserted **ahead
-of** the story block. The reviewer gets the north star too (so it reviews against goals, not
-just acceptance criteria). When `context` is undefined/empty, the prompts are unchanged.
-
-The loop loads + formats context once per iteration (`.yoke/context/` resolved relative to
-`targetDir`) and threads it through the runner/review call.
-
-### Loop write-back — `src/loop/loop.ts`
-After verify (and optional review) passes, **before the commit**:
-
-1. `appendDecision(contextDir, { storyId, title, summary })` → keep the returned `rollback`.
-2. `savePrd(passes:true)`.
-3. `commitAll(...)` — now also stages `DECISIONS.md`, so the decision and the `passes:true`
-   flip land in the **same atomic commit**.
-
-If the commit throws, revert **both**: `savePrd(prior stories)` *and* `rollback()` for the
-decision file. This preserves the existing invariant — *`passes:true` never persists without a
-commit* — and extends it to the decision ledger (no orphan decision without a commit).
-
-In `--isolate` mode the append happens inside the worktree before the worktree commit, so
-`integrate` fast-forwards the decision back into the main tree along with the code.
-
-### Retrofit scaffolding — `src/retrofit/`
-A retrofit action writes `.yoke/context/{PROJECT,DECISIONS,KNOWLEDGE}.md` from
-`canon/context/*.md` templates **only if absent** (non-destructive + idempotent, the same rule
-as every other artifact). Agent-agnostic — one set under `.yoke/` serves claude/codex/gemini,
-so it is emitted once regardless of `--agent`. The report lists the scaffolded files.
-
-### Skill — `canon/skills/maintaining-context/SKILL.md`
-Agent-facing, flows to all three agents via the existing planners + `manifest.yaml`:
-> Before substantial work, read `.yoke/context/PROJECT.md` for the north star and
-> `KNOWLEDGE.md` for known gotchas. When you make a non-obvious decision, append it to
-> `DECISIONS.md`. When you learn a reusable fact or gotcha, append it to `KNOWLEDGE.md`.
-
-This is what extends drift-protection from the loop to interactive sessions.
-
-### CLI — `src/cli.ts`
-- `yoke context init` — scaffold the three files standalone (idempotent, non-destructive).
-- `yoke context status` — show presence, byte sizes, and the last decision heading.
-
-## Data flow (loop iteration)
-
-```
-load PRD ─► pick story ─► load+format .yoke/context ─► runner(prompt + context)
-   ─► verify ─► [review] ─► appendDecision() ─► savePrd(passes:true) ─► commitAll(+DECISIONS.md)
-                                   └── on commit failure: rollback() + savePrd(prior) ──► blocked
-```
-
-## Error handling
-
-- Missing/partial context files: treated as empty; no error, prompt simply omits that part.
-- Oversized files: tail-bounded to a constant per file; never unbounded.
-- `appendDecision` before commit + rollback on commit failure: no orphan decisions.
-- Isolate mode: decision written in the worktree, carried back only on successful integrate.
-- `yoke context init` over existing files: skips them (reports "exists"), never overwrites.
-
-## Testing (subagent-driven TDD, like A–D)
-
-**context.ts units:** load with all/none/partial files present; `formatForPrompt` bounding +
-empty-returns-`''`; `appendDecision` format correctness + rollback restores prior content +
-creates file when absent.
-
-**loop:** prompt includes the context block when `.yoke/context/` present; prompt unchanged
-when absent; decision appended on success; **not** appended on a blocked story; both PRD and
-decision reverted on commit failure; isolate path carries the decision back via integrate.
-
-**retrofit:** scaffolds the three files; idempotent on re-run; non-destructive over existing
-files; emitted once for `--agent=all`.
-
-**canon:** `maintaining-context` present in `manifest.yaml`; `yoke validate canon` stays green.
-
-## Non-goals (YAGNI)
-
-- No new config keys (injection is automatic; bound is a constant).
-- No structured/parsed decision schema — markdown append only.
-- No cross-file linking or decision superseding.
-- Routing/priority arbitration is **Baustein F**, not this spec.
+# Baustein E — Context Layer (durable cross-session context)
+
+**Status:** Design approved 2026-06-28
+**Component:** Yoke (🐂)
+**Relates to:** [[harness-project-goal]], [[harness-stack-decisions]], [[harness-loop-technique]]
+
+## Problem & Goal
+
+The dev.to article ("A Claude Code Skills Stack") frames a three-layer division of labor:
+**gstack decides → GSD stabilizes context → Superpowers executes.** Yoke today has the
+Decision layer (ported gstack roles) and a strong Execution layer (superpowers methodology +
+the Ralph loop), but it never built the **Context layer** — GSD's actual contribution:
+durable, cross-session artifacts that prevent specification drift.
+
+Concretely, the loop's [`buildClaudePrompt`](../../../src/loop/runner.ts) injects **only the
+current story + its acceptance criteria**. Every fresh-context iteration starts blind to the
+project's overall goal, the decisions already made, and the gotchas already learned. Over many
+iterations this is exactly where drift leaks in. The user's own auto-memory does this job by
+hand; the harness should give its users the same thing.
+
+**Goal:** a durable Context layer — three markdown files under `.yoke/context/` that the loop
+**reads before each iteration** and **writes decisions back to**, plus a skill so interactive
+(non-loop) sessions honor the same files. This closes the spec-drift hole and completes the
+third leg of the article's model.
+
+## Key Decisions (locked)
+
+| Decision | Choice |
+|---|---|
+| Scope | Loop **and** interactive sessions (retrofit scaffolds for all 3 agents) |
+| Write-back | **Hybrid**: loop deterministically auto-logs decisions; agents enrich `DECISIONS`/`KNOWLEDGE` via the skill |
+| Files location | `.yoke/context/` (agent-agnostic shared state, like `.yoke/prd.yaml`) |
+| Config | None new — injection auto-on when files present; prompt bound is a constant |
+| Backwards-compat | No `.yoke/context/` → loop prompt is byte-identical to today |
+| Out of scope | Routing/priority fix (separate Baustein F), structured decision schema, cross-file linking |
+
+## The three files — `.yoke/context/`
+
+| File | Role | Writer |
+|------|------|--------|
+| `PROJECT.md` | North star: goal, constraints, **non-goals**, success criteria | Human/brainstorm authored; retrofit scaffolds a template. Read-only input. |
+| `DECISIONS.md` | Append-only ADR ledger | Loop auto-appends per completed+verified story; agents append in interactive work. |
+| `KNOWLEDGE.md` | Gotchas, conventions, reusable learnings | Agent/human maintained via the skill. |
+
+The files are plain markdown — no schema, no required structure beyond `DECISIONS.md`'s
+append format (so the loop can append unambiguously). Missing or partial files are valid:
+the layer degrades gracefully (an absent file contributes nothing to the prompt).
+
+## Architecture
+
+### New module — `src/context/context.ts`
+Pure and unit-testable, structured like `src/loop/prd.ts`:
+
+- `loadContext(dir): ProjectContext` — read the three files if present; missing → empty strings. Never throws on absence.
+- `formatForPrompt(ctx, maxChars): string` — render a "Project context" block, **tail-bounding** each file to `maxChars` (constant, ~2 KB) so a large ledger can't blow up the prompt. Returns `''` when all three are empty.
+- `appendDecision(dir, entry): { rollback: () => void }` — append a `DECISIONS.md` entry and return a rollback that restores the prior file content (captured before the write). Creates the file if absent.
+
+`ProjectContext = { project: string; decisions: string; knowledge: string }`.
+
+A decision entry is formatted as:
+```
+## <YYYY-MM-DD> — <story-id>: <title>
+<one-line summary>
+```
+The date comes from the Node runtime at loop time (the loop is normal Node, not a Workflow
+script — `Date` is available).
+
+### Loop read — `src/loop/runner.ts`
+`buildClaudePrompt(story, context?)` and `buildReviewPrompt(story, context?)` gain an optional
+pre-formatted `context` string. When present, a "Project context" section is inserted **ahead
+of** the story block. The reviewer gets the north star too (so it reviews against goals, not
+just acceptance criteria). When `context` is undefined/empty, the prompts are unchanged.
+
+The loop loads + formats context once per iteration (`.yoke/context/` resolved relative to
+`targetDir`) and threads it through the runner/review call.
+
+### Loop write-back — `src/loop/loop.ts`
+After verify (and optional review) passes, **before the commit**:
+
+1. `appendDecision(contextDir, { storyId, title, summary })` → keep the returned `rollback`.
+2. `savePrd(passes:true)`.
+3. `commitAll(...)` — now also stages `DECISIONS.md`, so the decision and the `passes:true`
+   flip land in the **same atomic commit**.
+
+If the commit throws, revert **both**: `savePrd(prior stories)` *and* `rollback()` for the
+decision file. This preserves the existing invariant — *`passes:true` never persists without a
+commit* — and extends it to the decision ledger (no orphan decision without a commit).
+
+In `--isolate` mode the append happens inside the worktree before the worktree commit, so
+`integrate` fast-forwards the decision back into the main tree along with the code.
+
+### Retrofit scaffolding — `src/retrofit/`
+A retrofit action writes `.yoke/context/{PROJECT,DECISIONS,KNOWLEDGE}.md` from
+`canon/context/*.md` templates **only if absent** (non-destructive + idempotent, the same rule
+as every other artifact). Agent-agnostic — one set under `.yoke/` serves claude/codex/gemini,
+so it is emitted once regardless of `--agent`. The report lists the scaffolded files.
+
+### Skill — `canon/skills/maintaining-context/SKILL.md`
+Agent-facing, flows to all three agents via the existing planners + `manifest.yaml`:
+> Before substantial work, read `.yoke/context/PROJECT.md` for the north star and
+> `KNOWLEDGE.md` for known gotchas. When you make a non-obvious decision, append it to
+> `DECISIONS.md`. When you learn a reusable fact or gotcha, append it to `KNOWLEDGE.md`.
+
+This is what extends drift-protection from the loop to interactive sessions.
+
+### CLI — `src/cli.ts`
+- `yoke context init` — scaffold the three files standalone (idempotent, non-destructive).
+- `yoke context status` — show presence, byte sizes, and the last decision heading.
+
+## Data flow (loop iteration)
+
+```
+load PRD ─► pick story ─► load+format .yoke/context ─► runner(prompt + context)
+   ─► verify ─► [review] ─► appendDecision() ─► savePrd(passes:true) ─► commitAll(+DECISIONS.md)
+                                   └── on commit failure: rollback() + savePrd(prior) ──► blocked
+```
+
+## Error handling
+
+- Missing/partial context files: treated as empty; no error, prompt simply omits that part.
+- Oversized files: tail-bounded to a constant per file; never unbounded.
+- `appendDecision` before commit + rollback on commit failure: no orphan decisions.
+- Isolate mode: decision written in the worktree, carried back only on successful integrate.
+- `yoke context init` over existing files: skips them (reports "exists"), never overwrites.
+
+## Testing (subagent-driven TDD, like A–D)
+
+**context.ts units:** load with all/none/partial files present; `formatForPrompt` bounding +
+empty-returns-`''`; `appendDecision` format correctness + rollback restores prior content +
+creates file when absent.
+
+**loop:** prompt includes the context block when `.yoke/context/` present; prompt unchanged
+when absent; decision appended on success; **not** appended on a blocked story; both PRD and
+decision reverted on commit failure; isolate path carries the decision back via integrate.
+
+**retrofit:** scaffolds the three files; idempotent on re-run; non-destructive over existing
+files; emitted once for `--agent=all`.
+
+**canon:** `maintaining-context` present in `manifest.yaml`; `yoke validate canon` stays green.
+
+## Non-goals (YAGNI)
+
+- No new config keys (injection is automatic; bound is a constant).
+- No structured/parsed decision schema — markdown append only.
+- No cross-file linking or decision superseding.
+- Routing/priority arbitration is **Baustein F**, not this spec.