@cluesmith/codev 3.0.1 → 3.0.2

package/scripts/forge/linear/issue-list.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+# Forge concept: issue-list (Linear via GraphQL API)
+# Input: CODEV_LINEAR_TEAM (team key, e.g. "ENG")
+# Output: JSON [{number, title, url, labels, createdAt, author, assignees}]
+set -e
+
+if [ -z "$LINEAR_API_KEY" ]; then
+  echo "LINEAR_API_KEY is not set" >&2
+  exit 1
+fi
+
+FILTER='{ state: { type: { nin: ["completed", "canceled"] } } }'
+if [ -n "$CODEV_LINEAR_TEAM" ]; then
+  FILTER="$(jq -n --arg team "$CODEV_LINEAR_TEAM" '{
+    team: { key: { eq: $team } },
+    state: { type: { nin: ["completed", "canceled"] } }
+  }')"
+fi
+
+curl -sf -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d "$(jq -n --argjson filter "$FILTER" '{
+    query: "query($filter: IssueFilter) { issues(filter: $filter, first: 200) { nodes { identifier title url labels { nodes { name } } createdAt assignee { displayName } creator { displayName } } } }",
+    variables: { filter: $filter }
+  }')" \
+  | jq '[.data.issues.nodes[] | {
+    number: .identifier,
+    title: .title,
+    url: .url,
+    labels: [.labels.nodes[] | { name: .name }],
+    createdAt: .createdAt,
+    author: (if .creator then { login: .creator.displayName } else null end),
+    assignees: (if .assignee then [{ login: .assignee.displayName }] else [] end)
+  }]'

package/scripts/forge/linear/issue-view.sh

@@ -0,0 +1,37 @@
+#!/bin/sh
+# Forge concept: issue-view (Linear via GraphQL API)
+# Input: CODEV_ISSUE_ID (e.g. "ENG-123")
+# Output: JSON {title, body, state, comments[]}
+set -e
+
+if [ -z "$LINEAR_API_KEY" ]; then
+  echo "LINEAR_API_KEY is not set" >&2
+  exit 1
+fi
+
+if [ -z "$CODEV_ISSUE_ID" ]; then
+  echo "CODEV_ISSUE_ID is not set" >&2
+  exit 1
+fi
+
+curl -sf -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d "$(jq -n --arg id "$CODEV_ISSUE_ID" '{
+    query: "query($id: String!) { issueVcsByFilter: issues(filter: { identifier: { eq: $id } }) { nodes { title description state { name } comments { nodes { body createdAt user { displayName } } } } } }",
+    variables: { id: $id }
+  }')" \
+  | jq 'if (.data.issueVcsByFilter.nodes | length) == 0 then
+    error("issue not found: \(env.CODEV_ISSUE_ID)")
+  else
+    .data.issueVcsByFilter.nodes[0] | {
+      title: .title,
+      body: (.description // ""),
+      state: .state.name,
+      comments: [.comments.nodes[] | {
+        body: .body,
+        createdAt: .createdAt,
+        author: { login: .user.displayName }
+      }]
+    }
+  end'

package/scripts/forge/linear/recently-closed.sh

@@ -0,0 +1,45 @@
+#!/bin/sh
+# Forge concept: recently-closed (Linear via GraphQL API)
+# Input: CODEV_LINEAR_TEAM, CODEV_SINCE_DATE (optional, ISO date)
+# Output: JSON [{number, title, url, labels, createdAt, closedAt}]
+set -e
+
+if [ -z "$LINEAR_API_KEY" ]; then
+  echo "LINEAR_API_KEY is not set" >&2
+  exit 1
+fi
+
+FILTER='{ state: { type: { in: ["completed", "canceled"] } } }'
+if [ -n "$CODEV_LINEAR_TEAM" ] && [ -n "$CODEV_SINCE_DATE" ]; then
+  FILTER="$(jq -n --arg team "$CODEV_LINEAR_TEAM" --arg since "$CODEV_SINCE_DATE" '{
+    team: { key: { eq: $team } },
+    state: { type: { in: ["completed", "canceled"] } },
+    completedAt: { gte: $since }
+  }')"
+elif [ -n "$CODEV_LINEAR_TEAM" ]; then
+  FILTER="$(jq -n --arg team "$CODEV_LINEAR_TEAM" '{
+    team: { key: { eq: $team } },
+    state: { type: { in: ["completed", "canceled"] } }
+  }')"
+elif [ -n "$CODEV_SINCE_DATE" ]; then
+  FILTER="$(jq -n --arg since "$CODEV_SINCE_DATE" '{
+    state: { type: { in: ["completed", "canceled"] } },
+    completedAt: { gte: $since }
+  }')"
+fi
+
+curl -sf -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d "$(jq -n --argjson filter "$FILTER" '{
+    query: "query($filter: IssueFilter) { issues(filter: $filter, first: 200, orderBy: updatedAt) { nodes { identifier title url labels { nodes { name } } createdAt completedAt } } }",
+    variables: { filter: $filter }
+  }')" \
+  | jq '[.data.issues.nodes[] | {
+    number: .identifier,
+    title: .title,
+    url: .url,
+    labels: [.labels.nodes[] | { name: .name }],
+    createdAt: .createdAt,
+    closedAt: .completedAt
+  }]'

