Files

Tom Boucher 1adf6d2245 fix(#3620 ): point the docs at files that actually exist (#3658 )

* fix(3620): point the docs at files that actually exist

docproof found 34 stale references; the reporter hand-read all 34 and reported the 8 that
are real, explaining why the other 26 are deliberate (files the documents themselves label
legacy or "superseded by", and one pre-Diataxis link label whose target still resolves).
Those 26 are left alone — re-touching them would contradict the issue's own analysis.

Every claim was re-verified against git ls-files at HEAD before editing.

docs/INVENTORY.md said its roster is anchored by six drift-control tests. Five are gone
(commands-doc-parity, agents-doc-parity, cli-modules-doc-parity, hooks-doc-parity in
5d8a8c4d; command-count-sync in fbf30792), so the sentence now names the one that exists.
Whether one test is sufficient coverage is a maintainer question the issue explicitly
declined to answer, so no new drift tests are proposed here.

The four translations were a revision further behind, each naming a seventh test deleted in
ae8bb707 that the English file had already dropped. All four now match.

Renamed targets corrected in CONTEXT.md, VERSIONING.md, docs/CONFIGURATION.md and the
update workflow. The new test names carry no issue-NNN- prefix, which is what
lint-regression-test-names requires, so they are the correct targets.

docs/TESTING-SUITES.md is the one that could cost somebody time: it INSTRUCTED contributors
to add an acknowledgment to the legacy drift-ack file, which CONTRIBUTING.md says to never
use. Rewritten from the real workflow — per-PR fragments under the drift-acks directory,
and a spent base-side ack is re-armed by rewording that fragment's reason in place, never
by adding a duplicate, since two sources naming one path is a hard error.

docs/skills/discovery-contract.md's heading named a query module deleted in 11918dcc. The
section was REMOVED rather than retargeted: its documented behavior (skip the deprecated
root) is not what the surviving code does — skill-manifest includes that root marked
deprecated:true — so retargeting would have documented something false.

Found and fixed inline, same class: VERSIONING.md described an SDK bundling step the
release workflow does not have (zero such mentions in that file); CONFIGURATION.md and four
translations named a dead model-catalog triple collapsed by ADR-457.

Dead config removed: the changeset lint's user-facing prefix list still carried two retired
sdk entries. git ls-files -- 'sdk/*' returns nothing. No test pins that array.

Left deliberately: the comment explaining the retired catalog path, the install regression
test that reconstructs the old broken layout to prove it fails, and the generated
test-timings cache. Each is a legitimate mention of a dead path, not drift.

Note lint-removed-but-needed cannot catch this class: it diffs baseRef...HEAD, so it only
sees files deleted in the change under review. These were orphaned by PRs that predate the
lint. A repo-wide existence audit would need a suppression mechanism for the 26 deliberate
mentions above; that is a feature, not part of this fix.

Fixes #3620

* chore(3620): backfill changeset PR number (#3658)

---------

Co-authored-by: sim <sim@local>

2026-08-19 01:54:01 -04:00

2.4 KiB

Raw Blame History

Skill Discovery Contract

Canonical rules for scanning, inventorying, and rendering GSD skills.

Root Categories

Project Roots

Scan these roots relative to the project root:

.claude/skills/
.agents/skills/
.cursor/skills/
.github/skills/
./.codex/skills/

These roots are used for project-specific skills and for the project CLAUDE.md skills section.

Managed Global Roots

Scan these roots relative to the user home directory:

~/.claude/skills/
~/.codex/skills/

These roots are used for managed runtime installs and inventory reporting.

Deprecated Import-Only Root

~/.claude/gsd-core/skills/

This root is kept for legacy migration only. Inventory code may report it, but new installs should not write here.

Legacy Claude Commands

~/.claude/commands/gsd/

This is not a skills root. Discovery code only checks whether it exists so inventory can report legacy Claude installs.

Normalization Rules

Scan only subdirectories that contain SKILL.md.
Read name and description from YAML frontmatter.
Use the directory name when name is missing.
Extract trigger hints from body lines that match TRIGGER when: ....
Treat gsd-* directories as installed framework skills.
Treat ~/.claude/gsd-core/skills/ entries as deprecated/import-only.
Treat ~/.claude/commands/gsd/ as legacy command installation metadata, not skills.

Scanner Behavior

`src/profile-output.cts`

Builds the project CLAUDE.md skills section.
Scans project roots only.
Skips gsd-* directories so the project section stays focused on user/project skills.
Adds .codex/skills/ to the project discovery set.

`src/init.cts`

Generates the skill inventory object for skill-manifest.
Reports skills, roots, installation, and counts.
Marks gsd_skills_installed when any discovered skill name starts with gsd-.
Marks legacy_claude_commands_installed when ~/.claude/commands/gsd/ contains .md command files.

Inventory Shape

skill-manifest returns a JSON object with:

skills: normalized skill entries
roots: the canonical roots that were checked
installation: summary booleans for installed GSD skills and legacy Claude commands
counts: small inventory counts for downstream consumers

Each skill entry includes:

name
description
triggers
path
file_path
root
scope
installed
deprecated

2.4 KiB Raw Blame History