v3.3.0.1 — post-ship docs pass, plus the bare-command bug it found - #58
Merged
Conversation
The release shipped new public surface, shared libraries, and eight test
suites; the docs described none of it. Corrections against the diff:
- CONTRIBUTING said a skill is "one directory, one file: SKILL.md" and
named only smoke-test.sh. A new contributor following it would hand-edit
a generated file and run 1 of 8 suites. Now documents the .tmpl source,
the regen gate, every suite and what it covers, the Python 3.9 floor for
embedded scripts, and the bin/lib rule (test the shipped file, not a copy).
- CLAUDE.md / AGENTS.md: added idstack-migrate (incl. --init), manifest-merge
and slugify to Commands; added the eight test suites and the CI matrix;
documented the {{IDSTACK_RESOLVE}} placeholder and why it repeats per bash
block; added the bin/lib section.
- README: the contributing pointer repeated CONTRIBUTING's wrong instruction;
the architecture block omitted idstack-doctor, which README's own
troubleshooting section tells users to run.
- ROADMAP was three releases behind, still showing v3.0.0 as newest. Added
v3.1-v3.3 and dropped the passed "(v2.6)" labels from pending items, which
made them read as overdue rather than unscheduled. Same labels fixed in
TODOS.md and CLAUDE.md.
- CHANGELOG: contributor-only work moved out of the user-facing "Changed"
section into "For contributors"; added the git pull && ./setup line so the
entry says how to actually receive the fixes. No entry reworded or removed.
Corrected "16 behavioral tests" to 17 — f956177 split an assertion after
the count was last audited; ./test/test-setup.sh reports 17/17.
Verified: gen-skills --dry-run clean (22 templates, 0 stale); all eight
suites pass (371 smoke, 25 integration, 17 setup, 21 manifest-merge, 27
version-classifier, 9 plugin-status, 6 preamble-python, 13/13 mutations
guarded).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Eight findings from the Codex documentation review, each verified against
the shipped source before applying.
User-facing (README):
- Bare /course-quality-review and /learning-objectives in prose and in the
sample transcript. This release banned exactly that form from skill text
for not being a valid command; the README still handed it to users. Now
/idstack:<skill>, with a note above the workflow diagram explaining that
its unprefixed labels are for column width, not for typing.
- The sample install output was from an install path that no longer exists
("linked: ...", "installed successfully"). setup:176 prints "idstack
installed (Claude Code) - scope: ..." and a skills list. Replaced with
what it actually prints.
- "Requirement: Claude Code" contradicted line 7's Codex support claim.
Codex is now named, with every setup flag documented.
Contributor guidance:
- --keep-legacy is a public flag with its own usage line (setup:32), fixed
by this very release, and was documented nowhere. Added to both command
lists.
- CLAUDE.md / AGENTS.md / CONTRIBUTING called inline manifest writes a
deprecated fallback, but needs-analysis and course-import use them
deliberately for multi-section writes. Undocumented, that reads as two
skills violating the rule. Now stated as the one exception, with the
standalone idstack-migrate --init requirement alongside it.
Counts:
- CHANGELOG said CI runs "all seven suites"; test.yml runs eight (seven in
the matrix job, mutation in its own).
- TODOS said "All 7 skill preambles"; there are 11.
- ROADMAP: pre-v2 entries used /idstack <skill> and bare /red-team forms.
Normalized to the colon namespace so nothing on the page is copy-pasteable
and broken.
Verified: gen-skills --dry-run clean; smoke 371/371, integration 25/25,
setup 17/17.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The previous commit rebuilt this block from setup:176 onward and claimed it was what setup prints. It skipped the three lines setup emits before that: the regeneration notice (setup:49) and the "Installing idstack (scope)" / "source:" header (setup:51-52), all unconditional. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
v3.3.0.0 banned bare /skill references because they resolve in neither CLI, and fixed them in bin/idstack-status. The guard enforcing it matched only backticked refs: BARE_SLASH_RE='`/(needs-analysis|...)`' Three plain-prose examples in templates/preamble.md survived it (lines 236, 241, 244) — and the preamble is spliced into all 22 skill files. They are the model's instructions for phrasing welcome-back and next-step messages, so the model copied their shape and told users things like "Based on your progress, /assessment-design is the natural next step." Typing that does nothing. It landed inside the context-recovery message v3.3.0.0 had just repaired, so it was the first thing a user saw once welcome-back messages started working again. - Namespaced all three. On Codex the existing translation rule renders them as $<skill>. - Widened the guard to match a bare /skill in any command position (line start, whitespace, quote, paren, backtick), not only inside backticks. It will not match a slash preceded by a path character, so .idstack/exports/<slug>/red-team.html stays legal, and it cannot match /idstack:<skill> because the skill name does not follow the slash. - Kept frontmatter exempt, as before: description: is picker prose, not a command. The check now strips through the closing --- and scans the body. Six frontmatter matches confirmed exempt rather than "fixed". - Added a mutation case reintroducing an unbackticked bare reference. Found by the doc sweep in /document-release, not by the suite — the guard that was supposed to catch it is the thing that had the hole. Verified: smoke 371/371, integration 25/25, setup 17/17, manifest-merge 21/21, version-classifier 27/27, plugin-status 9/9, preamble-python 6/6, mutations 14/14 guarded. gen-skills --dry-run clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Post-ship documentation pass over v3.3.0.0, plus one real bug the pass uncovered.
v3.3.0.0 merged in #57. This branch audits every doc against what actually shipped, and bumps to v3.3.0.1 for a behavior fix found along the way.
The bug (v3.3.0.1)
v3.3.0.0 banned bare
/skillreferences because they resolve in neither CLI, and fixed them inbin/idstack-status. The guard enforcing it matched only the backticked form:Three plain-prose examples in
templates/preamble.md(236, 241, 244) walked straight through it. That preamble is spliced into all 22 skill files, and those lines are the model's instructions for phrasing welcome-back and next-step messages — so the model copied their shape and told users things like:Typing that does nothing. It landed inside the context-recovery message v3.3.0.0 had just repaired, making it the first thing a user saw once welcome-back messages started working again.
Fixed by namespacing all three, widening the guard to catch a bare
/skillin any command position, and adding a mutation case. Frontmatter stays exempt as before (description:is picker prose, not a command) — the six frontmatter matches were confirmed exempt, not "fixed".Documentation
CONTRIBUTING.md — said a skill is "one directory, one file:
SKILL.md" and named onlysmoke-test.sh. A new contributor following it would hand-edit a generated file and run 1 of 8 suites. Now documents the.tmplsource, the regen gate, every suite and what it covers, the Python 3.9 floor for embedded scripts, and thebin/lib/rule.CLAUDE.md / AGENTS.md — added
idstack-migrate(incl.--init),manifest-merge,slugify, and--keep-legacyto Commands; added the eight test suites and CI matrix; documented the{{IDSTACK_RESOLVE}}placeholder and why it repeats per bash block; added thebin/lib/section; documented the deliberate multi-section-write exception soneeds-analysisandcourse-importno longer read as rule violations.README.md — bare
/course-quality-reviewand/learning-objectivesin prose and in the sample transcript (the exact form this release banned); sample install output was from an install path that no longer exists; "Requirement: Claude Code" contradicted the Codex support claim three lines above; architecture block omittedbin/idstack-doctor, which the troubleshooting section tells users to run.ROADMAP.md — was three releases behind, still showing v3.0.0 as newest. Added v3.1–v3.3, dropped the passed "(v2.6)" labels from pending items, normalized pre-v2 command syntax.
CHANGELOG.md — contributor-only work moved out of the user-facing "Changed" section into "For contributors"; added the
git pull && ./setupline so the entry says how to receive the fixes. No entry reworded or removed. Corrected "16 behavioral tests" → 17 (f956177 split an assertion after the count was last audited) and "all seven suites" → eight.TODOS.md — "All 7 skill preambles"; there are 11.
Verification
A cross-model doc review (Codex, high reasoning) ran against the release diff; all 8 findings were verified against the source and applied.
Documentation debt
Not fixed here, recorded so it isn't lost:
bin/lib/*.sh,{{IDSTACK_RESOLVE}},bin/idstack-migrate --init— now have reference coverage in CLAUDE.md / AGENTS.md / CONTRIBUTING.md, but no how-to or worked example. Would suit a how-to page./skillprose references left as internal shorthand. Contributor backlog, not user-facing, and none are copyable instructions.test/sample-cartridge.md,test/sample-course.md— bare/skillreferences in test fixture headers.Suggest a
docs-debtlabel.🤖 Generated with Claude Code