- STEP 0 collects user-confirmed CANONICAL NAP (LRN-032 zenquality:
duplicated-seed trap — source majority is not truth)
- Both dispatch prompts carry the canonical NAP + no-majority rule;
seo-analyzer spec forbids directional NAP fix without confirmation
- STEP 2 now emits .claude/audits/HUMAN-ACTIONS.md (checklist from §11)
and NAP-KIT.md (local business) in BOTH modes — audit-only runs leave
the user immediately actionable; /client-handover §4 consumes NAP-KIT
tokenstore remove/clear, fetch.sh forget dispatch, and a connect.sh wrapper
that sources ~/.claude/.env internally and runs from any project. /seo now
routes connect|accounts|forget before the audit flow; Makefile seo-connect
delegates to the wrapper. Labels are guarded to shell-safe ASCII (POSIX case,
whole-string, C-locale) as defense-in-depth; forget output states local
removal is not a Google-side revocation.
commit-changer committed code autonomously with no branch precondition
(gitflow-conformity §2a, verified MEDIUM CONFIRMED) — on develop/main it
attempted a direct code commit, backstopped only by the pre-commit hook.
Adds Phase 0: the same `gitflow-aiguillage.md` mechanism hotfixer/bugfixer/
feater already use (TYPE=chore) — branches to chore/* on a protected base,
no-op on a working branch — plus a report-only fallback (no develop / no
lib -> ask human, don't auto-branch). Commit-plan gate + scoped staging
untouched. SKILL.md pre-flight notes the aiguillage.
Dry-run (throwaway repos, REAL lib + REAL pre-commit hook) — both paths:
CASE 1 on develop: aiguillage -> chore/commit-pending, code commit
SUCCEEDS, hook never blocks; contrast: same commit direct on develop
is BLOCKED -> aiguillage is what avoids it. PASS
CASE 2 no develop: fallback -> no auto-branch, changes uncommitted,
no chore/* created, ask human. PASS
lib/deploy-commit.sh: a rejected `git commit` (pre-commit hook,
protected branch, signing failure) now exits 6 (loud stderr, distinct
from rc 1's "nothing to do") instead of sharing rc 1 with the no-op
cases. Header comment documents the full 0/1/2/3/4/5/6 taxonomy.
Closes J4-22 (UNTESTABLE): at client repos, a failed deploy-state
commit was indistinguishable BY EXIT CODE from "nothing to do" (rc 1
was shared 3 ways); exit-code-only callers couldn't disambiguate
(stderr-parsing callers already could).
Caller census (per report's explicit gate): skills/deploy/SKILL.md
documents and parses this exit-code contract in TWO places (bootstrap
commit + incident-recovery commit). Flagged to the user before
committing; confirmed GO to add rc 6 there too (additive — no existing
code's meaning changes) so the documented contract stays accurate for
live deploy runs.
New T10 in lib/tests/deploy-commit.test.sh (+3 assertions, 13→16):
rejecting pre-commit hook sandbox — asserts rc 6, empty stdout (no
stale hash), HEAD unmoved.
GREEN: full `make test` exit 0 (deploy-commit 16/16 incl. T10).
shellcheck clean, bash -n clean.
skills/prune-memory/tests/run-deterministic.sh:11 default changed from
$HOME/.claude/skills/prune-memory/SKILL.md to $HERE/../SKILL.md (kept
the ${SKILL:-…} env override; reordered HERE's definition before it,
since the new default references $HERE). Closes J4-11 (FIXTURE-DRIFT):
the suite sourced the INSTALLED path, safe today only because
~/.claude/skills/prune-memory is a symlinked directory back to this
repo — if an install ever materializes real copies instead of
symlinking, the suite would silently test the wrong (stale) artifact
while the shipped SKILL.md drifts unnoticed.
Behavior identical today (verified: symlink resolves to the same
inode, `diff` confirms byte-identical content).
GREEN: real repo, suite still all GREEN (RED-1/2/5/6/7).
Red demo (lean scratch copy — skills/prune-memory/{SKILL.md,tests/
run-deterministic.sh} only): moved $HERE/../SKILL.md away → loud
`grep`/`awk: cannot open ... No such file or directory` errors, exit
1, RED-2/RED-5 flip status — proves the new default is genuinely what
gets read, not a silent fallback.
Deleted T4e + its coupled echo note in lib/tests/run-reconcile.sh and
the fixtures/real-state.snapshot it read — superseded by SPEC-08's T7,
which actually DRIVES the tree_clean/pushed/msg_committed oracles
instead of miming them via a static line-count regex. Closes J4-09
(WEAK+drift): T4e only counted fixture line-suffixes matching
`=(true|resolved|present)$`; the snapshot itself was stale
(BLK-009=open contradicted blockers-snapshot.md's already-resolved
status) and unowned, and the drift was inert (`=open` doesn't even
match the count regex) — the assertion could never have caught
anything.
Updated skills/reconcile/SKILL.md:53's hardcoded "20/20" claim to the
new total (unguarded file, same logical step, ordered after SPEC-08+
SPEC-10 per the report).
grep -c 'real-state.snapshot' lib/tests/run-reconcile.sh == 0
(verified). No red demo (deletion, per spec) — gate is the green run
+ that grep. GREEN: 25/25 passed, shellcheck clean.
Both sections never matched any component (envelope §1-§9 vs the real
§0-§15 structure; 8-axis integer weights vs the agents' 7/4 and 6/5
percentage-weight scoring). Kept what this file legitimately owns: the
depth-decision matrix and the sibling-skill dedup rules.
- A1: delete STEP 5d (graphify --mode quick doesn't exist in the CLI; the
command always failed, masked by `|| true` — STEP 10's full pass already
covers the graph)
- A2: STEP 10 full-pass build flag --output -> --out
- A8: pipeline is 12 steps (STEP 0-11), not 11; header template unchanged
(N/11 correctly denotes the max index of a 0-indexed 12-step sequence)
- A2: graphify build flag --output -> --out
- A4: ROADMAP xref points to the real /onboard add gsd path, not a nonexistent STEP 9 decision
- A5: exact gitflow init commit message (matches lib/gitflow.sh:163)
- A6: bare skill names (design-review, browse) — no gstack: namespace exists
- A7: eval pattern for recommend_anim_install_cmd (the function only echoes; must eval its output)
Live failure (run 2): the checklist printed above AskUserQuestion never
reached the user. Fix is structural: the checklist is never written to a
file (throwaway — PENDING.json + live runbook regenerate it in any
session) and every hand-back/re-display ends the turn with the full
checklist as the FINAL text, no tool call after it. Cold resume without a
report regenerates + re-displays. Artifacts 5 -> 4 files; bootstrap
gitignore step drops NEXT.sh; mistakes/red-flags updated (no tool call
after the print, no file 'for reference').
Generator-owned files updated by the out-of-band 'make plugin' run
(SKILL.md, extraction-spec, query reference, version marker). Committed
deliberately after diff review; CHANGELOG Unreleased notes the bump.
First-real-run UX feedback (EVAL-016): one command per line as typed in an
interactive session (ssh opens the box, following lines run on it, local
steps flagged), never folded ssh compounds; the hand-back prints the full
checklist in the conversation (and every re-hand-back reprints it). Step
defined as a block (header + command lines to next blank line), @delta
governs the block. Template restyled to match.
ship-feature: STEP 0e CONTRACT (request verbatim) → ENRICHED at the STEP 3
validation gate (design criteria appended [gated <date>], the human
micro-gate) → STEP 5 VERIFY+SECURE judges the branch against the ENRICHED
contract via the shared include. Distinct axis from STEP 6 code review, both
run (LRN-095).
init-project: contract seeded from the PROJECT BRIEF (V1 features → criteria)
→ ENRICHED at VALIDATION GATE #1 → STEP 9 VERIFY+SECURE. Adds the security
gate init-project previously lacked (was deferred to a later /onboard).
onboard: explicit NO verify-loop — it produces an audit report, not a change
to verify against a request; contract is scope-only, security-auditor runs
MODE audit (report-only), never a gate. Documented to prevent a misplaced
symmetry loop (BDR-050: dev pipeline != audit).
lib/tests/no-vacuous-locks.test.sh: deterministic backstop for LRN-093 (2nd
recurrence in this chantier → the advisory alone did not hold). Refuses a
literal \n in any grep/tf/tr_/tn pattern across lib/tests/*.test.sh;
flip-tested against a synthetic offender so the guard proves it bites.
lib/tests/loops-heavy.test.sh: 18 structure locks green.
Behavioral dogfood (both vigilance points, real): (1) enrichment — a fresh
verifier reads and checks a [gated] design criterion (ECARTS naming it
precisely); (2) escalation — 3 consecutive ECARTS on the same criterion →
orchestrator STOPs at the max-3 bound + presents the CONTRACT-vs-REALIZED
table, no 4th loop, no commit. First real exercise of the infinite-loop guard.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpphkdTosUzokBDNG7PToS
lib/verify-secure-loop.md: shared main-loop include. GATE 1 fresh verifier
(blind, contract from disk) → CONFORME straight to GATE 2, ECARTS loop max
3; GATE 2 fresh security-auditor (MODE gate) → PASS to commit, BLOCK loop
max 3 with re-verify-request-FIRST order invariant. Mute agent never a PASS.
feater.md: STEP 0.7 CONTRACT (proportional, silent on a clear feature) +
STEP 3 VERIFY+SECURE via the include. Nominal = one verifier + one security
dispatch; the loop only costs when it loops.
bugfixer.md: STEP 3.5 CONTRACT fed by the DIAGNOSIS (bug report verbatim +
reproduced-then-gone + regression test criteria) + STEP 5 fresh gates via
the include. Renumbered STEP 5 sub-steps (gates before the commit gate).
hotfixer.md: STEP 1.7 CONTRACT (silent autofill, zero questions) + STEP 3
security gate whose FAILURE REVERTS (git restore to pre-flight SHA + escalate
to /bugfix), never loops — the 1-attempt model preserved. No fresh verifier
at hotfix weight (the smoke-check verifies the trivial contract). Adds the
Agent tool to hotfixer.md + hotfix/SKILL.md for the security dispatch.
lib/tests/loops-light.test.sh: 27 structure locks green, shellcheck clean.
Behavioral pipeline dogfood on a fixture (feat adding a feature WITH a SQLi):
GATE1 CONFORME (feature present, SQLi not a conformity gap — orthogonal
gates) → GATE2 BLOCK(1) (checklist caught the %-interp SQLi semgrep's taint
rules missed) → [fix to parameterized] → re-verify CONFORME (order invariant,
feature intact) → re-scan PASS. Loop converges to green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpphkdTosUzokBDNG7PToS
agents/security-auditor.md: fresh read-only-on-code SAST gate. Pinned
rulesets p/security-audit + p/secrets + p/owasp-top-ten (owasp REQUIRED —
measured: the 2-ruleset baseline misses SQLi + path-traversal entirely on
realistic Flask code), never --config auto, never auto login (BDR-048).
Severity map: secrets ERROR → CRITICAL, other ERROR → HIGH (block),
WARNING/INFO → reported. gate mode (diff, no Write) vs audit mode (Write
only to REPORT, rule-locked). DEGRADED (semgrep absent) still runs the
checklist and still blocks — never a vacuous pass (LRN-048). Anti-gaming:
a new un-gated nosemgrep suppression is BLOCKING. PROOF mandatory, mute
auditor never a PASS, blind (no iteration history), blocks HIGH/CRITICAL
only (LRN-047).
Grafts: onboard STEP 6 L3a dispatches it in audit mode (report
.onboard-audit/semgrep.md) in BOTH gstack branches — complement to cso
(cso is a gstack submodule, unmodifiable); synthesis picks it up via the
existing .onboard-audit/ sweep. audit-delta security axis runs the SAST
pass first, folds findings into the existing gate/fix/re-verify flow.
lib/tests/security-auditor.test.sh: 28 structure locks green, shellcheck
clean. Behavioral dogfood (fresh agents on a planted fixture):
BLOCK(9) on the vuln commit (2 secrets→CRITICAL, semgrep+checklist
complementarity — checklist caught the 6 semgrep missed off-context);
BLOCK(1) on a new nosemgrep suppression (understood semgrep's 0 was the
mask); DEGRADED → BLOCK(7) on grep-detectable secrets with semgrep hidden.
FP measured on real repos (faunosteo, game): owasp adds only hygiene
findings, contained by diff-scoping.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpphkdTosUzokBDNG7PToS
Standalone /capitalize /close /prune-memory /reconcile no longer lean on the .claude/** hook exemption when run on main/develop: the aiguillage branches them to chore/* off develop before writing. New chore type (base develop, finish->develop) added to the lib; hook unchanged (chore/* non-protected). Closes the leak where standalone memory work (memory IS the work, no code branch to follow) landed direct on a protected base. 64/64 gitflow-test green, shellcheck clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RNaYKPEkjH1jbgoX1TwKMX
/release-candidate cuts a release by orchestrating the existing gitflow
release mechanic (start from develop; finish fan-out main+develop+delete)
and adding the one piece the lib lacks: the version tag.
- skills/release-candidate/SKILL.md: thin orchestrator — preconditions →
gitflow start release → prep (version.txt + CHANGELOG, breaking doc'd) →
run-tests gate → human WHEN-to-release gate → gitflow finish → git tag -a
vX.Y.Z (in the skill, lib untouched) → push (gated).
- lib/tests/run-release-candidate.sh: throwaway-repo flow replay. RC_TAG=0
reds the tag (gitflow fans out but never tags); RC_TAG=1 → 5/5.
- CLAUDE.md: Skill routing line. CHANGELOG [Unreleased]: /reconcile +
/release-candidate under Added (so the eventual v4.0.0 captures them).
Tag scheme vX.Y.Z continues the version.txt/CHANGELOG lineage. writing-skills TDD.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C6bUdvHnajCNzgVQefZowj
/reconcile confronts declarative sources (TODO checkboxes, registry
statuses, ## Index) against real git/fs state and surfaces the gaps,
in 4 categories + contradiction candidates.
- lib/reconcile.sh: engine — body-only enumeration (never the Index),
git/fs oracles, BLK last-block-wins status, lexical deferral sweep,
contradiction candidates, pure reconcile_verdict kernel.
- lib/tests/run-reconcile.sh + fixtures (neutral-named): 20/20;
recursive-coherence T1 reds if the engine reads the Index (teeth).
- skills/reconcile/SKILL.md: thin orchestration + A/B/C write-back gate,
honest limits (lexical deferrals, contradictions surfaced not asserted).
- CLAUDE.md: Skill routing line.
Founding principle: never trust a declarative source as an oracle — the
skill practices what it preaches (tested). Built via writing-skills TDD.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C6bUdvHnajCNzgVQefZowj
RED-7 (example-priming): the STEP-2 worked example named live IDs (LRN-014 +
LRN-016) and modeled merging them — but they are complementary (header-ids vs
checkbox-CSS), a merge the skill's own rule forbids. Live IDs in an example prime
the skill to act on those exact entries on real data. Fictionalized the whole
STEP-2 example to 9xx IDs (cannot match a live registry); the merge example now
models a same-concept merge. Closed by a DETERMINISTIC test (run-deterministic.sh
RED-7: the example must carry only 9xx ids) per LRN-046, not a flaky behavioral
fixture. The test caught its own ugrep false-green first (a leading-dash pattern
parsed as an option) — fixed via /usr/bin/grep, the same dodge the skill's verify
already uses at line 189.
RED-8 (added-negation inversion): re-reviewed, consciously accepted as a documented
limit in BACKLOG — remote (compression subtracts tokens), and an FP-safe increase
check is non-trivial (needs the HEAD entry-id set to exclude legit new/merged 0->N);
a noisy guard is worse than the honest limit on a destructive skill (LRN-047).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C6bUdvHnajCNzgVQefZowj
STEP 12 ran `gsd init` AFTER FINISH, creating ROADMAP.md + .gsd/ in the working
tree once the merge had already integrated committed history only — so the
artifacts stranded outside the merge/PR (BLK-011, 3rd post-FINISH artifact after
memory + docs).
Resolved by REMOVAL, not by plumbing a commit: STEP 12 speculatively bootstrapped
a heavy multi-session engine (state machine / crash recovery / cost tracking /
parallel workers) that is opt-in and rarely used. Deleting the producer means the
orphan is never created — a negative diff beats building a gsd-commit helper for an
artifact nobody commits to using.
Deliberate GSD use is untouched: initializable on-demand (`/onboard add gsd`, or
`gsd init` in a terminal), still recommended by plugin-advisor, still read by
/status. init-project is now an 11-step pipeline.
Coherence sweep (the "test" for a removal): zero dangling STEP-12 refs — header
12->11-step, the STEP 10c note, and 4 USAGE.md worked-example references all updated
to on-demand init.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C6bUdvHnajCNzgVQefZowj
/capitalize + /close predated lib/capitalize-commit.md and never called it, so
a standalone flush left memory written but uncommitted (BDR-037). Add STEP 5B:
after the content gate (STEP 3) approves entries and STEP 5 writes the journal,
commit them surgically via memory-commit.sh — same one-liner as the 6 dev flows.
/close is a thin alias, inherits it for free. Journal always writes => memory
always pending at 5B => hash non-empty by construction (only rc 3 skips).
Reorder: SYNC README moves from STEP 12 (post-FINISH) to STEP 10c (after 10b capitalize, before 11 FINISH) and gains lib/doc-commit.md; GSD 13 → 12. Final order: 10b capitalize -> 10c doc-sync -> 11 FINISH -> 12 GSD — both artifact-commits (memory, docs) land before FINISH, so they reach the merge/PR (twin of the ship-feature fix, BDR-034). Partial-fix note added: scaffold + STEP 5b bootstrap-README commit gap (BLK-010) and GSD-post-FINISH ROADMAP (BLK-011) are deliberately out of scope — separate chantiers.
Ref-coherence (the swap flips STEP 12's meaning SYNC-README -> GSD and removes 13, so refs by number must move, not just a vanishing number): PROGRESS PROTOCOL 13-step -> 12-step + STEP <N>/13 -> /12. USAGE.md: 5 refs corrected (table 12-13 -> 11-12 steps; pipeline illustration reworked so sync README shows BEFORE finish; 3 GSD-as-STEP-13 refs -> STEP 12). Each USAGE ref read individually post-swap — all were correct at 13, correct at 12 after fix, none accidentally-true/silently-false. Latent-bug check: init-project had NO stale ref from the capitalize chantier (STEP 10b was a non-shifting letter insertion, not a swap). Historical records (BDR-017 '13 steps', CHANGELOG STEP 13 GSD, BLK-011) left as-is — append-only; closing entry documents the renumber.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ho5EQCFTSvYamuRtVZpp2d
Reorder: DOC SYNC moves from STEP 9 (post-FINISH) to STEP 8 (pre-FINISH); FINISH → 9. doc-syncer PATCHES public docs but never commits them, and finishing-a-development-branch integrates only committed history — so on the push+PR path the patched docs were uncommitted and never reached the PR (twin of the capitalize PR-strand fix, BDR-034). STEP 8 now chains lib/doc-commit.md: surgical commit of the PATCHED_FILES, never git add -A, never .claude/ (rc 4 loud anomaly), no-op if nothing patched. Twin-chantier HTML comment removed — the twin is fixed, 'deferred' is now false.
Ref-coherence (part of the reorder — a swap flips meanings, it doesn't just drop a number): STEP 7 capitalize body refs 'STEP 8 FINISH' → 'STEP 9 FINISH' (lines 159, 189). README.md pipeline illustration completed — STEP 4-7 ends in capitalize (not 'finish'), STEP 8 = sync README, STEP 9 = finish; it had been silently wrong since e8eff7e moved DOC SYNC 8→9 without updating it, so completed rather than left accidentally-correct. Historical records (BDR-034, journal, CHANGELOG) left as-is — they said 'STEP 8' when it was true; append-only.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ho5EQCFTSvYamuRtVZpp2d
Shared include lib/analyze-before-plan.md (two-pass on '## <PREFIX>-' headings, disposition-not-reading invariant, guarded no-op). Wired into the dev flows: ship-feature STEP 0d (analyzer code+memory, INPUT INJECTION into brainstorm/plan + STEP 3 reconciliation gate), bugfix STEP 2.5 (blockers-first), feat STEP 0.6 (decisions-first, MINI-PLAN names in-force or states none), hotfix opt-in. analyzer gains a RELATED MEMORY output section pointing at the include (DRY). init-project / onboard no-op by construction (guarded scan on absent/empty registries).
Mirror of the coupled-capitalize write-after (BDR-034): read-before / write-after bookend.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ho5EQCFTSvYamuRtVZpp2d
Bastien Chanot