From 9f800ffc09e10b63d926a47afdf0e88ea9f9ef86 Mon Sep 17 00:00:00 2001 From: Franco Arza Date: Tue, 7 Jul 2026 11:53:22 -0300 Subject: [PATCH] feat(v12.2.0): shadcn/improve folds, first /harvest run, CC v2.1.202 sync MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three-part batch, no new skills (library stays 37/40): shadcn/improve folds (4 mechanics, skill not adopted — audit surface already owned by adversarial-audit/nuclear-review/review): - plan stamps + reconcile pass (project, orchestrate) - expected-output done criteria + escape hatches (implementer briefing contract) - untrusted-diff rule (review-batch) - considered-and-rejected ledger (adversarial-audit, nuclear-review) First live /harvest run, from two 2026-07-06 programa transcripts (both independently exhibited the top procedure); all three folds trap-validated 4/4 with blind subagents: - verify subagent claims independently (orchestrate) - when CI goes red: reproduce locally, canonical bump scripts, read .conclusion explicitly (ship) - commits named in a bug report are hypotheses; blame first (fix) Claude Code v2.1.202 sync: docs-only — /review reverted to fast single-pass (MANUAL.md note), manifest bump. Dynamic-workflow-size setting is config-state, not a settings.json key; no schema surface. --- .claude-plugin/plugin.json | 2 +- CHANGELOG.md | 19 ++++++++++++++++++ CLAUDE-FULL.md | 2 +- MANUAL.md | 2 +- agents/implementer.md | 7 +++++-- skills/adversarial-audit/SKILL.md | 1 + skills/fix/SKILL.md | 2 +- skills/nuclear-review/SKILL.md | 3 +++ skills/orchestrate/SKILL.md | 26 +++++++++++++++++++++++++ skills/project/SKILL.md | 31 ++++++++++++++++++++++++++++-- skills/review-batch/SKILL.md | 2 ++ skills/ship/SKILL.md | 8 +++++--- src/setup.ts | 2 +- upstream/claude-code-manifest.json | 4 ++-- 14 files changed, 97 insertions(+), 14 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 93ab11a..63b9ab8 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "name": "darkroom", "displayName": "Darkroom Engineering", "description": "Darkroom Engineering AI coding standards. Layered config with portable AGENTS.md, progressive complexity, and two-tier knowledge system.", - "version": "12.1.0", + "version": "12.2.0", "author": { "name": "Darkroom Engineering", "url": "https://darkroom.engineering" diff --git a/CHANGELOG.md b/CHANGELOG.md index b9afd97..a374921 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,25 @@ All notable changes to cc-settings are documented here. > **Versioning** — cc-settings uses a single version number matching the installer (`src/setup.ts` `VERSION` constant, written to `~/.claude/.cc-settings-version` sentinel). Historical entries below 10.0 predate this unification; the jump from v8.x to v10.x in April 2026 realigned the product version with the installer version that was already ahead. +## [12.2.0] — 2026-07-07 + +Three-part batch: shadcn/improve folds, first real `/harvest` run, and the v2.1.202 upstream sync. + +**Harvested from production transcripts** (first live run of the `/harvest` skill, v12.1.0 — evidence: two programa sessions from 2026-07-06, both independently exhibiting the top procedure): + +- **Verify subagent claims independently** (`orchestrate`) — a subagent's "done" is a claim: re-run its briefed verification against the real artifact; check its capability envelope (a no-Bash implementer zeroed files instead of deleting them and still reported done); fix-solo vs re-delegate rule for breaks found during verification; SendMessage-resume cut-off agents instead of respawning. +- **When CI goes red** (`ship` Step 9) — reproduce the exact failing guard locally against the real built artifact before re-pushing; canonical bump scripts over hand-edited version fields; never trust a watcher pipeline's exit code — read `.conclusion` explicitly. +- **Blame before blaming** (`fix` Diagnose step) — commits named in a bug report are hypotheses; blame the affected file's history first (the transcript's "regression" predated all three accused commits). + +**Sync with Claude Code v2.1.202:** docs-only. `MANUAL.md` `/review` note updated (v2.1.202 reverted native `/review ` to fast single-pass; multi-agent review only via `/code-review `); manifest bumped. The new "Dynamic workflow size" `/config` setting is config-state, not a `settings.json` key — nothing for the strict schema to adopt; all other 2.1.202 entries are behavioral fixes with no cc-settings surface. + +Folds from reviewing `shadcn/improve` (audit-to-plans skill; same intelligence-plans/cheap-execution philosophy as our quota routing). No new skill adopted — its audit surface is already owned by `/adversarial-audit` + `/nuclear-review` + `/review`, its executor isolation by `isolation: worktree`, its false-positive vetting by disprove-before-reporting. Four mechanics folded instead: + +- **Plan stamps + reconcile** (`project`, `orchestrate`) — plans/issues record the commit SHA they were written against; a reconcile pass re-runs done-criteria of completed tasks (a "done" that no longer verifies gets reopened), refreshes drifted file/line refs, and retires obsoleted tasks with a reason. Kills silent plan drift. +- **Expected-output done criteria + escape hatches** (`agents/implementer.md` REQUIRED BRIEFING items 4/6, CLAUDE-FULL briefing contract) — verification commands must state what success looks like (machine-checkable, never "works correctly"); briefings state the conditions to STOP and report back instead of improvising. +- **Untrusted-diff rule** (`review-batch`) — verbatim posture adopted: verify every hunk traces to a step in the task that produced it; reject out-of-scope changes however plausible they look. +- **Considered & rejected ledger** (`adversarial-audit` output §6, `nuclear-review` output format) — disproved candidate findings get recorded with a one-line reason so future audits check the ledger instead of re-litigating. + ## [12.1.0] — 2026-07-07 New skill: `harvest` (36 → 37 skills, cap 40) — captures an unusually good workflow (from a stronger or temporary model, a one-off session, or a teammate's transcript) into a durable, reviewed artifact instead of losing it when the session or model access ends. Six phases: identify what's harvestable (repeatable procedure, not raw intelligence — "the model was smarter" is explicitly not harvestable), gather evidence via interview or transcript analysis, extract four components (procedure / failure modes / quality bar / self-tests), route to the smallest artifact that carries it (skill, rule, profile section, AGENTS.md diff, or `/share-learning` note), write it per the target's own conventions, then validate with 2–3 blind trap prompts (autoresearch's blind-run rule; the traps seed a later `/autoresearch` eval set). Hard approval gate before touching shared standards (AGENTS.md, rules/, profiles/), posting team knowledge, or committing. Explicit non-goals: no model-API sampling, no "operating manual" prose output. diff --git a/CLAUDE-FULL.md b/CLAUDE-FULL.md index 21f0646..4084e7d 100644 --- a/CLAUDE-FULL.md +++ b/CLAUDE-FULL.md @@ -46,7 +46,7 @@ Before each unit of work, ask once: **3+ files, 10+ tool calls, or security-sens 3. **Delegating needs no narration** — just call the Agent tool. 4. **Parallelize**: independent delegations go in a single message — they run concurrently. -> **Briefing contract for `implementer`**: as a subagent it gets only your prompt — no conversation context, none of the files you've read — so every prompt MUST contain actual content, not references: the user's ask verbatim, exact file paths and line ranges, the change to make (paste the planner output; never write "based on findings" or "according to plan"), the verification command, and a scope boundary. Thin prompts cause regressions; the agent will refuse them. It runs in the live working tree and leaves changes **uncommitted** for you to review before they land. Full contract: `agents/implementer.md` REQUIRED BRIEFING. This applies equally to `explore` → `implementer` and `planner` → `implementer` chains. +> **Briefing contract for `implementer`**: as a subagent it gets only your prompt — no conversation context, none of the files you've read — so every prompt MUST contain actual content, not references: the user's ask verbatim, exact file paths and line ranges, the change to make (paste the planner output; never write "based on findings" or "according to plan"), the verification command with its expected output (machine-checkable, never "works correctly"), a scope boundary, and any escape hatches (conditions to STOP and report back instead of improvising). Thin prompts cause regressions; the agent will refuse them. It runs in the live working tree and leaves changes **uncommitted** for you to review before they land. Full contract: `agents/implementer.md` REQUIRED BRIEFING. This applies equally to `explore` → `implementer` and `planner` → `implementer` chains. For full orchestration mode, activate `profiles/maestro.md`. Model routing per agent: see `docs/agent-models.md`. diff --git a/MANUAL.md b/MANUAL.md index 3a8c413..4064830 100644 --- a/MANUAL.md +++ b/MANUAL.md @@ -154,7 +154,7 @@ Triggers `/refactor` — explore → plan → implement → test → review. Pre Say: *"rewrite this as if from scratch"* or *"delete the compat layer"* or *"too many flags"* -Triggers `/zero-tech-debt` — rework a patch from the intended end-state, not from the historical path. Deletes compatibility cruft and mode flags no one calls. Sibling to `/refactor` (out-of-diff restructuring) — this one targets the patch in front of you. (Note: Claude Code 2.1.147 renamed native `/simplify` to `/code-review`, dropping the cleanup-and-fix behavior. As of 2.1.186, native `/review ` runs the same engine as `/code-review medium`.) +Triggers `/zero-tech-debt` — rework a patch from the intended end-state, not from the historical path. Deletes compatibility cruft and mode flags no one calls. Sibling to `/refactor` (out-of-diff restructuring) — this one targets the patch in front of you. (Note: Claude Code 2.1.147 renamed native `/simplify` to `/code-review`, dropping the cleanup-and-fix behavior. As of 2.1.202, native `/review ` is back to a fast single-pass review; the multi-agent engine is only via `/code-review `.) --- diff --git a/agents/implementer.md b/agents/implementer.md index 207bb01..26e6c48 100644 --- a/agents/implementer.md +++ b/agents/implementer.md @@ -16,8 +16,11 @@ description: | your prompt, with none of the conversation context or files you've already read 3. The specific change to make — paste the planner output or quote the recommended fix line-by-line. Never write "based on findings" or "according to plan" - 4. The verification command (e.g. `bun test`, `npm run build`, repro steps) + 4. The verification command AND its expected output (e.g. `bun test` → exit 0, + all pass) — machine-checkable results, never prose like "works correctly" 5. Scope boundary — which adjacent code is OFF-LIMITS + 6. Escape hatches — the conditions under which to STOP mid-task and report + back instead of improvising (e.g. "if the types don't line up, stop") Thin prompts ("implement based on plan", "fix the bug", "build it") cause regressions. @@ -43,7 +46,7 @@ prompt you received against this checklist: - [ ] Specific file paths to modify (not "the codebase", not "from prior agent output") - [ ] The concrete change to make (the actual fix or refactor steps, not a reference like "according to plan" or "based on findings") -- [ ] A verification command (test, build, or repro) +- [ ] A verification command with its expected output (test, build, or repro — and what success looks like) If any item is missing, **STOP and report back** — do not start work, do not guess, do not infer from agent memory. Reply with exactly: diff --git a/skills/adversarial-audit/SKILL.md b/skills/adversarial-audit/SKILL.md index 36ba4e3..07a7c62 100644 --- a/skills/adversarial-audit/SKILL.md +++ b/skills/adversarial-audit/SKILL.md @@ -40,6 +40,7 @@ Run codebase mode on the same cadence as nuclear-review (version cuts, post-spri 3. Findings by hunt category, severity order. Each: stable ID (H1/M1/L1 by severity, or C/D/P prefix per mode), location, one-line issue, concrete scenario, status, recommended direction. 4. Design tensions: the 3-5 deepest structural issues ("the approach, not a line"), each with the alternative you'd weigh. 5. Open questions: what the artifact alone can't resolve — maintainer answers required. +6. Considered & rejected: candidate findings you investigated and disproved (or reclassified as by-design), each with a one-line reason. This ledger is what stops the next audit from re-litigating them — check it before hunting. Chat reply = exec summary only: counts by severity + top 3-5 findings + report path. diff --git a/skills/fix/SKILL.md b/skills/fix/SKILL.md index 473387a..dd83950 100644 --- a/skills/fix/SKILL.md +++ b/skills/fix/SKILL.md @@ -19,7 +19,7 @@ You are in **Maestro orchestration mode**. Delegate immediately to specialized a 1. **Explore** - Spawn `explore` agent to understand the affected codebase area 2. **Reproduce** - Spawn `tester` agent to create a failing test if possible -3. **Diagnose** - Analyze findings to identify root cause +3. **Diagnose** - Analyze findings to identify root cause. Commits named in the bug report are hypotheses, not conclusions — blame the actually-affected file's history before fixing; regressions often ride in earlier on the same branch as the change that got blamed 4. **Implement** - Spawn `implementer` agent to fix the issue 5. **Verify** - Spawn `tester` agent to confirm the fix 6. **Learn** - If this was a non-obvious fix, the auto-memory system in `~/.claude/CLAUDE.md` captures it; for team-wide gotchas use `/share-learning` to post to the team-knowledge repo diff --git a/skills/nuclear-review/SKILL.md b/skills/nuclear-review/SKILL.md index 9a6e996..0b27e47 100644 --- a/skills/nuclear-review/SKILL.md +++ b/skills/nuclear-review/SKILL.md @@ -312,6 +312,9 @@ make findings executable by fixing agents): ## Documented / By-Design (verify still current) - [Findings that contradict a team-knowledge decision — escalated for team discussion, NOT auto-fixed. Cite the note; flag if the decision looks stale.] +## Considered / Rejected +- [Candidate findings investigated and disproved, one-line reason each — the ledger future reviews check first so disproved findings aren't re-litigated.] + ## Notes - [Smaller maintainability concerns worth flagging] ``` diff --git a/skills/orchestrate/SKILL.md b/skills/orchestrate/SKILL.md index 0073045..ca5d02a 100644 --- a/skills/orchestrate/SKILL.md +++ b/skills/orchestrate/SKILL.md @@ -35,6 +35,30 @@ The Maestro agent handles: agent selection, parallel execution, workflow coordin For simple delegation (1-2 agents), use Agent() directly without invoking this skill. +## Verify Subagent Claims Independently + +A subagent's "done" is a claim, not a result. Before building on it, committing, +or reporting success: + +1. **Re-run the briefed verification yourself** against the real artifact — + the actual build, the actual binary's output, the actual grep sweep. Never + forward a subagent's self-reported pass as your own verification. +2. **Check the capability envelope.** Subagents may lack tools you assume + (a no-Bash implementer cannot run builds or delete files — it will + improvise, e.g. zeroing a file instead of removing it, and still report + done). Read what the agent *says it couldn't do*, then absorb the gap + yourself: run the deletion, the build, the test. +3. **Re-delegate vs fix solo.** A trivial break found during verification + (single file, few lines) — fix it solo with a one-line stated reason; + round-tripping to a fresh subagent costs more than the fix. Anything that + adds scope goes back out as a new, fully-briefed delegation. +4. **Resume, don't respawn.** If a subagent's report was cut off or is + missing a section, SendMessage the same agent to finish — a respawn + rebuilds its context from nothing and re-does paid work. + +Failure mode this section exists to prevent: chaining on an unverified "done" +and discovering three phases later that the build never ran. + ## When to Fan Out (Teams mode) Use full parallel team fan-out instead of sequential subagent delegation when: @@ -110,6 +134,8 @@ Save checkpoints at these milestones: A completed phase is a **commit checkpoint, not a stopping point** — the job is the whole plan, not the first green milestone; finishing a phase means starting the next, and you only hand back to the user on a genuine blocker. On long runs, spend one pass every few phases on maintenance before drift accumulates: prune plan bloat (tasks that no longer match what the code taught you), refresh the live handoff so a cold resume lands cleanly, delete dead TODOs, and reconcile the plan with the current architecture rather than preserving development-only shims the plan predates. +Stamp the plan with the commit it was written against (`git rev-parse --short HEAD`) and re-stamp on every maintenance pass. The reconcile semantics: re-run the done-criteria of tasks marked complete (a "done" that no longer verifies gets reopened, not trusted), refresh file/line refs that drifted since the stamp, and retire tasks obsoleted by intervening changes with a one-line reason so they aren't re-litigated later. + #### Checkpoint Contents See `hooks/checkpoint.md` for the full checkpoint JSON schema, storage location, and recommended checkpoint threshold actions. diff --git a/skills/project/SKILL.md b/skills/project/SKILL.md index 10b4135..0400cf3 100644 --- a/skills/project/SKILL.md +++ b/skills/project/SKILL.md @@ -92,12 +92,12 @@ gh project item-list PROJECT_NUM --owner ORG --format json When the user describes a feature or task: ```bash -gh issue create --title "feat: description" --body "$(cat <<'EOF' +gh issue create --title "feat: description" --body "$(cat <