docs: close 11 accuracy defects between idstack.org and the repo - #70
Merged
Conversation
Audits idstack.org against the repo and finds 11 defects across three kinds: claims that are untrue, material omissions, and files published that were never meant to be public. Two mechanism decisions worth noting: - Internal design docs and og-template.html are excluded at build time in static.yml rather than relocated. The brainstorming skill hardcodes docs/superpowers/specs/, so a move alone gets silently undone on its next run; and smoke-test.sh asserts docs/og-template.html exists, so that file cannot move at all. - dateModified and sitemap lastmod are deleted rather than corrected. A CI check asserting either date is current fails on commits that did not introduce the defect, and a check that cries wolf is one people learn to bypass. The guard becomes an absence assertion instead. Spec lives outside docs/ on purpose — the skill's default location is finding 10. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- Item 5's primary fix is the install prose, not the JSON-LD string. A Windows visitor is stopped by prose they read, not by metadata they never see. The operatingSystem edit is a precision improvement only. - Drop the search-engine claim from D2's rationale. The argument stands on the scoring model alone, and the spec should not carry a third-party assertion it cannot verify. - Pin the staging step's position in static.yml and require the local dry-run before the workflow is edited. - Note that superpowers/plans/ must be created; git mv won't. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Five tasks, each with its own test cycle. Task 1 is a genuine red-green cycle: the new absence check fails against the current files, and deleting the two stale date fields turns it green. Both non-obvious verification commands were run against the tree before being written into the plan -- the JSON-LD parse snippet and the Pages staging dry-run, which produces exactly the eight entries the plan lists. The dry-run also surfaced that _site was not gitignored, so a forgotten cleanup could be committed. Added as Task 4 Step 1. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- Confirm the PRIVACY.md blob URL resolves on main (200), so a 404 in the link sweep points at a typo rather than a missing file upstream. - grep -c counts matching lines, not occurrences; the privacy-link check now uses grep -o | wc -l so a reflowed paragraph cannot read as failure. - Note that a stray _site/ in git status is an uncleaned dry-run. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
dateModified in the JSON-LD and lastmod in sitemap.xml were both stale -- 2026-08-06 and 2026-05-13 against docs changed through 2026-08-12. They are deleted rather than corrected: any check asserting such a date is current fails on commits that did not introduce the defect, and a check that cries wolf gets bypassed. check-doc-accuracy.py now asserts neither field returns, which cannot false-positive. Mutation 22 proves the guard bites.
smoke-test.sh sweeps every tracked file for references to the retired CLI and this spec named it while describing an og-image verification result. Reworded rather than tagged with IDSTACK_CLI_LEAK_ALLOW: the tag is for dated historical mentions, and weakening the invariant to accommodate my own prose is the wrong trade. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
.superpowers/ holds implementation reports and review notes written during development. It is not shipped and CI never sees it, but notes discussing the sweep tripped it, making the local gate unreliable. Matches the .gstack/.idstack/.claude exclusions already on that line. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- Install headline said five minutes; README says 30 seconds for the same command. Reconciled to README. - Pipeline lede accounted for ten skills under an 'Eleven skills' headline; /idstack:pipeline is the eleventh and now appears in the count. - JSON-LD claimed plain Windows support; ./setup is a bash script. - v3.4.0.1 release note covered only the evidence-card fix; ROADMAP lists two more items shipped in that patch.
…anding page The page asked visitors to paste a bash script without saying a bash shell is required, never mentioned bin/idstack-doctor or bin/idstack-status, and collected email addresses without linking the privacy policy that already exists in the repo.
static.yml uploaded docs/ verbatim, so design specs and og-template.html were served at idstack.org. Stage a copy and drop both instead of moving them: the brainstorming skill writes specs to docs/superpowers/ by default so a move alone gets undone on its next run, and smoke-test.sh asserts docs/og-template.html exists at that exact path so it cannot move at all.
Both anchored on the literal string 'Install in about five minutes.', which this branch corrected to 'Install in 30 seconds.' Their replace() calls matched nothing, so both silently mutated nothing and the suite reported NOT-GUARDED. Repointed at the current text; what each mutation proves is unchanged.
…n anchors The --exclude-dir=.superpowers comment argued the directory is git-ignored like .gstack/.idstack/.claude, but it was not in the root .gitignore -- only a nested .superpowers/sdd/.gitignore made its contents untracked, so a file directly under .superpowers/ would have been tracked and sweep-exempt. Mutations 16 and 17 now assert their anchor matches before replacing, the pattern already used at mutation-test.sh:341. Both had just gone stale by silently matching nothing.
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.
Implements
superpowers/specs/2026-08-14-github-page-accuracy-design.md.An audit of idstack.org against the repo found 11 defects that the two existing
validators (
check-doc-accuracy.py,check-evidence-cards.py) do not cover.All 11 are closed here.
Corrected
./setupis a bash script./idstack:pipelineis the eleventh.Added
Prerequisites (bash shell, WSL or Git Bash on Windows, python3 optional),
bin/idstack-doctorandbin/idstack-status, and a link toPRIVACY.mdunderthe email signup form that previously had none.
Unpublished
static.ymluploadeddocs/verbatim, so internal design docs andog-template.htmlwere served at idstack.org. They are now excluded from thestaged artifact. Excluded rather than moved, for two independent reasons: the
brainstorming skill writes specs to
docs/superpowers/by default, so a movealone is undone on its next run; and
smoke-test.shassertsdocs/og-template.htmlexists at that exact path, so that file cannot move.Guarded
dateModifiedand sitemaplastmodwere both stale. They are deleted ratherthan corrected: any check asserting such a date is current fails on commits
that did not introduce the defect — a PR left open a week, a merge dated after
the docs edit — and a check that cries wolf is one people learn to bypass.
check-doc-accuracy.pynow asserts neither field returns, which cannotfalse-positive, and mutation 22 proves the guard bites.
Found during execution, not in the plan
smoke-test.sh's sweep.Reworded rather than tagged
IDSTACK_CLI_LEAK_ALLOW— that tag is for datedhistorical mentions.
.superpowers/addedto the root
.gitignoreso the exclusion's stated premise is actually true.install headline this branch corrected. Their
replace()calls matchednothing, so they mutated nothing. Repointed, and both now assert their anchor
matches before replacing — the pattern already used at
mutation-test.sh:341.Verified accurate, left alone
All version strings, the 108-studies / 11-domains claim, all 11 evidence cards,
every per-skill capability claim (UDL 3.0, WCAG 2.1 AA, SCORM 1.2, red-team's 5
dimensions, Nicol's 7 principles, three-level needs assessment),
og-image.png,and the repo's About/topics/homepage.
Testing
11 suites green; mutation suite 27/27 guarded, 0 not guarded.
After merge,
curlshould return 404 for/superpowers/specs/2026-08-12-documentation-accuracy-design.mdand/og-template.html, and 200 for the site root.🤖 Generated with Claude Code