package/scripts/forge/linear/user-identity.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Forge concept: user-identity (Linear via GraphQL API)
+# Output: plain text display name
+set -e
+
+if [ -z "$LINEAR_API_KEY" ]; then
+  echo "LINEAR_API_KEY is not set" >&2
+  exit 1
+fi
+
+curl -sf -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{"query":"{ viewer { displayName } }"}' \
+  | jq -r '.data.viewer.displayName'

package/skeleton/.claude/skills/update-arch-docs/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: update-arch-docs
+description: Audit, prune, and update the project's architecture documentation — `codev/resources/arch.md` and `codev/resources/lessons-learned.md`. Use this skill when running MAINTAIN's arch-doc step, or when asked to update / audit / prune `codev/resources/arch.md` or `codev/resources/lessons-learned.md`. The skill is opinionated about what NOT to include in these files (per-spec changelogs, exhaustive enumerations, aspirational state, duplicate meta-spec content) and ships two operating modes: diff-mode (apply a specific change) and audit-mode (propose cuts with reasons). It edits files directly via normal file-edit tooling and does not invoke destructive shell commands.
+---
+
+# update-arch-docs
+
+This skill maintains two governance documents:
+
+- `codev/resources/arch.md` — the project's architecture document.
+- `codev/resources/lessons-learned.md` — durable engineering wisdom extracted from reviews.
+
+It is invoked by the MAINTAIN protocol's documentation step, and ad-hoc whenever someone needs to update, audit, or prune either file. The skill is opinionated about *what does not belong* in these files. Use it whenever a doc change touches arch.md or lessons-learned.md, even if the change is just an addition.
+
+## What this skill does NOT do
+
+These are the patterns that have, in practice, caused arch.md and lessons-learned.md to grow without bound. Treat them as bright-line rejections during both audit-mode and diff-mode work.
+
+### In arch.md
+
+- **Per-file enumerations** that go stale the moment they're written. Document the *shape* of a directory and the handful of load-bearing files; do not list every file. `git ls-files` is authoritative; the doc is for orientation.
+- **Per-spec changelog sections** ("Spec 0042 added X, Spec 0073 changed Y"). Architecture is current state, not history. The git log + the spec/review documents own the changelog framing.
+- **Specs/plans tables** that mirror the contents of `codev/specs/` and `codev/plans/`. These are duplicative and rot quickly. Link to the directory; do not paginate it into the doc.
+- **Aspirational state** ("we plan to…", "in the next phase we'll…"). That belongs in the relevant meta-spec or roadmap doc, not in the architecture body. arch.md describes what *is*, not what *might be*.
+- **Date-stamped narrative** ("As of 2026-Q2, the system uses…"). Dates make the doc look fresh while making it harder to maintain. Use git log + commit dates for temporal context.
+- **Duplication of meta-spec content**. If a subsystem has its own meta-spec under `codev/architecture/<domain>.md` or under `codev/specs/`, arch.md should carry a 1-paragraph summary plus a pointer — not a copy.
+- **Retired-component graveyards**. When a component is removed, delete its section. `git log` retains history; an arch.md that describes things that no longer exist is misleading.
+
+### In lessons-learned.md
+
+- **Spec-narrow recipes** that only matter inside the originating feature ("In spec 0073 we found that the rate limiter needs X"). These belong in the spec's review document, not in lessons-learned.md. lessons-learned.md captures patterns that apply *across* specs.
+- **Multi-paragraph entries**. If a lesson needs more than 1–3 sentences to land, it is either two lessons fused together or it is documentation that belongs elsewhere.
+- **Duplicate adjacent entries**. Fold variations of the same lesson into one entry. Two entries that say the same thing are louder, not clearer.
+- **Spec-numbered narrative entries** ("Lesson from #0468:…"). Link to the review if needed; the lesson itself should be stated as a general principle.
+
+### In either file (process)
+
+- **Destructive shell commands**. The skill must not invoke `rm -rf`, `git rm`, or destructive `sed` scripts. All edits go through the normal Edit tool. The MAINTAIN PR diff is the human-confirmation step; that's enough.
+
+## arch.md vs. lessons-learned.md (two-doc framing)
+
+Treat the two files as siblings with different purposes. When in doubt about which file a fact belongs in, route by purpose:
+
+| Purpose | Goes in |
+|---|---|
+| Current system shape — services, transports, key mental models | `arch.md` |
+| Mechanism for a unique subsystem | `arch.md` (subsystem section) — or its own meta-spec if the mechanism is large enough to warrant one, with arch.md keeping a 1-paragraph summary + pointer |
+| Pointers ("see meta-spec X for details") | `arch.md` |
+| A durable engineering pattern that applies across multiple specs | `lessons-learned.md` |
+| A system-shape surprise verified-wrong in production ("looks like X but isn't") | `arch.md` § "Verified-Wrong Assumptions" — *not* lessons-learned.md, because it's a property of the system, not a general pattern |
+
+The "system-shape surprise" routing is the one most often gotten wrong. If a future reader needs to know "the system *looks* like X but actually does Y", that is system shape and lives in arch.md. If they need to know "we learned that doing X is generally a bad idea", that is engineering wisdom and lives in lessons-learned.md.
+
+## Sizing by purpose, not by line count
+
+There is no line-count budget for either file. The right size for each section is determined by what the section needs to do. If a subsystem genuinely has unique mechanism that takes 80 lines to explain clearly, 80 lines is the right size. If a subsystem can be described in 5 lines and a pointer to a meta-spec, 5 lines is right.
+
+What's *wrong* is bulk that comes from any of the patterns in "What this skill does NOT do" above. Strip those, and the file's size will land where it belongs.
+
+When proposing a section, ask: "Could a future reader skip this section without losing anything load-bearing?" If yes, the section should not exist. The doc's purpose is orientation, not completeness.
+
+## Mode: diff-mode (apply a specific change)
+
+Use diff-mode when the request is specific: "add a section about the new caching layer," "update the Glossary entry for Tower," "remove the reference to the deleted dashboard-server."
+
+In diff-mode:
+
+1. Find the smallest section that needs to change.
+2. Apply the change via the Edit tool.
+3. If the change adds new content, run a quick sanity check against "What this skill does NOT do" before saving — make sure the new content is current state, not aspirational; not duplicative of a meta-spec; not a per-spec changelog entry.
+4. Surface the resulting diff for review.
+
+Diff-mode is fast. It is the right mode for ~80% of post-MAINTAIN documentation work.
+
+## Mode: audit-mode (identify what to cut)
+
+Use audit-mode when the request is general: "the doc feels stale," "MAINTAIN says it's time to prune," "review arch.md against the principles."
+
+In audit-mode:
+
+1. Read the file end-to-end.
+2. For each section in arch.md, run through the per-section pruning checklist (from the MAINTAIN protocol):
+   - Does it describe *current state*? If aspirational, the section moves to a meta-spec; the arch.md keeps a 1-paragraph summary + pointer (or nothing, if the meta-spec stands on its own).
+   - Does it duplicate a meta-spec? If yes, replace with a 1-paragraph summary + pointer.
+   - Is it a per-file enumeration that's gone stale? If yes, prune to the directory shape + a few key files.
+   - Is it a changelog/narrative section ("Spec 0042 added X")? If yes, absorb the architecturally-relevant facts and remove the spec-numbered framing.
+   - Is the component still alive? If retired, delete the section entirely.
+3. For each entry in lessons-learned.md, run the per-entry checklist:
+   - Is it cross-applicable beyond the spec that produced it? If no, remove (the lesson belongs in the spec's review).
+   - Is it terse (1–3 sentences)? If multi-paragraph, split or compress.
+   - Is the topic section the right one? If filed under "Architecture (continued)" or a spec-numbered section, move it to the right topical home.
+   - Is it a duplicate of an adjacent entry? If yes, fold them.
+4. **When in doubt, KEEP.** This rule comes from the MAINTAIN protocol and applies in audit-mode too. A confident cut is better than three speculative ones. Bias toward fewer, higher-confidence proposals with clear rationale; do not chase a maximum cut count.
+5. Apply the cuts via the Edit tool — the skill does not produce a "candidate-cuts list and stop." The diff *is* the proposal. The MAINTAIN PR review is the human-confirmation step.
+6. Surface a short reason alongside each cut in the run file (`codev/maintain/NNNN.md`) so PR reviewers can evaluate intent ("removed because: per-spec changelog framing"; "compressed because: duplicates the orchestrator meta-spec").
+
+Audit-mode is slower than diff-mode and produces larger diffs. Reserve it for explicit audit invocations, not for routine doc updates.
+
+## Output contract
+
+The skill commits to the following:
+
+- It edits `codev/resources/arch.md` and `codev/resources/lessons-learned.md` directly via the Edit tool.
+- It does not invoke destructive shell commands (no `rm -rf`, no `git rm`, no destructive `sed`). File deletions happen only through Edit removing the relevant content; whole-file removal would be a structural change that is out of scope for this skill.
+- In audit-mode, every removal is paired with a one-line reason in the MAINTAIN run file's `## Audit Findings` section. Rationale lives there so reviewers can evaluate intent without re-deriving it from the diff.
+- The skill does not modify other files (specs, plans, reviews, source code). If a fact belongs somewhere else, the skill flags it; it does not move it.
+- The skill does not edit live arch.md or lessons-learned.md content as a side effect of being read or invoked — only when the user/MAINTAIN protocol explicitly asks for an update or audit.

package/skeleton/protocols/maintain/protocol.md

@@ -10,6 +10,23 @@ MAINTAIN is a single-pass maintenance protocol for keeping codebases healthy. Th
 - `codev/resources/arch.md` - Architecture documentation
 - `codev/resources/lessons-learned.md` - Extracted wisdom from reviews
 
+The two governance docs are siblings with **different purposes**: `arch.md` owns system shape (services, transports, mental models, verified-wrong assumptions about *this* system); `lessons-learned.md` owns durable engineering wisdom that applies *across* specs. Use the routing matrix below to decide where each fact belongs.
+
+### Lives where: routing facts to the right home
+
+| Type of fact/insight | Lives in |
+|---|---|
+| Current system shape (services, transports, key mental models) | `codev/resources/arch.md` |
+| Mechanism for a unique subsystem | `codev/resources/arch.md` (subsystem section) OR a meta-spec under `codev/architecture/<domain>.md` if the mechanism is large enough to warrant its own doc |
+| A durable engineering pattern that applies across multiple specs | `codev/resources/lessons-learned.md` |
+| A spec-narrow fix recipe (only relevant inside the originating feature) | Spec review only — does NOT belong in `lessons-learned.md` |
+| A system-shape surprise verified-wrong in production ("looks like X but isn't") | `codev/resources/arch.md` § "Verified-Wrong Assumptions" |
+| Aspirational architectural direction (where we want to go) | The relevant meta-spec or roadmap doc, NOT `arch.md` body |
+| A changelog entry ("we shipped X in spec Y on date Z") | `git log` + the spec/review document — NOT `arch.md`, NOT `lessons-learned.md` |
+| A retired or removed component | Delete the section entirely; do NOT keep a "retired components" graveyard. (`git log` retains history.) |
+
+The most commonly-misrouted entry is the system-shape surprise. If a future reader needs to know "the system *looks* like X but actually does Y," that is system shape and lives in `arch.md`. If they need to know "we learned that doing X is generally a bad idea," that is engineering wisdom and lives in `lessons-learned.md`.
+
 ## When to Use
 
 - Before a release (clean slate for shipping)
@@ -90,14 +107,54 @@ For each finding from the audit:
 
 ### Step 3: Sync Documentation
 
+Step 3 is split into two sub-steps: **Audit first, then update.** This split exists because `arch.md` and `lessons-learned.md` accumulate without bound when MAINTAIN does only "what's new" — the audit pass surfaces what should be cut so the update pass is not purely additive.
+
+The `update-arch-docs` skill (at `.claude/skills/update-arch-docs/SKILL.md`) is invoked by both sub-steps. Read it before starting Step 3 so the discipline is fresh.
+
+#### Step 3a: Audit documentation
+
+Invoke the `update-arch-docs` skill in **audit-mode**. The skill reads `codev/resources/arch.md` and `codev/resources/lessons-learned.md` end-to-end against the discipline below and produces a candidate-cuts list (with reasons) recorded in the run file (`codev/maintain/NNNN.md`) under a new `## Audit Findings` section before any edits land.
+
+**Per-arch.md-section pruning checklist** — for each section in `arch.md`, ask:
+- Does it describe **current state**? If aspirational, the section moves to a meta-spec; `arch.md` keeps a 1-paragraph summary + pointer (or nothing, if the meta-spec stands on its own).
+- Does it duplicate a meta-spec? If yes, replace with a 1-paragraph summary + pointer.
+- Is it a per-file enumeration that's gone stale? If yes, prune to the directory shape + a few key files.
+- Is it a changelog/narrative section ("Spec 0042 added X")? If yes, absorb the architecturally-relevant facts and remove the spec-numbered framing.
+- Is the component still alive? If retired, delete the section entirely.
+
+**Per-lessons-learned.md-entry pruning checklist** — for each entry, ask:
+- Is it cross-applicable beyond the spec that produced it? If no, remove (the lesson belongs in the spec's review).
+- Is it terse (1–3 sentences)? If multi-paragraph, split or compress.
+- Is the topic section the right home? If filed under "Architecture (continued)" or a spec-numbered section, move it to the right topical home.
+- Is it a duplicate of an adjacent entry? If yes, fold them.
+
+**Sample audit prompt** (paste into the skill invocation if you want a baseline checklist run):
+
+```
+Audit codev/resources/arch.md and codev/resources/lessons-learned.md against the
+discipline in the update-arch-docs skill. For each section/entry, run the per-
+arch.md-section and per-lessons-learned.md-entry pruning checklists from the
+MAINTAIN protocol (Step 3a). Produce a candidate-cuts list with one-line reasons.
+Bias toward fewer, higher-confidence cuts ("when in doubt, KEEP"). Record the
+findings in the current run file's ## Audit Findings section before applying.
+```
+
+**When in doubt, KEEP.** This rule is preserved from the older Step 3. A confident cut is better than three speculative ones. The audit pass is a *proposal*; the architect's PR review confirms it.
+
+#### Step 3b: Update documentation
+
+Apply the audit decisions from Step 3a, plus any additive content needed.
+
 **arch.md**: Compare documented structure with actual codebase. Update:
 - Directory structure
 - Component descriptions (explain HOW things work, not just WHAT)
 - Key files and their purposes
-- Remove references to deleted code
+- Remove references to deleted code (per Step 3a audit findings)
 - Add new components/utilities
 
-**lessons-learned.md**: Scan `codev/reviews/` for new reviews since last run. Extract lessons that are actionable, durable, and general.
+**lessons-learned.md**: Scan `codev/reviews/` for new reviews since last run. Extract lessons that are actionable, durable, and general. Apply Step 3a's per-entry cuts.
+
+For specific additive changes, invoke `update-arch-docs` in **diff-mode** — it applies the smallest section update needed.
 
 **CLAUDE.md / AGENTS.md**: Diff the two files. They must be identical. Update the stale one.
 
@@ -133,6 +190,16 @@ Each run creates `codev/maintain/NNNN.md`:
 
 <key commits summary>
 
+## Audit Findings
+
+Recorded by Step 3a (Audit documentation) before any edits land. One line per candidate cut.
+
+### arch.md
+- <section-name>: <reason for proposed cut/compression>
+
+### lessons-learned.md
+- <entry>: <reason>
+
 ## What Was Done
 
 ### Dead Code Removed

package/skeleton/protocols/spir/protocol.md

@@ -504,9 +504,10 @@ Execute for each phase in the plan. Each phase follows a build-verify cycle.
    - Enhance documentation
 
 3. **Update Architecture Documentation**
-   - Update `codev/resources/arch.md` with new modules, utilities, or architectural changes
-   - Follow guidance in MAINTAIN protocol's "Update arch.md" task for structure and standards
-   - Ensure arch.md reflects current codebase state
+   - Update `codev/resources/arch.md` and `codev/resources/lessons-learned.md` with new modules, utilities, architectural changes, and durable engineering wisdom uncovered during this work
+   - Use the **`update-arch-docs` skill** (at `.claude/skills/update-arch-docs/SKILL.md`) to apply changes — the skill encodes the discipline for what NOT to include and the two-doc framing (arch.md owns system shape; lessons-learned.md owns durable engineering wisdom)
+   - Follow guidance in the MAINTAIN protocol's Step 3 ("Sync Documentation") for structure, the "Lives where" routing matrix, and pruning checklists
+   - Ensure both docs reflect current state
 
 4. **Revision Requirements** (MANDATORY)
    - Update README.md with any new features or changes

package/skeleton/resources/risk-triage.md

@@ -41,7 +41,7 @@ gh pr view <N> --json files | jq '.files[].path'
 | `packages/codev/src/state/` | State management | High |
 | `codev/protocols/` | Protocol definitions | High |
 | `codev-skeleton/protocols/` | Protocol templates | High |
-| `packages/codev/src/commands/af/` | Agent Farm commands | Medium |
+| `packages/codev/src/agent-farm/commands/` | Agent Farm commands | Medium |
 | `packages/codev/src/commands/consult/` | Consultation system | Medium |
 | `packages/codev/src/lib/` | Shared libraries | Medium |
 | `packages/codev/src/commands/` (other) | CLI commands | Medium |

package/skeleton/templates/arch.md

@@ -1,56 +1,126 @@
 # Architecture
 
-High-level architecture documentation for this project. Updated during MAINTAIN protocol runs.
+The architecture document for this project. Skim it to orient yourself; reach for the meta-specs under `codev/architecture/` (if any) or the relevant subsystem section for depth.
 
-## Overview
+> **How to use this template**: Each section below is a stub with a one-line "skip if N/A" hint. Delete sections that don't apply to your project — small projects often only need TL;DR, Repository Layout & Stack, and Updating This Document. Bigger systems will fill in more. The goal is orientation, not completeness.
 
-<!-- Brief description of the project and its purpose -->
+## TL;DR
 
-## Directory Structure
+A 2–4 sentence summary of what this project is, the language/stack, the deployment shape, and the single most important mental model a new contributor needs.
+
+*Example*: "A monorepo of TypeScript packages and a CLI. The CLI talks to a long-running orchestrator process (Tower) over WebSockets. The orchestrator manages git worktrees, one per builder. The mental model is: 'CLI = thin client; Tower = state owner.'"
+
+## Repository Layout & Stack
+
+The shape of the repo and the languages/frameworks in use. Not a per-file enumeration — a `tree -L 2` view plus 2–3 lines on each top-level directory's role is plenty.
+
+> *Skip if N/A: a single-package project that's well-served by `package.json` alone.*
 
 ```
 project-root/
-├── codev/           # Development methodology
-│   ├── specs/       # Feature specifications
-│   ├── plans/       # Implementation plans
-│   └── reviews/     # Post-implementation reviews
-└── [your code]      # Project source code
+├── packages/        # Workspace packages
+├── codev/           # Specs, plans, reviews, protocol files
+├── docs/            # User-facing documentation
+└── ...
 ```
 
-## Key Components
+**Stack**: language version(s), framework(s), package manager. Avoid pinning exact patch versions; the lockfile is authoritative for those.
+
+## Per-Subsystem Mechanism
+
+For each subsystem with **unique mechanism** — something a reader cannot derive from reading the code in 5 minutes — give it a section here. Mechanism means: how the pieces fit together, what invariants hold, what surprised the team.
+
+> *Skip if N/A: subsystems whose mechanism is well-conveyed by the code itself or by a meta-spec under `codev/architecture/<domain>.md`. In that case, replace this section with a 1-paragraph summary + pointer.*
+
+### [Subsystem name]
+
+**Purpose**: One sentence on what this subsystem owns.
+
+**Mechanism**: How it works. Invariants. Failure modes worth knowing.
+
+**Pointer**: `codev/architecture/<domain>.md` (if a meta-spec exists).
+
+## Apps Roster
+
+For projects that ship multiple deployable apps — a CLI, a web service, a worker, etc. List them with a one-liner each.
+
+> *Skip if N/A: single-app projects.*
 
-<!-- Document major modules, services, or subsystems -->
+| App | Purpose | Entry point |
+|---|---|---|
+| `cli` | Command-line interface | `packages/cli/src/index.ts` |
+| `worker` | Background job runner | `apps/worker/src/main.ts` |
 
-### Component 1
+## Packages Roster
 
-**Location**: `src/...`
+For monorepos. List the workspace packages with a one-liner each. Do not duplicate `pnpm-workspace.yaml` or `package.json` — link to them.
 
-**Purpose**: ...
+> *Skip if N/A: non-monorepo projects.*
 
-**Key Files**:
-- `file1.ts` - ...
-- `file2.ts` - ...
+| Package | Purpose |
+|---|---|
+| `@org/core` | Domain logic, no I/O |
+| `@org/cli` | CLI entry point, depends on core |
 
-## Data Flow
+## Verified-Wrong Assumptions
 
-<!-- How data moves through the system -->
+System-shape surprises that have been verified wrong in production. Each entry is one or two sentences: *"It looks like X but is actually Y. We learned this when ..."*. This section earns its keep by saving future readers from the same mistake.
 
-## External Dependencies
+> *Skip if N/A: nothing has surprised you yet. Add entries as they're discovered.*
 
-<!-- Third-party services, APIs, databases -->
+- *Example*: "It looks like the CLI talks to Tower over HTTP, but the WebSocket bidirectional channel is the actual transport — the HTTP routes are only used for `/health` and one-off lookups. We learned this when adding a new command broke because we wrote it as a fetch call."
 
-| Dependency | Purpose | Documentation |
-|------------|---------|---------------|
-| Example | ... | [docs](url) |
+## Updating This Document
 
-## Configuration
+This is a single-page orientation doc, not a wiki. Keep it sized to its purpose.
 
-<!-- Environment variables, config files -->
+### When to update
 
-## Conventions
+- After a MAINTAIN run that changed system shape.
+- When a subsystem's mechanism changes meaningfully (not when one file gets renamed).
+- When a verified-wrong assumption is discovered.
+- *Not* every spec; specs already produce reviews and git history. Don't duplicate that here.
 
-<!-- Coding standards, naming conventions, patterns used -->
+### How to update
 
----
+Use the `update-arch-docs` skill. It runs in two modes:
+
+- **diff-mode**: apply a specific change to the smallest section that needs updating.
+- **audit-mode**: read the doc end-to-end against the discipline below and propose cuts with reasons.
+
+The skill edits this file directly via normal file-edit tooling. It does not invoke destructive shell commands; everything goes through Edit. The MAINTAIN PR diff is the human-confirmation step.
+
+### What NOT to put in
+
+The main pressure on this document is unchecked growth. Reject all of the following:
+
+- **Per-file enumerations** that go stale. Document directory shape and key files; let `git ls-files` be authoritative for the rest.
+- **Per-spec changelog sections** ("Spec 0042 added X"). The git log + the spec/review docs own this framing. Architecture is current state, not history.
+- **Specs/plans tables** that mirror `codev/specs/` and `codev/plans/`. Link to the directory; do not paginate it here.
+- **Aspirational state** ("we plan to…"). That's a meta-spec or a roadmap doc, not architecture.
+- **Date-stamped narrative** ("As of 2026-Q2…"). Looks fresh; ages worse than a calendar.
+- **Duplication of meta-spec content**. If a subsystem has a meta-spec, this doc carries a 1-paragraph summary plus a pointer.
+- **Retired-component graveyards**. When a component is removed, delete its section. `git log` keeps the history.
+
+### Sanity-check checklist
+
+Before committing an arch.md change, run through these:
+
+1. Does the section describe **current state**, not aspiration?
+2. Does it duplicate a meta-spec? If yes, replace with a summary + pointer.
+3. Is the section orienting (worth a reader's 30 seconds), or is it exhaustive?
+4. Could a future reader skip this section without losing anything load-bearing?
+5. If audit-mode produced cuts, does each cut have a one-line reason in the MAINTAIN run file?
+6. Does the doc still feel like it can be skimmed end-to-end in under 5 minutes?
+
+### Note on propagation
+
+By design, **`codev init`, `codev adopt`, and `codev update` do not copy framework templates** (including this `arch.md` template) into the consuming project's filesystem. They are framework files that resolve at runtime from the installed `@cluesmith/codev` npm package — see `packages/codev/src/commands/init.ts` and `adopt.ts` (the `// Framework files ... are NOT copied` comments).
+
+To opt into this richer template for a project's *living* `codev/resources/arch.md`, copy it manually:
+
+```bash
+cp $(node -p 'require.resolve("@cluesmith/codev/skeleton/templates/arch.md")') codev/resources/arch.md
+```
 
-*Generated by MAINTAIN protocol. To update: run MAINTAIN or edit directly.*
+(Or, if developing inside the codev repo itself, simply `cp codev-skeleton/templates/arch.md codev/resources/arch.md` and edit from there.)

package/skeleton/templates/lessons-learned.md

@@ -1,28 +1,66 @@
 # Lessons Learned
 
-> Extracted from `codev/reviews/`. Last updated: YYYY-MM-DD
+Engineering wisdom that applies *across multiple specs*, extracted from review documents during MAINTAIN runs.
+
+> **How to read this doc**: Skim by topic section. Each entry is 1–3 sentences and states a general principle. If you need the full story behind a lesson, follow the link to the originating review.
+
+## What goes here, what does not
+
+This file is a sibling to `codev/resources/arch.md`. They have different purposes:
+
+- `arch.md` owns **system shape** — services, transports, mental models, verified-wrong assumptions about *this* system.
+- `lessons-learned.md` owns **durable engineering wisdom** — patterns that apply across specs, projects, and time.
+
+When you have a fact that's specific to one feature, it belongs in that feature's review, not here.
+
+### Add an entry when
+
+- A pattern surfaced in two or more specs/reviews.
+- A failure mode is general enough that future contributors will hit it on unrelated work.
+- A practice was confirmed (the team adopted it after trying alternatives).
+
+### Do NOT add an entry when
+
+- **Spec-narrow recipes** that only matter inside the originating feature. Those belong in the spec's review document.
+- **Multi-paragraph entries**. If a lesson needs more than 1–3 sentences, it is either two lessons or it is documentation that belongs elsewhere.
+- **Duplicate adjacent entries**. Fold variations of the same lesson into one entry.
+- **Spec-numbered narrative** ("Lesson from #0468:…"). Link to the review if useful; state the lesson itself as a general principle.
+
+### Sanity-check checklist
+
+Before adding or keeping an entry, run through these:
+
+1. Is it cross-applicable beyond the spec that produced it?
+2. Is it terse (1–3 sentences)?
+3. Is the topic section the right home? (If "Architecture (continued)" or spec-numbered, move it.)
+4. Is it a duplicate of an adjacent entry? (If yes, fold them.)
+5. Could the lesson be stated as a general principle, independent of the originating feature?
+
+If any answer is "no," either reshape the entry or move it to the originating spec's review.
+
+---
 
 ## Testing
 
-<!-- Lessons about testing patterns, test isolation, mocking, etc. -->
+<!-- Patterns about test isolation, mocking, fixtures, regression coverage. -->
 
 ## Architecture
 
-<!-- Lessons about system design, state management, file organization -->
+<!-- Patterns about system design, state management, file organization. -->
 
 ## Process
 
-<!-- Lessons about protocol execution, consultation, PR workflow -->
+<!-- Patterns about protocol execution, consultation, PR workflow. -->
 
 ## Tooling
 
-<!-- Lessons about CLI tools, dependencies, build systems -->
+<!-- Patterns about CLI tools, dependencies, build systems. -->
 
 ## Integration
 
-<!-- Lessons about external APIs, third-party services, auth -->
+<!-- Patterns about external APIs, third-party services, auth. -->
 
 ---
 
 *Generated by MAINTAIN protocol from review documents.*
-*To add lessons: document them in review files, then run MAINTAIN.*
+*To add lessons: document them in review files, then run MAINTAIN with the `update-arch-docs` skill.*