Capitalize the install-self-sufficient / gstack-on-demand session:
- BDR-030: gstack skills activated on-demand per profile, OFF by default.
- LRN-042: npx skills add / setup resolve target relative to CWD — run
from $HOME or artifacts land in the repo tree, unreachable by link.sh.
- journal 2026-06-23 line + TODO task block reconciled.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0169vjUD1sP9Nx4ZiCa8wvAw
gstack stays OFF by default (no per-skill symlink in skills/, zero context
cost). enable_skill now gains a gstack branch: a skill absent from skills/
and skills-disabled/ but present in the skills-external/gstack submodule is
symlinked in on demand when a profile lists it; disable_gstack_not_in()
parks it again on an unrelated profile.
This makes `set full` (which lists 35 gstack skills) work without 35 bogus
"missing — try: bash link.sh" warnings, without abandoning the OFF-by-default
policy. The old remedy message was wrong (link.sh never creates gstack
skills) and is replaced with submodule-aware messages.
Refs BDR-030.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0169vjUD1sP9Nx4ZiCa8wvAw
Two root causes found via the install log (install-20260623-181416.log):
A. install.sh runs link.sh BEFORE install-plugins.sh, and install-plugins
never re-linked, so npx/external skill symlinks were missing on a fresh
run. Add a final Step 10 that re-runs link.sh (idempotent), so
`make plugin`/`make install` finish with nothing left to link by hand.
B. `npx skills add` resolves its target (.agents/skills, skills-lock.json)
relative to the CWD. Run from the repo (which carries gitignored .agents/
and .claude/), skills landed in $REPO/.agents/skills instead of
$HOME/.agents/skills where link.sh looks — self-reinforcing once
$REPO/.agents exists. Run `skills add` from $HOME in both install and
update paths, and clean the stray repo-local skills dirs (gitignored,
safe to rm).
Refs LRN-042.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0169vjUD1sP9Nx4ZiCa8wvAw
Bump 0.8.13 -> 0.8.45. Extract the SKILL.md monolith (~530 lines) into
references/ for progressive disclosure: github-and-merge, transcribe,
extraction-spec, exports, update, query, add-watch, hooks. SKILL.md now
points to each reference and loads it only on the path that needs it.
Inline fixes carried by the new version: empty-extraction guard before
any write (#1392), shrink-guard ordering so GRAPH_REPORT/analysis never
describe a graph.json that was refused (#479), root= relativization for
build/manifest parity across clones (#1361/#1417), stale-cache cleanup
and code-only semantic pre-write (#1392), edge-direction preserving
merge (#801). Adds FalkorDB export (--falkordb/--falkordb-push) and
rewrites the frontmatter description (drops the obsolete trigger: field).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0169vjUD1sP9Nx4ZiCa8wvAw
Effort is set in settings.json ("effortLevel": "xhigh") — the source of
truth. The CLI alias `claude --effort max` was redundant and, worse, would
OVERRIDE settings.json (forcing max over xhigh). Step 9 no longer adds it and
now strips it (and the older CLAUDE_EFFORT env) from the shell profile if
present, cleaning orphaned comment lines.
(A dtach `cc` launcher was prototyped here and dropped — deferred to a later
sprint per the user.)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyNYwD4UccVw9ZCFZyJX55
The magic check + link_env grep'd `^MAGIC_API_KEY=` on $REPO/.env, but on a
fresh machine ~/.claude/.env is often created AFTER link.sh runs, so the
repo/.env symlink (which toggle-external.sh sources) is never made — the key
looks absent though it's set, and the warning misleadingly points at
~/.claude/.env.
- install-plugins.sh: self-heal — if ~/.claude/.env exists but repo/.env is
missing, create the symlink before checking. Accurate message.
- Both: tolerate optional `export ` + leading whitespace and require a
non-empty value (regex sanity-tested), so common .env formats match.
Immediate fix for an affected machine: `make link`.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyNYwD4UccVw9ZCFZyJX55
Two OS-too-new layers blocked gstack's browser on Ubuntu 26.04; handle both
from the installer so a fresh `make install` works without manual steps:
1. Playwright version — gstack pins 1.58.x which has no browser build for
ubuntu>24.04 ("does not support chromium on ubuntu26.04"). New
gstack_bump_playwright_if_unsupported() runs before ./setup: if the
pinned Playwright's support list lacks the running distro, `bun add
playwright@latest` in the submodule (1.61 supports 26.04), then ./setup's
frozen-lockfile install picks it up and rebuilds the browse binary against
it. Idempotent (skips when already supported). Edits the submodule locally
— goes dirty, reset by `git submodule update`, re-applied next install.
2. Chromium sandbox — Ubuntu 24.04+ restricts unprivileged user namespaces
via AppArmor, so Chromium aborts "No usable sandbox". Persist gstack's
documented opt-out GSTACK_CHROMIUM_NO_SANDBOX=1 to the shell profile, gated
on the exact sysctl (kernel.apparmor_restrict_unprivileged_userns=1) so it
only triggers where the restriction is active.
Verified end-to-end on Ubuntu 26.04: gstack browse drives a real page
(Navigated 200). See BDR-029 / LRN-040 / BLK-008.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyNYwD4UccVw9ZCFZyJX55
The PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-x64 pin (211c7d4) made
Playwright 1.58.2 stop erroring and instead download a Chrome-for-Testing
fallback build — but that download reaches 100% and then HANGS at extraction
on Ubuntu 26.04 (reproduced on a real machine + here: chrome binary never
materializes, no headless-shell download starts). Net effect: the override
turned a 0.5s fast-fail into an indefinite hang that blocks `make install` /
`make plugin` (user had to Ctrl+C).
Reverting restores the original behavior: gstack's ./setup fast-fails the
browser install (non-fatal — gstack is OFF by default, browser only needed
for /browse, /qa, screenshots) and the install completes. Replaced the code
with a NOTE explaining the dead end. Real fix is upstream: gstack bumping
Playwright to a version that supports the OS. See BLK-008.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyNYwD4UccVw9ZCFZyJX55
Three paths are (re)generated by every install/update and should never be
committed:
- skills-external/frontend-design/ — install-plugins.sh Step 8b and
update-all.sh cp the latest SKILL.md from the example-skills plugin cache
over it, so it churned a diff each time Anthropic shipped an update. The
source is always re-synced (example-skills is always installed), so no
vendored copy is needed.
- .agents/ and skills-lock.json — `npx skills add` (darwin-skill) installs
at project scope into the repo. Our own agents live in agents/ (no dot)
and stay tracked; the dotted pollution dir is anchored-ignored (/.agents/).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyNYwD4UccVw9ZCFZyJX55
graphify's installer rewrites CLAUDE.md + .claude/settings.json (clobbers
the curated graphify section, drops the "This repo only" header, injects
aggressive MANDATORY pre-tool hooks) and `claude plugin install` flips
enable-states in settings.json. These 3 files are hand-curated, never
installer-owned.
Snapshot them at the top of install-plugins.sh and restore on EXIT (trap)
so `make install` / `make plugin` leaves them exactly as found. Pre-existing
local edits are preserved; only installer drift is undone. Verified with an
isolated drift→restore test. update-all.sh needs no guard — it only runs
`claude plugin update` (no enable flips) and never re-runs graphify's
CLAUDE.md/settings integration.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyNYwD4UccVw9ZCFZyJX55
jq is used 18+ times in always-on hooks (statusline.sh, rtk-rewrite.sh)
but was never installed by any script — it only worked because dev
machines happened to have it; a bare machine breaks at hook-run time.
Add it to Step 1 (same inline pattern as the other prereqs) and to
doctor.sh at fail level.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyNYwD4UccVw9ZCFZyJX55
Ubuntu 26.04 (and any release newer than 24.04) isn't in Playwright
1.58.2's supported-build list, so gstack's ./setup aborted with
"Playwright does not support chromium on ubuntu26.04-x64".
Add gated helper playwright_platform_override() (ubuntu >24.04 → echoes
ubuntu24.04-<arch>, else nothing). Export PLAYWRIGHT_HOST_PLATFORM_OVERRIDE
before gstack ./setup (install-time download) and persist it to the shell
profile (runtime browser launch). Playwright then pulls a compatible
Chrome-for-Testing fallback build instead of erroring.
Verified on Ubuntu 26.04: override emitted correctly (no var leak), CfT
build resolves all shared libs (ldd) and renders headless. No submodule
edits — purely an env pin from the wrapper.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyNYwD4UccVw9ZCFZyJX55
Fresh machine had no npm → install.sh err-exited before the Claude Code
CLI install could run. Instead of aborting, bootstrap the current LTS via
nvm (v0.39.7) → `nvm install --lts` when node or npm is absent. Keeps the
>=18 floor + friendly messages on hard failure.
Replaces the reverted lib/install-prereqs.sh centralization with the
minimal targeted fix.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyNYwD4UccVw9ZCFZyJX55
BDR-025: design gate = profile-based (tier=profil, GATE-BLOCK allowlist,
magic required-but-manual, unknown->fail-visible exit 11, claude resolved via
ensure_claude_on_path since command -v depends on PATH carrying nvm bin). Alts
rejected: hardcoded tier->tools, advisory magic, strict fail-closed.
BDR-026: secret source-of-truth in ~/.claude/.env via repo/.env symlink;
source follows link -> zero read-path change; link_env defensive.
LRN-037: verify the load-bearing scenario on the real subject in real context,
not a stub/logic — every refutation this chantier came from execution.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Real cause of the gate's 'claude absent'/unknown: command -v claude needs the
nvm node bin on PATH; a sanitized-PATH hook/subshell or a version-pinned nvm
path loses it. NOT the alias (refuted: binary on inherited PATH makes command
-v succeed), NOT exit 11 (that's the mitigation). Fix = ensure_claude_on_path.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Stale "Copy to .env" comment updated to the inverted layout: the real key
lives in ~/.claude/.env and link.sh symlinks repo/.env to it. Comment only;
the MAGIC_API_KEY placeholder is unchanged.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The "unknown -> exit 11" path triggers when `command -v claude` fails. Root
cause is NOT the interactive alias (claude->dtach_claude) not surviving the
subshell — that's true but harmless: the real binary is on the inherited PATH,
so `command -v` finds it in a normal `bash script.sh` (proven: toggle-external
and the gate both resolve claude). The actual lever is PATH carrying the nvm
node bin. A skill/hook that shells the gate out with a sanitized PATH, or a node
upgrade moving the version-pinned nvm path, loses it.
ensure_claude_on_path(): if `command -v claude` already resolves, do nothing;
else probe known install dirs (~/.claude/local, ~/.local/bin, /usr/local/bin)
and the nvm glob, prepending the bin dir — which carries BOTH claude and its
node runtime (claude's shebang needs node, same dir). nvm keeps old versions
after an upgrade, so pick the newest that ships claude via sort -V, not the
first glob match. If nothing resolves, command -v still fails -> unknown ->
exit 11 (fail-visible net stays).
Verified: shellcheck clean; normal PATH -> READY exit 0 (function returns early,
no regression); PATH=/usr/bin:/bin (sanitized hook) -> now resolves claude via
the nvm glob and reports REAL magic state (READY exit 0), where before the fix
it was exit 11 unknown.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The gate's remedy is now /profile design (not an atomic ui-ux-pro-max toggle),
but several callers still described the old "ask user to activate ui-ux-pro-max"
behavior. Repoint the prose — the `Follow lib/design-gate.md` pointers stayed
valid (the gate was extended in place), so only descriptions change:
- agents/feater.md, hotfixer.md, bugfixer.md (STEP 0.5/1.5 gate bullet):
signals found → run design-tool-gate.sh; if INCOMPLETE → /profile design.
- agents/feater.md rule 6: trigger is "design toolchain incomplete", not
"ui-ux-pro-max inactive".
- agents/plugin-advisor.md: gate points at /profile design when the toolchain
is incomplete.
- skills/feat/test-prompts.json (id 2): expected behavior updated; still valid JSON.
No logic change — descriptions only, aligned with the profile-based gate.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
When `claude` is unreachable, the plugin/MCP checks (magic, ui-ux-pro-max —
the most important design tools) return `unknown`. The old verdict folded that
into a silent `READY` exit 0 — a fail-OPEN: the gate granted "proceed" exactly
when it had verified nothing. Contradicts the fail-closed-on-uncertainty rule.
Now fail-VISIBLE (not strict fail-closed — claude can be merely slow, false
blocks would get the gate ignored): a third outcome READY BUT UNVERIFIED with a
distinct exit 11. It proceeds, but says so loudly and names the unchecked tools,
telling the user to confirm with `claude mcp list` / `claude plugin list`. The
distinct non-zero code also stops a naive `if gate; then proceed` shell caller
from silently passing. Also covers the non-reproducible "transient claude absent
after apply" flake seen in live testing.
design-gate.md §DECISION updated: exit-code line + a real branch-3 state for 11.
Verified: shellcheck clean; reachable+active -> READY exit 0; claude off PATH ->
READY BUT UNVERIFIED exit 11 naming magic+ui-ux-pro-max; magic off -> INCOMPLETE
exit 10 (trip branch intact after the restructure).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Move the real secret out of the git tree: the key lives in ~/.claude/.env
(outside the repo), and link.sh symlinks repo/.env -> ~/.claude/.env so
`source "$REPO/.env"` resolves transparently. The secret never enters git —
not as content (it's a link) and not by accident (gitignored).
link.sh: add link_env() — verify ~/.claude/.env exists + has MAGIC_API_KEY
(warn, never create/copy the secret), then create repo/.env -> ~/.claude/.env.
Defensive + idempotent: links only when repo/.env is absent or already the
right symlink; a residual REAL repo/.env is left untouched with a migrate hint
(never clobbered, so the secret can't be destroyed).
.gitignore: harden .env -> .env + .env.* + !.env.example (covers .env.local,
.env.bak, .env.save; keeps the template tracked).
Messages point at ~/.claude/.env (the canonical edit location) instead of the
ambiguous $REPO/.env: design-tool-gate.sh gate output, design-gate.md
(branch 3 + IMPORTANT), toggle-external.sh, install-plugins.sh.
Verified: shellcheck clean (link.sh, toggle-external.sh, design-tool-gate.sh);
link.sh created the symlink (1 change, idempotent re-run); repo/.env absent
from git status; magic-off path still exits 10 with the ~/.claude/.env hint.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the inline "Design gate (automatic)" description — which still named
the old atomic "ui-ux-pro-max inactive → ask user" behavior — with a one-line
pointer to the gate spec, now that the gate logic lives in design-gate.md +
design-tool-gate.sh and points at /profile design. No design rule changed;
the Orchestrators line (STEP 0 plugin-check) is untouched.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
design-tool-gate.sh: deterministic design-toolchain state check. Reads the
design-core tools from design.profile's `# GATE-BLOCK:` allowlist + their
types via `profile.sh show design --plain` (claude-free parse contract),
checks each on its own channel (skill symlink / claude plugin list / claude
mcp list / command -v). Never reads disabledMcpServers. Exit 0 ready · 10
incomplete · 2 error.
Remedy is always a profile (/profile design), never an atomic tool toggle —
the profile system stays the single source of truth for activation. magic is
required-but-manual: it TRIPS the gate (not advisory) and the output names
the MAGIC_API_KEY step. Non-design tools bundled in the profile (browse,
plan-*, design-shotgun, graphify) are excluded from the trip via GATE-BLOCK,
so the gate fires only on real design tools.
design-gate.md: §DECISION rewritten profile-based (tier → run script → branch
on 3 groups), replacing the old atomic "ask user to activate ui-ux-pro-max".
§DETECTION unchanged. design.profile: add the `# GATE-BLOCK:` allowlist
(8 design-core tools); it is a comment, so read_profile/--plain are unaffected.
Verified: shellcheck clean; magic-off (real design profile) → exit 10 +
API-key line; all active → exit 0; browse-off (non-GATE-BLOCK) → exit 0,
no trip.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
LRN-034: narrated state (any source) ≠ ground truth — P3 was believed
applied (approval confused with writing, accepted without re-checking)
until git proved otherwise on reprise. Lead signal missed = internal
contradiction ("P3 non écrit" then "P3 fait"). Verify against git.
LRN-035: honest dedup — name-mention ≠ definition-instance; the dosage
rule correctly reduced P4 to a no-op, don't force factorization.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X3e8LaH2vymmxyh36h3jFU
P5: merge the TODO volet of ## Workflow with ## Task tracking into a
single ## Planning & TODO section (when to plan / exempt scope / how to
track), placed right after ## Workflow. Drops the "see Workflow" cross-ref;
no rule lost.
P6: reserve emphasis caps (NEVER/ALWAYS/MUST/FORBIDDEN/ONLY/No…) for the
~9 critical rules only (security, never-invent, append-only memory, radical
honesty, never-assume, STOP, SPA-ban, supply-chain dep vetting). Downgrade
process/style dressing to normal case so the critical anchors stand out.
Typography only — no content or meaning changes.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X3e8LaH2vymmxyh36h3jFU
Design routing was split across 3 places (Skill-routing entries, the
Design gate paragraph, and the Design work section). Collapse the 3
skill-routing design entries to one renvoi; move the Design gate into
"## Design work — full toolchain"; mark that section the single source.
No rule lost — gate preserved verbatim, just relocated.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X3e8LaH2vymmxyh36h3jFU
LRN-032: rule has a domain — applying it out-of-domain = category error;
check artifact class before invoking (80-char rule = source-code, not CLI
output). Cross-ref LRN-031 (paired meta-lessons on not applying mechanically).
LRN-033: multibyte separator breaks printf %-Ns byte-padding; pad via ${#}.
BDR-024: show --plain = claude-free parse contract for the upcoming design gate.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X3e8LaH2vymmxyh36h3jFU
list: ITEMS column with compact per-category counts (e.g. 12s·1p·1m·1c),
left block aligned; full descriptions kept (CLI output, not 80-strict).
show: grouped by type (gstack/external/personal/plugin/mcp/cli) with
status; redundant per-line TYPE column and plugin marketplace suffix dropped.
show --plain: parsable "type<TAB>name" list, no status, zero claude calls —
the contract for the upcoming design gate. All derived from .profile files.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X3e8LaH2vymmxyh36h3jFU
BDR-023 — merge /close into /capitalize (2 modes + TODO reconcile), /close
now a thin alias. LRN-031 — a skill earns complexity only on gate +
anti-noise + determinism, not by re-coding what a capable agent does free;
if the RED baseline passes, harden the fixture. Journal 2026-06-19.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X3e8LaH2vymmxyh36h3jFU
PASS A done-detection was ~60% machinery a capable agent already does for
free (the baseline checked done tasks and left the umbrella task alone
unaided). Cut the git-command how-to and worked example; keep only the
load-bearing restraint rule (flip only on a clean task<->commit map;
partial/umbrella/vague stay unchecked; never guess).
Add a Red flag: the STEP 3 gate STOP was never exercised (non-interactive
build harness printed the gate then proceeded as approved) — confirm it
halts before any write on first real use. TDD note records the same caveat.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X3e8LaH2vymmxyh36h3jFU
Reflect the /close → /capitalize --ritual merge in the session-loaded routing
table (CLAUDE.md) and the README/USAGE command tables: capitalize now also
reconciles .claude/tasks/TODO.md, --ritual adds the end-of-session reflection,
and /close is documented as an alias. Does not touch the in-progress caveman
purge edits in these files (left unstaged).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X3e8LaH2vymmxyh36h3jFU
Two-mode capitalize: default pre-wipe flush, --ritual adds the 3-question
end-of-session reflection (now deduped, unlike legacy /close). New STEP 2B
reconciles .claude/tasks/TODO.md — PASS A done-detection (only on an
unambiguous task<->commit map), PASS B explicit-only capture with an
anti-noise filter (never track commit/deploy/push/release/tag) and BDR
routing for orientation directives. STEP 3 gate gains a separate TODO block;
journal/handoff report TODO ops. /close becomes a thin alias for
/capitalize --ritual (zero duplicated logic).
Built via superpowers:writing-skills TDD: RED baseline (no skill) folded a
push/tag parasite into the TODO, invented a subtask, and wrote with no gate;
GREEN re-run on the same fixture stops at the gate, drops both dups (footer
shows existing IDs), logs one learning, checks only the cleanly-done task,
ignores the parasite, and routes the GraphQL directive to BDR.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X3e8LaH2vymmxyh36h3jFU
Teach doc-syncer to sync an existing ROADMAP.md without ever creating one.
- ROADMAP absent → propose nothing; never bootstrapped (creation belongs
to init/onboard skills). Never enters DOC_MISSING, never a CREATE
candidate.
- ROADMAP present → standard drift detection plus 'shipped reconciliation':
a planned/unchecked item proven delivered by CODE + git is proposed for
the shipped/done section (or checkbox), preserving wording. [AUTO] when
the item-to-code mapping is obvious, [HUMAN] when it needs judgment.
One direction only (planned -> shipped); never invent planned items.
- Forbid reading .claude/tasks/ (or any .claude/) to populate or check
ROADMAP; shipped status is deduced from code/git only.
- Numeric incoherence (e.g. a '22/22' milestone matching no code counter)
is surfaced as a [HUMAN] question, never overwritten with a guess.
Implements BDR-022's read-only .claude/ boundary for the ROADMAP case.
Co-Authored-By: Claude <noreply@anthropic.com>
Run /doc clean over the public docs and apply the verified items.
- README: drop the unused CONTEXT7_API_KEY step from fresh-install (the
var is never read; add an optional ctx7 setup section), complete the
Makefile target table (+link, onboard, profile×3), add personal-skill
rows (audit-delta, capitalize, prune-memory, pdf-translate) with a
scope note, link CHANGELOG.md.
- USAGE: add audit-delta / capitalize / prune-memory to the decision
tree, the quick-decision table, and the command reference, plus a
scope note about plugin/marketplace skills.
- CHANGELOG: add a Keep-a-Changelog [Unreleased] section with a drafted
(review-flagged) summary of changes since 3.4.0.
GSD notation left unchanged: gsd --help confirms both 'gsd <cmd>' (CLI)
and '/gsd <cmd>' (in-TUI) are valid, so no blanket rewrite. CHANGELOG
[Unreleased] is a draft for human review, not exhaustive.
Co-Authored-By: Claude <noreply@anthropic.com>
Record the doc-syncer rewrite decision: sync targets limited to public
docs, .claude/ and CLAUDE.md as read-only context, normative conventions
and clean mode added. Extends BDR-016, does not supersede it. Log the
session in journal.md under 2026-06-18.
Co-Authored-By: Claude <noreply@anthropic.com>
Rewrite the doc-syncer agent so it only ever targets public docs and
treats .claude/ (and CLAUDE.md) as read-only context.
- Add normative CONVENTIONS section: Standard-Readme, Diátaxis doc-type
separation, Keep a Changelog + SemVer, Conventional Commits.
- Add CONTEXT SOURCES section: .claude/ and CLAUDE.md may be read for
project context but are never modified, never sync targets, and their
content is never copied into a public doc.
- Drop .claude/{tasks,audits,memory} and CLAUDE.md from discovery,
per-doc analysis, tagging, patches, and the report. Remove the STEP 4
blocks that audited TODO.md / audits/*.md / decisions-learnings-blockers.
- Fix sync scope to the modifiable targets: README, INSTALL, CONFIGURE,
USAGE, DEPLOY, CONTRIBUTING, CHANGELOG, SECURITY, ARCHITECTURE, LICENSE,
docs/**. Add SECURITY.md and ARCHITECTURE.md analysis stanzas.
- Make the README template lean (Standard-Readme order): drop Status and
Project layout; forbid roadmap/todo/internal-state; README only links
to the Diátaxis docs, never duplicates them.
- Add CLEAN mode (triggered by a 'clean' arg): propose removal of
out-of-convention sections and copied .claude/ content from existing
public docs, HUMAN-tagged and gate-validated.
- Conserve: stack detection, 14-section DEPLOY gate, validation gate,
AUTO/HUMAN tagging, never-invent rule, AUTO MODE (input contract
'auto-mode scope:' unchanged, so callers are unaffected).
- Preserve frontmatter name/tools/model; update description to reflect
the public-doc scope and 'reads .claude/ for context only'.
Co-Authored-By: Claude <noreply@anthropic.com>
Add LRN-030 documenting Opus 4.8's tendency to under-delegate
subagents/memory/custom-tools by default and the CLAUDE.md fan-out
rule that counters it; log the session in journal.md under 2026-06-18.
Co-Authored-By: Claude <noreply@anthropic.com>
Expand the sub-agent bullet to push fan-out work (many files,
parallel searches, multi-point checks) to sub-agents rather than
serial iteration, and default to delegation for multi-file
exploration. Counters Opus 4.8's tendency to under-delegate.
Co-Authored-By: Claude <noreply@anthropic.com>
Drop the top-level "model" key so the session falls back to the
default model instead of forcing claude-fable-5[1m].
Co-Authored-By: Claude <noreply@anthropic.com>
Fable 5 audit of the global CLAUDE.md (symlinked from this repo):
Contradictions resolved:
- two conflicting graphify sections merged into one (query-first when
graphify-out/graph.json exists, direct read otherwise; single command
form; dropped the false 'this project has a knowledge graph' claim)
- plan rule: 'when in doubt skip plan' no longer cancels the mandate —
borderline = single-file small obvious change
- deviation rule disambiguated: minor/justified -> explain after,
significant/shaky -> ask before
- 'append-only' registries reconciled with /prune-memory curation
Dead refs fixed: /caveman:compress -> /caveman-compress; design-gate
path now ~/.claude/lib/ (was repo-relative); '(replaces LESSONS)' note
dropped.
Structure: Health Stack / Skill routing / graphify no longer nested
under '# Communication mode'; new '# Tooling & skills' and
'# This repo only' sections; repo-specific Health Stack labeled as such.
Routing updated: + audit-delta, close, capitalize, prune-memory,
profile, context-restore, geo; explicit gstack-OFF fallback rule.
Mid-task question exception generalized to all skill-mandated gates.
Non-critical sections caveman-compressed; Architecture decisions and
Security kept verbatim (must stay unambiguous). Net -1471 chars while
adding 8 routing entries.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Both blind judges flagged the same residual: without a detection
criterion, a /seo-dispatched subagent could misread itself as headless
and degrade to report-only. Unreachable = no answer obtainable at all
(cron/CI, user explicitly absent); orchestrator dispatch with a main
thread that can relay questions is reachable.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
