From c04b70d9dae632dbc87f41b2a065abfecc060e98 Mon Sep 17 00:00:00 2001 From: Garo Nazarian Date: Thu, 28 May 2026 11:52:11 +0700 Subject: [PATCH 1/2] docs: refocus ctx-docs on architecture checkpoints --- README.md | 2 +- plugins/ctx-codex/skills/ctx-docs/SKILL.md | 184 +++++++++++++-------- plugins/ctx/skills/ctx-docs/SKILL.md | 184 +++++++++++++-------- 3 files changed, 233 insertions(+), 137 deletions(-) diff --git a/README.md b/README.md index e870dab..fa4333b 100644 --- a/README.md +++ b/README.md @@ -122,7 +122,7 @@ Invoked with `/ctx:`. | `ctx-worktree` | Isolated git worktree with env files and deps, ready immediately. | | `ctx-kill-wt` | Teardown: kill port, remove worktree, delete branch. | | `ctx-open` | Open current directory in WebStorm. | -| `ctx-docs` | Aggregate completed work into epic documentation from specs, plans, parks, and git history. | +| `ctx-docs` | Create evidence-grounded architecture checkpoint docs with source-of-truth boundaries, verification, and Mermaid diagrams. | **Calibration** diff --git a/plugins/ctx-codex/skills/ctx-docs/SKILL.md b/plugins/ctx-codex/skills/ctx-docs/SKILL.md index 994ada9..5c648a0 100644 --- a/plugins/ctx-codex/skills/ctx-docs/SKILL.md +++ b/plugins/ctx-codex/skills/ctx-docs/SKILL.md @@ -1,124 +1,172 @@ --- name: ctx-docs description: > - Aggregate completed work into human-readable epic documentation. - Use when an epic or batch of issues is complete and you want a documentation - package. Triggers: "document this epic", "generate docs", "ctx-docs", - or after a batch of issues is shipped. + Create architecture checkpoint documentation for completed work. Use when the + user asks to document what was just built, document task or phase completion, + explain current migration state, capture source-of-truth boundaries, generate + docs with Mermaid diagrams, or run "ctx-docs". Produces evidence-grounded docs + from existing code, tests, migrations, and docs; not Linear-first. user-invocable: true allowed-tools: Bash, Read, Glob, Grep, Write --- -# ctx-docs — Epic Documentation Aggregation +# ctx-docs — Architecture Checkpoint Documentation -Synthesize completed work into structured, human-readable docs. Pulls from Linear, specs, plans, git history, and distilled memories. +Create a human-readable checkpoint doc for completed technical work. The goal is to preserve the current system boundary: what changed, why it matters, how it works, how to verify it, and what remains. + +Do not default to Linear or issue aggregation. Treat code, migrations, tests, and existing docs as the primary evidence. --- -## 1. Parse arguments +## 1. Define The Checkpoint + +Start by naming the completed slice in plain language: + +- `auth-identity-postgres-task-3` +- `billing-postgres-cutover` +- `playbook-runtime-v1` +- `company-list-postgres-phase-1` -Two entry points: +If the user did not give a title, derive one from the current branch, changed files, or the user's wording. -- **Epic mode:** `ctx-docs ` — queries Linear for the epic/project's issues -- **Issue mode:** `ctx-docs CTX-33 CTX-28 CTX-16` — user provides issue IDs directly +Use one doc unless the user asks for a full documentation package. Put the doc near existing related docs: -`` is always required — becomes the directory name and index title. +- feature docs under the local app docs directory when one exists, e.g. `src/coreties-app/docs/` +- project-wide docs under `docs/` +- diagrams under a colocated `diagrams//` directory when standalone Mermaid files are useful -If no issue IDs provided, use the Linear MCP (`mcp__plugin_linear_linear__list_issues`) to find issues belonging to the named epic/project. If Linear is unavailable or returns nothing, ask the user for issue IDs. +Do not commit unless the user explicitly asks. --- -## 2. Resolve issues +## 2. Gather Evidence -For each issue ID: -1. Fetch metadata from Linear via `mcp__plugin_linear_linear__get_issue` (title, description, status, labels) -2. If Linear unavailable, proceed with issue ID only — artifact discovery still works +Read narrowly, then expand only as needed. Prefer `rg` and targeted file reads. ---- +Minimum evidence set: -## 3. Gather artifacts +- existing docs related to the same feature, migration, or architecture area +- changed or referenced service files +- changed or referenced API entrypoints +- relevant migrations or schema definitions +- relevant tests +- current git status -For each issue, scan these locations: +For migration/source-of-truth work, explicitly find: -| Artifact | Location | Match strategy | -|----------|----------|---------------| -| Spec | `docs/specs/*.md` | Grep for issue ID in filename or content | -| Plan | `~/.codex/ctx-codex/plans/*.md` | Grep for issue ID in content | -| Park smart context | `docs/ctx/park.md` or git history | Branch name or issue ID reference | -| Git history | `git log --all --oneline --grep="{issue-id}"` | Commit messages | -| Linear metadata | From step 2 | Already fetched | -| Distilled memories | `~/.codex/ctx-codex/projects//memory/*.md` | Grep for issue ID in content or description | +- current source of truth +- previous source of truth +- write paths +- read paths +- fallbacks or dual-write behavior +- compatibility side effects +- verification commands +- remaining migration boundary -Not every issue will have every artifact. Work with what exists — skip missing artifacts gracefully. +If an older doc conflicts with current code, state the current code-backed boundary and mention the doc gap. --- -## 4. Generate docs - -Create `docs/ctx//` with: +## 3. Write The Doc -### `index.md` +Use this structure by default. Omit sections only when they genuinely do not apply. ````markdown -# - -**Generated:** {timestamp} -**Issues:** {N} completed -**Branches:** {list} +# -## Summary +This document summarizes and relates it to the existing docs. -{2-3 paragraph narrative synthesized from specs and plans} +## Status -## Issues +{What is now true. Include exact boundary language.} -| ID | Title | Complexity | Status | Branch | -|----|-------|-----------|--------|--------| -| ... | ... | ... | ... | ... | +## Why This Exists -## Key Decisions +{Problem before the change and why the new boundary is useful.} -{Aggregated from park smart context and spec "Why this approach" sections — only non-obvious decisions} +## Data Model -## Learnings +{Tables, contracts, schemas, durable ids, source keys, or state objects.} -{Aggregated from distilled memories related to these issues} -```` +## Runtime Write Path -### Per-issue docs (`.md`) +{Who writes what, in what order, and transaction/side-effect boundaries.} -````markdown -# — {title} +## Entry Points Updated -**Status:** {from Linear or git} -**Branch:** {from git} -**Spec:** {relative path to spec file, if found} -**Plan:** {relative path to plan file, if found} +| Path | Role | +| --- | --- | +| ... | ... | -## Design +## Reader Behavior -{From spec — problem, chosen approach, tradeoffs} +{What reads the new source first, what falls back, and what remains legacy.} -## Implementation +## What Changed About -{From plan — what was built, key files touched} +{Be explicit about what did not disappear. Name fallbacks and side effects.} -## Outcome +## Verification -{From git log — commits. From park — what actually happened} +{Focused tests, manual SQL/API checks, and behavioral checks.} -## Learnings +## Remaining Migration Boundary -{From park smart context + distilled memories} +{What is intentionally not done yet.} ```` -If a section has no data (e.g., no park file found), omit that section rather than writing "N/A". +### Boundary Language Rules + +- Do not write "migrated" without naming the migrated slice. +- Do not imply the whole product is on the new architecture unless the evidence proves it. +- Separate authentication source, app identity source, analytics source, billing source, and workflow state source when those are different. +- Name legacy fallbacks directly. +- Name compatibility side effects directly. +- Prefer "Postgres-owned for these updated paths" over broad claims like "Postgres-only." --- -## 5. Commit +## 4. Add Mermaid Diagrams + +For system-boundary docs, include both embedded Mermaid blocks in the markdown and standalone `.mmd` files when useful. + +Default diagrams: + +1. **Runtime flow**: request/event -> service -> transaction -> tables/side effects +2. **Entrypoint map**: routes/jobs/events -> shared service -> stores +3. **Reader boundary**: new source -> fallback -> behavior +4. **Before/after ownership**: old source vs new source when the migration is confusing -```bash -git add docs/ctx// -git commit -m "docs: epic documentation" +Use diagrams to clarify ownership and flow. Do not add decorative diagrams. + +Standalone file convention: + +```text +/diagrams//runtime-flow.mmd +/diagrams//entrypoints.mmd +/diagrams//reader-boundary.mmd +``` + +Keep Mermaid syntax simple: + +```mermaid +flowchart TD + A[External source] --> B[Shared service] + B --> C[New durable store] + B --> D[Legacy side effect] ``` + +--- + +## 5. Verify The Documentation + +Before reporting back: + +- confirm the doc file exists +- confirm any standalone `.mmd` files exist +- re-read the generated doc for overclaims +- check that links point to real local files where practical +- run a focused search for the main terms to ensure the doc names the actual code paths +- report verification commands run + +Do not claim tests pass unless you ran the tests. For docs-only changes, file existence, content checks, link sanity, and git status are usually the right verification. diff --git a/plugins/ctx/skills/ctx-docs/SKILL.md b/plugins/ctx/skills/ctx-docs/SKILL.md index cc6735f..64d2712 100644 --- a/plugins/ctx/skills/ctx-docs/SKILL.md +++ b/plugins/ctx/skills/ctx-docs/SKILL.md @@ -1,124 +1,172 @@ --- name: ctx-docs description: > - Aggregate completed work into human-readable epic documentation. - Use when an epic or batch of issues is complete and you want a documentation - package. Triggers: "document this epic", "generate docs", "ctx-docs", - or after a batch of issues is shipped. + Create architecture checkpoint documentation for completed work. Use when the + user asks to document what was just built, document task or phase completion, + explain current migration state, capture source-of-truth boundaries, generate + docs with Mermaid diagrams, or run "/ctx-docs". Produces evidence-grounded docs + from existing code, tests, migrations, and docs; not Linear-first. user-invocable: true allowed-tools: Bash, Read, Glob, Grep, Write --- -# /ctx-docs — Epic Documentation Aggregation +# /ctx-docs — Architecture Checkpoint Documentation -Synthesize completed work into structured, human-readable docs. Pulls from Linear, specs, plans, git history, and distilled memories. +Create a human-readable checkpoint doc for completed technical work. The goal is to preserve the current system boundary: what changed, why it matters, how it works, how to verify it, and what remains. + +Do not default to Linear or issue aggregation. Treat code, migrations, tests, and existing docs as the primary evidence. --- -## 1. Parse arguments +## 1. Define The Checkpoint + +Start by naming the completed slice in plain language: + +- `auth-identity-postgres-task-3` +- `billing-postgres-cutover` +- `playbook-runtime-v1` +- `company-list-postgres-phase-1` -Two entry points: +If the user did not give a title, derive one from the current branch, changed files, or the user's wording. -- **Epic mode:** `/ctx-docs ` — queries Linear for the epic/project's issues -- **Issue mode:** `/ctx-docs CTX-33 CTX-28 CTX-16` — user provides issue IDs directly +Use one doc unless the user asks for a full documentation package. Put the doc near existing related docs: -`` is always required — becomes the directory name and index title. +- feature docs under the local app docs directory when one exists, e.g. `src/coreties-app/docs/` +- project-wide docs under `docs/` +- diagrams under a colocated `diagrams//` directory when standalone Mermaid files are useful -If no issue IDs provided, use the Linear MCP (`mcp__plugin_linear_linear__list_issues`) to find issues belonging to the named epic/project. If Linear is unavailable or returns nothing, ask the user for issue IDs. +Do not commit unless the user explicitly asks. --- -## 2. Resolve issues +## 2. Gather Evidence -For each issue ID: -1. Fetch metadata from Linear via `mcp__plugin_linear_linear__get_issue` (title, description, status, labels) -2. If Linear unavailable, proceed with issue ID only — artifact discovery still works +Read narrowly, then expand only as needed. Prefer `rg` and targeted file reads. ---- +Minimum evidence set: -## 3. Gather artifacts +- existing docs related to the same feature, migration, or architecture area +- changed or referenced service files +- changed or referenced API entrypoints +- relevant migrations or schema definitions +- relevant tests +- current git status -For each issue, scan these locations: +For migration/source-of-truth work, explicitly find: -| Artifact | Location | Match strategy | -|----------|----------|---------------| -| Spec | `docs/specs/*.md` | Grep for issue ID in filename or content | -| Plan | `~/.claude/plugins/marketplaces/ctx-plugin/plans/*.md` | Grep for issue ID in content | -| Park smart context | `docs/ctx/park.md` or git history | Branch name or issue ID reference | -| Git history | `git log --all --oneline --grep="{issue-id}"` | Commit messages | -| Linear metadata | From step 2 | Already fetched | -| Distilled memories | `~/.claude/projects//memory/*.md` | Grep for issue ID in content or description | +- current source of truth +- previous source of truth +- write paths +- read paths +- fallbacks or dual-write behavior +- compatibility side effects +- verification commands +- remaining migration boundary -Not every issue will have every artifact. Work with what exists — skip missing artifacts gracefully. +If an older doc conflicts with current code, state the current code-backed boundary and mention the doc gap. --- -## 4. Generate docs - -Create `docs/ctx//` with: +## 3. Write The Doc -### `index.md` +Use this structure by default. Omit sections only when they genuinely do not apply. ````markdown -# - -**Generated:** {timestamp} -**Issues:** {N} completed -**Branches:** {list} +# -## Summary +This document summarizes and relates it to the existing docs. -{2-3 paragraph narrative synthesized from specs and plans} +## Status -## Issues +{What is now true. Include exact boundary language.} -| ID | Title | Complexity | Status | Branch | -|----|-------|-----------|--------|--------| -| ... | ... | ... | ... | ... | +## Why This Exists -## Key Decisions +{Problem before the change and why the new boundary is useful.} -{Aggregated from park smart context and spec "Why this approach" sections — only non-obvious decisions} +## Data Model -## Learnings +{Tables, contracts, schemas, durable ids, source keys, or state objects.} -{Aggregated from distilled memories related to these issues} -```` +## Runtime Write Path -### Per-issue docs (`.md`) +{Who writes what, in what order, and transaction/side-effect boundaries.} -````markdown -# — {title} +## Entry Points Updated -**Status:** {from Linear or git} -**Branch:** {from git} -**Spec:** {relative path to spec file, if found} -**Plan:** {relative path to plan file, if found} +| Path | Role | +| --- | --- | +| ... | ... | -## Design +## Reader Behavior -{From spec — problem, chosen approach, tradeoffs} +{What reads the new source first, what falls back, and what remains legacy.} -## Implementation +## What Changed About -{From plan — what was built, key files touched} +{Be explicit about what did not disappear. Name fallbacks and side effects.} -## Outcome +## Verification -{From git log — commits. From park — what actually happened} +{Focused tests, manual SQL/API checks, and behavioral checks.} -## Learnings +## Remaining Migration Boundary -{From park smart context + distilled memories} +{What is intentionally not done yet.} ```` -If a section has no data (e.g., no park file found), omit that section rather than writing "N/A". +### Boundary Language Rules + +- Do not write "migrated" without naming the migrated slice. +- Do not imply the whole product is on the new architecture unless the evidence proves it. +- Separate authentication source, app identity source, analytics source, billing source, and workflow state source when those are different. +- Name legacy fallbacks directly. +- Name compatibility side effects directly. +- Prefer "Postgres-owned for these updated paths" over broad claims like "Postgres-only." --- -## 5. Commit +## 4. Add Mermaid Diagrams + +For system-boundary docs, include both embedded Mermaid blocks in the markdown and standalone `.mmd` files when useful. + +Default diagrams: + +1. **Runtime flow**: request/event -> service -> transaction -> tables/side effects +2. **Entrypoint map**: routes/jobs/events -> shared service -> stores +3. **Reader boundary**: new source -> fallback -> behavior +4. **Before/after ownership**: old source vs new source when the migration is confusing -```bash -git add docs/ctx// -git commit -m "docs: epic documentation" +Use diagrams to clarify ownership and flow. Do not add decorative diagrams. + +Standalone file convention: + +```text +/diagrams//runtime-flow.mmd +/diagrams//entrypoints.mmd +/diagrams//reader-boundary.mmd +``` + +Keep Mermaid syntax simple: + +```mermaid +flowchart TD + A[External source] --> B[Shared service] + B --> C[New durable store] + B --> D[Legacy side effect] ``` + +--- + +## 5. Verify The Documentation + +Before reporting back: + +- confirm the doc file exists +- confirm any standalone `.mmd` files exist +- re-read the generated doc for overclaims +- check that links point to real local files where practical +- run a focused search for the main terms to ensure the doc names the actual code paths +- report verification commands run + +Do not claim tests pass unless you ran the tests. For docs-only changes, file existence, content checks, link sanity, and git status are usually the right verification. From c2aaf899304052f58c08a90eea65b1cd5d47afa9 Mon Sep 17 00:00:00 2001 From: Garo Nazarian Date: Tue, 23 Jun 2026 10:28:48 +0700 Subject: [PATCH 2/2] docs: plan CTX factory guardrails and task contracts --- ...06-23-factory-guardrails-plan-contracts.md | 489 ++++++++++++++++++ 1 file changed, 489 insertions(+) create mode 100644 docs/context/plans/2026-06-23-factory-guardrails-plan-contracts.md diff --git a/docs/context/plans/2026-06-23-factory-guardrails-plan-contracts.md b/docs/context/plans/2026-06-23-factory-guardrails-plan-contracts.md new file mode 100644 index 0000000..43e666f --- /dev/null +++ b/docs/context/plans/2026-06-23-factory-guardrails-plan-contracts.md @@ -0,0 +1,489 @@ +# Factory Guardrails And Plan Contracts + +**Date:** 2026-06-23 +**Status:** Draft for maintainer review +**Repository:** `ctx-plugin` +**Scope:** CTX plugin workflow prompts and deterministic helper scripts + +## Problem + +CTX has two valuable workflow strengths: + +- the factory gives agents a practical visual workspace for product and UI exploration +- `ctx-plan` turns approved specs into tagged implementation plans + +The weak points are in long-running and iterative work: + +- Factory iterations can drift into full rewrites instead of targeted changes. +- Agents can spend too many tokens regenerating prototype HTML that already exists. +- Factory sessions can keep producing visual versions after the decision should have been converted into a spec or plan. +- Plan tasks do not explicitly state the contracts they consume from earlier tasks or produce for later tasks. +- Long implementation sessions can lose their place after context compaction and accidentally replay completed work. + +This spec strengthens CTX without turning the lean brainstorm path into a heavier Superpowers-style process. + +## Decision + +Add three workflow upgrades: + +1. **Factory hard guardrails**: iteration budgets, decision questions, patch-first iteration, and explicit exit rules. +2. **Per-task interfaces** in `ctx-plan`: every task declares what it consumes and what it produces. +3. **Progress ledger** for plan execution: durable task completion state that survives compaction and worktree loss. +4. **Simplification checkpoints**: lightweight clean-code review built into specs, plans, and task completion. + +Do not add a mandatory `Global Constraints` section. Repository-level rules already belong in the project instructions file for the target repo. CTX plans may still include task-specific constraints when the approved spec creates local boundaries such as "do not change schema" or "prototype is visual reference only." + +## Goals + +- Reduce token waste during factory iteration. +- Prevent visual exploration from drifting past the point of decision. +- Make plan tasks easier for fresh agents and subagents to execute without inventing neighboring contracts. +- Give long sessions a durable recovery map after compaction or restart. +- Reduce junior-looking drift: dead branches, duplicated logic, one-off abstractions, excessive defensive code, and convention drift. +- Keep `ctx-brainstorm` lean by default and preserve `ctx-brainstorm-ss` as the escalation path. + +## Non-Goals + +- Do not replace CTX with Superpowers. +- Do not make subagent review mandatory for normal brainstorms. +- Do not require `ctx-execute` for the progress ledger to be useful. +- Do not create a heavy "simplify subagent" requirement for every task. +- Do not chase line-count reduction when explicit code is clearer. +- Do not add project-specific examples, file paths, or business-domain language. +- Do not create a new visual design system for the factory. + +## Design + +### 1. Factory Guardrails + +Factory mode should distinguish between first creation, narrow iteration, reset, and exit. Guardrails need a canonical state shape so agents do not each invent their own budget tracking. + +#### Factory session state + +Each factory page should track a small metadata record: + +- `cycle_id`: stable identifier for one decision question, for example `sidebar-density-20260623` +- `decision_question`: the current question the prototype is meant to answer +- `version_count`: number of versions produced in the current decision cycle +- `source_version`: the version copied or patched to produce the current version +- `change_summary`: what changed from the prior version +- `fixed_decisions`: decisions that should not be revisited without explicit reset +- `status`: `exploring`, `approved`, `reset-requested`, or `exited` + +Canonical state should live in a sidecar file next to the page versions: + +```text +factory/pages///.ctx-factory.json +``` + +The visible prototype should not carry large process notes by default. For approved interactive prototypes, the latest approved HTML still needs visible `Implementation context` or `Interaction behavior` when behavior matters. + +#### Iteration budget + +Default rule: + +- Allow at most 3 versions for a single decision question. +- After version 3, stop and ask for one of: + - approve one version + - name the concrete criterion that is still unresolved + - explicitly reset with a new direction + +Agents must not continue generating "one more pass" without a sharper decision criterion. + +#### Patch-first iteration + +Version 1 may be generated from the design prompt. + +Version 2 and later must be derived from the latest active or approved source version in the same decision cycle: + +1. Locate the latest version for the target group/page. +2. Copy it to the next version path. +3. Apply only the requested changes. +4. Preserve unrelated structure, copy, interactions, and implementation notes. + +Full regeneration is allowed only when the user explicitly says `restart`, `new direction`, or equivalent. A reset starts a new `cycle_id` and resets `version_count`. + +#### Required iteration notes + +Every factory version after v1 must update `.ctx-factory.json` with: + +```markdown +Decision question: +Cycle ID: +Source version: +What changed: +What stayed fixed: +Exit condition: +``` + +The factory should prefer concise metadata over large visible notes when a prototype is intended as a polished implementation reference. + +#### No vague iteration + +If the user says "make it better", "more premium", "cleaner", or similar, the agent must convert that into 1-3 concrete criteria before writing a new version. + +Examples: + +- reduce density in the sidebar +- make the primary action easier to find +- preserve layout but improve typography hierarchy + +If the agent cannot name the criteria, it must ask instead of generating. + +#### Factory exit ramp + +When the user approves a version: + +1. Mark the version as approved. +2. Summarize the implementation-relevant decisions. +3. Stop factory iteration. +4. Move to spec or plan work. + +Approval should not lead to more visual exploration unless the user explicitly opens a new decision question. + +### 2. Factory CLI Support + +Add a new helper so agents do not need to manually regenerate latest-version mechanics. Do not break the existing `factory/cli/iterate.sh ` shape. + +Proposed command shape: + +```bash +factory/cli/prepare-iteration.sh --from latest --note "" +``` + +Expected behavior: + +- find the latest `-vN.html` +- copy it to `-vN+1.html` +- print the new file path +- print the source file path +- create or update `.ctx-factory.json` +- never overwrite an existing version +- return non-zero when the decision cycle has exceeded the 3-version budget and no explicit reset flag was provided + +The helper should emit structured output that is cheap for an agent to parse: + +```text +source=factory/pages///-v3.html +target=factory/pages///-v4.html +version=4 +cycle_id=sidebar-density-20260623 +budget_status=ok +``` + +The agent still applies the actual HTML changes, but the helper removes the token-heavy and error-prone parts: finding latest, copying, version naming, and budget accounting. + +The existing `/api/write` path remains the normal creation path for v1 and can remain the normal final submission path for changed content. The new helper prepares a patch target for v2+; implementation should either make the factory server notice the copied file or add a small reload/broadcast path so the browser can show prepared versions without manual refresh. + +### 3. Per-Task Interfaces In Plans + +Extend `ctx-plan` task structure with an `Interfaces` block for cross-task and public contracts only. Do not restate files already listed under `Files`. + +```markdown +### Task N: `[MED]` + +**Files:** +- Modify: `path/to/file` +- Test: `path/to/test` + +**Interfaces:** +- Consumes: + - `` from Task M +- Produces: + - `` for Task K + +**Steps:** +- [ ] ... +``` + +`Consumes` means the task depends on a contract created earlier or already present. + +`Produces` means later tasks rely on the task's output. It should name exact functions, commands, files, metadata keys, CLI output fields, or prompt sections when those details matter. + +If a task is isolated, the block should explicitly say: + +```markdown +**Interfaces:** +- Consumes: none +- Produces: none outside this task +``` + +This prevents fresh workers from inventing nearby names, changing contracts silently, or assuming context from the full plan. + +### 4. Progress Ledger + +Add a durable progress ledger for plans so execution can resume after compaction, restart, or worktree deletion. + +Canonical ledger path: + +```text +Claude: ~/.claude/plugins/marketplaces/ctx-plugin/progress/.md +Codex: ~/.codex/ctx-codex/progress/.md +``` + +Each plan frontmatter must include: + +```yaml +progress_ledger: +``` + +Rationale: + +- current `ctx-plan`, `ctx-execute`, and `ctx-resume` already discover plans from runtime-global storage +- a runtime-global ledger survives deleted worktrees +- the plan frontmatter gives inline execution, delegated execution, and resume the same source of truth +- the ledger is separate from the plan, so agents can update progress without rewriting the plan document + +Optional worktree mirror: + +```text +.ctx/progress/.md +``` + +The mirror is only a convenience for agents already inside a worktree. The runtime-global ledger is authoritative when the two disagree. + +Example: + +```markdown +# Progress Ledger: factory-guardrails-plan-contracts + +Plan: docs/context/plans/2026-06-23-factory-guardrails-plan-contracts.md +Branch: +Started: 2026-06-23T00:00:00Z + +## Current State + +- Task 1: complete + - commits: abc1234..def5678 + - verification: `bash plugins/ctx-codex/scripts/test-scripts.sh` passed + - notes: none +- Task 2: in_progress + - owner: current session + - started: 2026-06-23T00:00:00Z + +## Events + +- 2026-06-23T00:00:00Z Task 1 marked in_progress by current session +- 2026-06-23T00:05:00Z Task 1 marked complete after verification +``` + +Minimum required fields: + +- task number +- status: `pending`, `in_progress`, `complete`, `blocked` +- commit range when available +- verification command and result when available +- blocker summary when blocked + +Agents resuming a plan must read the ledger before executing tasks. Completed tasks in the ledger must not be replayed unless the user explicitly asks to redo them. + +Ledger update semantics: + +- update `Current State` as a mutable table/list for cheap resume parsing +- append every transition to `Events` for auditability +- treat the runtime-global ledger as authoritative over any worktree mirror +- stop and ask if the ledger, plan frontmatter, and git history contradict each other + +### 5. Prompt Updates + +Update `ctx-plan` to require: + +- `Interfaces` block in every task +- exact consumed/produced names when tasks depend on each other +- task-specific constraints when relevant +- `progress_ledger` in the plan frontmatter +- creation of the runtime-global ledger when a plan is written + +Update inline execution guidance to require: + +- read the progress ledger before starting +- update the ledger after each verified task +- skip tasks already marked `complete` + +Update `ctx-execute` to require: + +- read ledger before starting +- create ledger if missing +- mark task `in_progress` before work starts +- mark task `complete` only after verification evidence exists +- preserve completed entries after compaction +- stop if ledger contradicts the plan or git history + +Update `ctx-resume` to require: + +- show the `progress_ledger` path when listing active plans +- read the ledger before relaunching a worktree +- tell the next session which task should be resumed first +- preserve the runtime-global ledger when recreating a deleted worktree + +Update factory references to require: + +- patch-first iteration after v1 +- version budget +- decision question per cycle +- explicit reset language for full rewrites +- exit ramp on approval + +Equivalent behavior must be implemented in both plugin trees, or a runtime-specific exception must be documented next to the changed file and in the implementation plan. + +### 6. Simplification Checkpoints + +CTX should make clean-code review part of the normal workflow without turning every plan into a refactor project. + +The source pattern is the local `simplify` discipline: + +- remove dead code +- remove duplication +- remove unnecessary complexity +- preserve behavior +- stay inside the scope of recent changes +- avoid new abstractions with only one call site +- prefer project conventions over invented patterns + +For CTX itself, this should be generalized into runtime-agnostic guidance and applied at three points. + +#### Brainstorm spec guardrails + +`ctx-brainstorm` specs should include a small "Simplicity Guardrails" section when the feature changes code behavior, creates new helpers, or adds UI/workflow complexity. + +The section should answer: + +```markdown +## Simplicity Guardrails + +- Existing patterns to reuse: +- Complexity to avoid: +- Abstractions explicitly not being introduced: +- Behavior that must not change: +- Files or areas outside scope: +``` + +This belongs in the spec because it sets design altitude before implementation. It should not become a generic checklist on every tiny change; if the feature is truly `[LOW]`, the section may be omitted or reduced to one sentence. + +#### Plan task guardrails + +`ctx-plan` should add a short `Simplification Check` to each task that modifies production code: + +```markdown +**Simplification Check:** +- Remove dead code introduced or made obsolete by this task. +- Collapse duplicated logic created by this task. +- Do not add an abstraction unless at least two call sites need it, or the approved spec names it. +- Do not refactor outside the task's files. +- Preserve behavior not explicitly changed by the spec. +``` + +For task-specific risks, the plan should be more concrete: + +```markdown +**Simplification Check:** +- Reuse the existing parser helper; do not add a second parsing path. +- Keep the new state in the existing reducer; do not add a parallel state holder. +- Delete the old branch only after the replacement path is covered by the task test. +``` + +The plan self-review should reject vague cleanup tasks such as "simplify later" or "clean up the code" unless they name the exact changed files and the exact class of complexity to remove. + +#### Completion-time cleanup + +After each task is implemented and verified, the executing agent should run a local simplification pass over only the files changed by that task. + +This is a review step, not a new feature step: + +1. Inspect the task diff. +2. Remove dead imports, unused variables, obsolete branches, and commented-out code. +3. Collapse duplicated logic introduced by the task. +4. Remove one-off abstractions unless the plan/spec explicitly requires them. +5. Re-run the task's targeted verification after any cleanup edit. + +For `[LOW]` and most `[MED]` tasks, this should be same-context. Fresh-context simplification review is reserved for `[HIGH]` tasks, repeated drift, or when the user explicitly requests it. + +The progress ledger should record the simplification checkpoint: + +```markdown +- simplification: checked changed files; removed unused helper; verification re-run +``` + +or: + +```markdown +- simplification: checked changed files; no changes needed +``` + +This keeps compaction recovery honest: a resumed agent can tell whether the task was merely made to pass or also cleaned up. + +## Data Flow + +### Factory iteration + +```text +User feedback + -> agent identifies decision question and concrete criteria + -> factory prepare-iteration helper copies latest version to next version + -> agent patches only requested HTML/CSS/JS changes + -> factory server displays next version + -> user approves, asks for concrete next version, or resets +``` + +### Plan execution recovery + +```text +Agent resumes work + -> reads approved plan + -> resolves progress_ledger from plan frontmatter + -> reads runtime-global progress ledger + -> skips complete tasks + -> resumes first pending/in_progress task + -> verifies task + -> updates Current State and appends Events entry +``` + +### Clean-code checkpoint + +```text +Task implementation passes verification + -> agent inspects task diff + -> removes dead code, duplication, and one-off complexity inside task scope + -> re-runs targeted verification if cleanup changed code + -> writes simplification result to progress ledger +``` + +## Success Criteria + +- [ ] Factory docs state that v2+ must copy and patch the previous version unless reset is explicit. +- [ ] Factory docs enforce a default 3-version budget per decision question. +- [ ] Factory docs require decision question, change summary, fixed decisions, and exit condition for iterations. +- [ ] Factory docs define an approval exit ramp into spec or plan work. +- [ ] Factory state has a canonical `.ctx-factory.json` schema with `cycle_id`, status, budget, and approval fields. +- [ ] Factory CLI has a deterministic helper for latest-version copy, next-version naming, metadata updates, and budget warnings. +- [ ] `ctx-plan` task template includes `Interfaces: Consumes / Produces`. +- [ ] `ctx-plan` self-review checks for missing or vague task interfaces. +- [ ] `ctx-plan` writes `progress_ledger` in frontmatter and creates the runtime-global ledger. +- [ ] `ctx-brainstorm` can capture task-relevant simplicity guardrails without forcing ceremony onto trivial changes. +- [ ] `ctx-plan` task template includes a scoped `Simplification Check` for production-code tasks. +- [ ] Execution guidance runs a post-task simplification pass over only the task diff before marking the task complete. +- [ ] Progress ledger records whether simplification was checked and whether it changed code. +- [ ] Inline execution, `ctx-execute`, and `ctx-resume` read and update the same durable progress ledger. +- [ ] Resuming after compaction or deleted worktree cannot replay tasks marked complete in the runtime-global ledger. +- [ ] Equivalent behavior is implemented for both Claude and Codex plugin trees, with documented exceptions if needed. +- [ ] User-visible changes update `CHANGELOG.md` and the relevant manifest versions. +- [ ] Script changes pass the matching script harnesses for changed runtimes. + +## Complexity Tags + +- [LOW] Update `ctx-plan` prompt and example plan with `Interfaces` block. +- [LOW] Add optional `Simplicity Guardrails` guidance to `ctx-brainstorm` and `ctx-brainstorm-ss`. +- [MED] Add scoped `Simplification Check` guidance to `ctx-plan`, inline execution, and `ctx-execute`. +- [MED] Add progress ledger requirements to `ctx-plan`, inline execution guidance, `ctx-execute`, and `ctx-resume`. +- [MED] Update factory prompt references with version budget, decision question, patch-first iteration, and exit ramp. +- [MED] Add factory CLI helper for latest-version copy, metadata, budget warnings, and structured output. +- [LOW] Mirror prompt/reference changes across Claude and Codex trees. +- [LOW] Replace or neutralize project-specific example-plan content touched by this change. +- [LOW] Update CHANGELOG, manifest versions, README, or maintainer docs if user-visible workflow behavior changes. + +## Open Questions + +- Should `prepare-iteration.sh` be purely filesystem-based, or should it call a new factory server endpoint so browser reload/broadcast behavior stays centralized? +- What exact `.ctx-factory.json` schema should be documented as v1? +- Should docs-only and prompt-only tasks accept a review checklist as verification evidence, or require a script/doc-link validation command? +- Should `[HIGH]` tasks get a default fresh-context simplification review, or should that remain explicit/user-triggered to control token spend?