From 1adf6d2245ae55d6f93f0d1d1ed7812d25d8b194 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Wed, 19 Aug 2026 01:54:01 -0400 Subject: [PATCH] fix(#3620): point the docs at files that actually exist (#3658) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 --- .changeset/sturdy-mice-sprint.md | 5 +++++ CONTEXT.md | 4 ++-- VERSIONING.md | 6 +++--- docs/CONFIGURATION.md | 2 +- docs/INVENTORY.md | 2 +- docs/TESTING-SUITES.md | 20 ++++++++++++++----- docs/how-to/configure-model-profiles.md | 2 +- docs/ja-JP/INVENTORY.md | 2 +- docs/ja-JP/how-to/configure-model-profiles.md | 2 +- docs/ko-KR/INVENTORY.md | 2 +- docs/ko-KR/how-to/configure-model-profiles.md | 2 +- docs/pt-BR/CONFIGURATION.md | 2 +- docs/pt-BR/INVENTORY.md | 2 +- docs/pt-BR/how-to/configure-model-profiles.md | 2 +- docs/skills/discovery-contract.md | 10 ++-------- docs/zh-CN/CONFIGURATION.md | 2 +- docs/zh-CN/INVENTORY.md | 2 +- docs/zh-CN/how-to/configure-model-profiles.md | 2 +- gsd-core/workflows/update.md | 2 +- scripts/changeset/lint.cjs | 2 -- 20 files changed, 41 insertions(+), 34 deletions(-) create mode 100644 .changeset/sturdy-mice-sprint.md diff --git a/.changeset/sturdy-mice-sprint.md b/.changeset/sturdy-mice-sprint.md new file mode 100644 index 000000000..9f69d64e9 --- /dev/null +++ b/.changeset/sturdy-mice-sprint.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 3658 +--- +**Documentation no longer points at files that were renamed or deleted** — `docs/INVENTORY.md` claimed its roster was anchored by six drift-control tests when five had been deleted, and the four translations named a seventh that the English file had already dropped. `CONTEXT.md`, `VERSIONING.md`, `docs/CONFIGURATION.md` and `docs/skills/discovery-contract.md` pointed at `issue-NNN-` test filenames and `sdk/` paths that no longer exist, and `VERSIONING.md` described an SDK bundling step the release workflow does not perform. Most consequentially, `docs/TESTING-SUITES.md` instructed contributors to add drift acknowledgments to a file `CONTRIBUTING.md` says to never use — following it put the entry where the contributing guide forbids. (#3620) diff --git a/CONTEXT.md b/CONTEXT.md index 00c968fda..2c932ba31 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -242,7 +242,7 @@ A **genuine leaf** (node builtins only) owning the typed IR for `~/.codex/agents Single seam owning GSD's published-package coordinates so a repoint/rename is a one-line change instead of a tree-wide sweep. Source of truth is `package.json`; values are *derived*, not re-typed: `packageName` (`.name` → `@opengsd/gsd-core`), `binName` (`Object.keys(.bin)[0]` → `gsd-core`), `repoSlug` (parsed from `.repository.url` → `open-gsd/gsd-core`), plus derived `changelogRawUrl` and `manualInstallCommand({ scope, runtime })`. Generated `.cjs` per ADR-457 (generated-single-source); shipped under `gsd-core/bin/lib/`. Three consumer worlds: **Node** consumers `require()` it at runtime (worker, `check-latest-version.cjs`, `bin/install.js`); the **bash launcher** snippet receives the literal injected by `scripts/sync-runtime-launcher.cjs` at sync time; **prose/help** literals (`update.md`, installer help) carry a committed copy. A drift-guard lint (`scripts/lint-package-identity-drift.cjs`, sibling to `check:alias-drift`) fails CI on any raw package/repo literal outside `package.json`, the generated module, and the value-checked materialization sites — this is what keeps the seam real (`two adapters`, not one). Replaces the contradictory pair it consolidates: the runtime-broken `require('../package.json').name` in `hooks/gsd-check-update-worker.js` (#378, resolves to `undefined` post-install) and the hardcoded constant in `check-latest-version.cjs` (#2992). _Avoid_: "package name string", "the npm name" (when you mean the seam). See ADR-457 and Installer Module. ### Update Context Module [Planned] -Module owning install detection for `/gsd:update`. `resolveUpdateContext({ home, cwd, env, fs, preferredConfigDir, preferredRuntime })` is a pure, injected-fs port of update.md's former ~280-line `get_installed_version` bash; it reproduces the full precedence cascade — preferred-config-dir fast path, local-over-global probe with same-path dedup, env-var overrides (`CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG`, `KILO_CONFIG`, `XDG_CONFIG_HOME`, `CODEX_HOME`, …), and semver validation — and returns the 4-field contract `{ installedVersion, scope, runtime, gsdDir }` (scope ∈ `LOCAL`/`GLOBAL`/`UNKNOWN`). Antigravity is modelled first-class (its `.gemini/antigravity{,-ide,-cli}` dirs probe before bare `.gemini`; #3608). Exposed to the workflow as `gsd-tools update-context [--config-dir ] [--runtime ] --json`; `loadUpdateContext` wires the real fs. The workflow keeps only the execution_context path → `PREFERRED_*` derivation (the one input it alone knows). Source: `gsd-core/bin/lib/update-context.cjs`; tests: `tests/issue-498-update-context.test.cjs`. See Installer Module and Package Identity Module. +Module owning install detection for `/gsd:update`. `resolveUpdateContext({ home, cwd, env, fs, preferredConfigDir, preferredRuntime })` is a pure, injected-fs port of update.md's former ~280-line `get_installed_version` bash; it reproduces the full precedence cascade — preferred-config-dir fast path, local-over-global probe with same-path dedup, env-var overrides (`CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG`, `KILO_CONFIG`, `XDG_CONFIG_HOME`, `CODEX_HOME`, …), and semver validation — and returns the 4-field contract `{ installedVersion, scope, runtime, gsdDir }` (scope ∈ `LOCAL`/`GLOBAL`/`UNKNOWN`). Antigravity is modelled first-class (its `.gemini/antigravity{,-ide,-cli}` dirs probe before bare `.gemini`; #3608). Exposed to the workflow as `gsd-tools update-context [--config-dir ] [--runtime ] --json`; `loadUpdateContext` wires the real fs. The workflow keeps only the execution_context path → `PREFERRED_*` derivation (the one input it alone knows). Source: `gsd-core/bin/lib/update-context.cjs`; tests: `tests/update-context.test.cjs`. See Installer Module and Package Identity Module. ### Skill Surface Budget Module Module owning which skills and agents are written to runtime config directories at install time (Phase 1) and at runtime via cluster-level toggles (Phase 2). Phase 1: `gsd-core/bin/lib/install-profiles.cjs` defines named profiles (`core`, `standard`, `full`), computes transitive closure over `requires:` frontmatter, stages skills/agents to runtime config dirs, and persists the chosen profile in a `.gsd-profile` marker. Profile resolution precedence: explicit `--profile=` flag > `.gsd-profile` marker > `full`. `--minimal`/`--core-only` are back-compat aliases for `--profile=core`. Phase 2: `gsd-core/bin/lib/surface.cjs` implements the `/gsd:surface` slash command for cluster-level enable/disable without reinstall; cluster definitions live in `gsd-core/bin/lib/clusters.cjs`; per-runtime state persists in `/.gsd-surface.json` independent from the `.gsd-profile` marker. See ADR-0011. @@ -395,7 +395,7 @@ Standalone hook-surface writer module extracted from `bin/install.js` as ADR-857 Module owning the explicit per-runtime config-mutation dispatch table for the installer. `resolveRuntimeConfigIntent(runtime)` projects a typed config intent — `installSurface` (`settings-json` | `codex-toml` | `copilot-instructions` | `cline-rules` | `cursor-hooks-json` | `profile-marker-only`), `writesSharedSettings` (the `finishInstall` shared-settings write gate), and `finishPermissionWriter` (`opencode` | `kilo` | `antigravity` | none) — that `bin/install.js` dispatches on instead of inline `runtime === '...'` branching. Owns adapter selection only: it performs no filesystem IO and does not execute config mutations (the install/finishInstall handlers and the per-runtime writers do that). Unknown runtimes fail loudly with a `TypeError`, guarded by an `Object.hasOwn` own-property check so prototype-chain keys (`__proto__`, `constructor`) also throw. Also exports `resolveInstallPlan(runtime)` — the ADR-58 `InstallPlan` capstone — which collects the install-level descriptor axes (`installSurface`, `writesSharedSettings`, `finishPermissionWriter`, `hookEvents`, `extendedHookEvents`, `hooksSurface`, `sandboxTier`) into one typed `InstallPlan` value consumed by `install()` and `finishInstall()` in `bin/install.js`. `sandboxTier` (`none` | `codex-agent-sandbox`) gates per-agent `sandbox_mode` emission in the codex TOML path and fails loud on a missing/invalid value (#1151). The spatial axes (`configHome`, `artifactLayout`, `commandStyle`) remain behind their self-resolving adapter modules and are not part of the plan; they are the execution adapters. Realizes both the adapter-selection and plan-collection halves of the Runtime Install Policy Module boundary. Source: `gsd-core/bin/lib/runtime-config-adapter-registry.cjs`. See ADR-58, #60. ### Claude Code Plugin Manifest Module -Module owning the projection of gsd-core's artifact surfaces (`commands`, `agents`, hooks) onto the Claude Code plugin contract (`.claude-plugin/plugin.json` + `hooks/hooks.json`) — the plugin-contract sibling of the Runtime Artifact Layout Module (which projects the same surfaces onto filesystem placements). Defined mapping: `name`=`binName` (drives the `/gsd-core:` command namespace), `repository`/`homepage`=`repoUrl` (Package Identity Module), `version`/`description`/`license` from `package.json` (`version` is required for `claude plugin validate --strict`), `commands`=`./commands/gsd/`, agents via Claude Code's default `agents/` discovery (the explicit string form is schema-rejected), `hooks`=`./hooks/hooks.json`. The hook projection carries ONLY the always-on subset of the Installer Module's Claude `settings.json` wiring (check-update, context-monitor, prompt-guard, read-guard, worktree-path-guard, read-injection-scanner, write-guard) via `${CLAUDE_PLUGIN_ROOT}`; config-gated opt-in hooks are excluded because a static manifest cannot honor per-project config gates, and plugin-shipped agents cannot carry hook frontmatter (so all plugin-path hook wiring lives in hooks.json). `hooks.json` covers all seven Claude Code lifecycle events: SessionStart, PreToolUse, PostToolUse, SubagentStop, Stop, PreCompact (all wired to context-monitor for context-headroom awareness), and FileChanged (matcher: `config.json` → config-reload, injects `additionalContext` when `.planning/config.json` changes mid-session). Additive — the file-copy path (Runtime Artifact Layout / Install Policy / Installer Modules) is unchanged. Conformance is validated by `claude plugin validate --strict` plus the in-repo drift-guard `tests/issue-766-plugin-manifest.test.cjs`. _Avoid_: "the plugin API", "the plugin file" (when you mean the seam). See ADR-766 and Runtime Artifact Layout Module. +Module owning the projection of gsd-core's artifact surfaces (`commands`, `agents`, hooks) onto the Claude Code plugin contract (`.claude-plugin/plugin.json` + `hooks/hooks.json`) — the plugin-contract sibling of the Runtime Artifact Layout Module (which projects the same surfaces onto filesystem placements). Defined mapping: `name`=`binName` (drives the `/gsd-core:` command namespace), `repository`/`homepage`=`repoUrl` (Package Identity Module), `version`/`description`/`license` from `package.json` (`version` is required for `claude plugin validate --strict`), `commands`=`./commands/gsd/`, agents via Claude Code's default `agents/` discovery (the explicit string form is schema-rejected), `hooks`=`./hooks/hooks.json`. The hook projection carries ONLY the always-on subset of the Installer Module's Claude `settings.json` wiring (check-update, context-monitor, prompt-guard, read-guard, worktree-path-guard, read-injection-scanner, write-guard) via `${CLAUDE_PLUGIN_ROOT}`; config-gated opt-in hooks are excluded because a static manifest cannot honor per-project config gates, and plugin-shipped agents cannot carry hook frontmatter (so all plugin-path hook wiring lives in hooks.json). `hooks.json` covers all seven Claude Code lifecycle events: SessionStart, PreToolUse, PostToolUse, SubagentStop, Stop, PreCompact (all wired to context-monitor for context-headroom awareness), and FileChanged (matcher: `config.json` → config-reload, injects `additionalContext` when `.planning/config.json` changes mid-session). Additive — the file-copy path (Runtime Artifact Layout / Install Policy / Installer Modules) is unchanged. Conformance is validated by `claude plugin validate --strict` plus the in-repo drift-guard `tests/plugin-manifest.test.cjs`. _Avoid_: "the plugin API", "the plugin file" (when you mean the seam). See ADR-766 and Runtime Artifact Layout Module. ### Knowledge Graph Module Module owning the graphify integration: tri-state capability gate (`isCapabilityActive('graphify', cwd)` from capability-state.cjs — requires installed AND surfaced AND config-enabled; replaces the former config-only `isGraphifyEnabled` gate, cutover in #1306), disabled response (`disabledResponse`), subprocess helper (`execGraphify`, typed `GRAPHIFY_REASON` enum), presence detection (`checkGraphifyInstalled`), version checking (`checkGraphifyVersion`), query surface (`graphifyQuery` — BFS seed-expand + budget trim), status surface (`graphifyStatus` — node/edge counts, mtime staleness, commit-staleness tri-state via `built_at_commit`/`commits_behind`/`commit_stale`), diff surface (`graphifyDiff` — added/removed/changed nodes+edges), build pre-flight (`graphifyBuild`), snapshot management (`writeSnapshot`). Config leg reads `.planning/config.json:graphify.enabled`; all three legs (install, surface, config) must be active; writes to `.planning/graphs/`. Graph location override (#1825): `graphify.graph_path` in `.planning/config.json` (a path relative to the project root, or absolute) redirects where `graphifyQuery`/`graphifyStatus`/`graphifyDiff` read `graph.json` — so one umbrella-level cross-repo graph serves multiple sibling projects without N drifting mirror copies; the diff snapshot (`.last-build-snapshot.json`) travels with the configured graph (same dir); the auto-update status sidecar stays project-local; `writeSnapshot` honors the key (reads the configured graph, writes the snapshot alongside it); build stays project-scoped (`.planning/graphs/`) since the build skill hardcodes that destination — the umbrella graph is built in the umbrella project and sub-projects only READ it. Unset/blank/non-string → byte-identical `.planning/graphs/graph.json` default; a configured-but-missing file yields an actionable error naming the path. The key is registered in `config-schema.manifest.json` `validKeys`. Auto-update hook (`hooks/gsd-graphify-update.sh`) triggers a detached background rebuild after HEAD-advancing git operations on the default branch when `graphify.auto_update=true`. Status file `.planning/graphs/.last-build-status.json` carries `{ ts, status, exit_code, duration_ms, head_at_build, graphify_version }`. Graph IR uses `nodes[]`, `edges[]` (or `links[]` for graphify ≥0.7 compat), `hyperedges[]`, `built_at_commit`. `commit_stale` is tri-state: `false` (known fresh), `true` (stale), `null` (unknown — no git or pre-v0.7 graph). Source: `gsd-core/bin/lib/graphify.cjs`. Skill: `commands/gsd/graphify.md`. diff --git a/VERSIONING.md b/VERSIONING.md index 1ba485a44..dd821c209 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -80,12 +80,12 @@ Hotfixes are dispatched via the **Release workflow (`release.yml`)** with a patc - Branches `hotfix/1.27.1` from `BASE_TAG`. - Auto-cherry-picks every `fix:`/`chore:` commit on `origin/main` not already in the base, oldest-first. Patch-equivalents are skipped via `git cherry`. `feat:`/`refactor:` are **never** auto-included. - On conflict the workflow halts with the offending SHA. Resolve manually on the branch, then re-run finalize with `auto_cherry_pick=false`. - - Bumps `package.json` (and `sdk/package.json`), pushes the branch, and lists every included SHA in the run summary. + - Bumps `package.json`, pushes the branch, and lists every included SHA in the run summary. 2. (Optional) push additional manual commits to `hotfix/1.27.1`. 3. Trigger `release.yml` with `action=finalize`. The workflow: - Runs `install-smoke` cross-platform gate. - Runs full test suite + coverage. - - Builds SDK, bundles `sdk-bundle/gsd-sdk.tgz` inside the CC tarball. + - Promotes CHANGELOG from merged fragments. - Tags `v1.27.1`, publishes to `@latest`, re-points `@next → v1.27.1`. - Opens merge-back PR against `main`. @@ -142,7 +142,7 @@ they are included in the release commit alongside `package.json`. To add a new manifest that must track the package version, register its path (and, if its version field is not top-level, its dotted `versionKey`) in the `VERSIONED_MANIFESTS` array in `scripts/sync-manifest-versions.cjs`. A -regression test (`tests/issue-844-manifest-version-sync.test.cjs`) enforces this: +regression test (`tests/manifest-version-sync.test.cjs`) enforces this: it scans all committed JSON files for a matching `version` field and fails if any are missing from the registry. diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 3e7fc09ba..35cabfba2 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -1239,7 +1239,7 @@ Invalid flag tokens are sanitized and logged as warnings. Only recognized GSD fl | gsd-doc-writer | Opus | Sonnet | Haiku | Sonnet | Inherit | | gsd-doc-verifier | Sonnet | Sonnet | Haiku | Haiku | Inherit | -> **All 33 shipped agents have explicit per-profile tier assignments** in the catalog (`sdk/shared/model-catalog.json`). The table above shows a representative subset of the most-used agents. For agents not listed here, `model_overrides` accepts any shipped agent name. The authoritative profile data is derived from `sdk/shared/model-catalog.json` via `gsd-core/bin/lib/model-catalog.cjs` and `sdk/src/model-catalog.ts`. +> **All 33 shipped agents have explicit per-profile tier assignments** in the catalog (`gsd-core/bin/shared/model-catalog.json`). The table above shows a representative subset of the most-used agents. For agents not listed here, `model_overrides` accepts any shipped agent name. The authoritative profile data is derived from `gsd-core/bin/shared/model-catalog.json` via `src/model-catalog.cts`. ### Per-Agent Overrides diff --git a/docs/INVENTORY.md b/docs/INVENTORY.md index a45d0f7bb..222cdbc8b 100644 --- a/docs/INVENTORY.md +++ b/docs/INVENTORY.md @@ -6,7 +6,7 @@ - The machine-readable roster lives in `docs/INVENTORY-MANIFEST.json` (regenerated by `scripts/gen-inventory-manifest.cjs --write`). For live counts, run `ls agents/gsd-*.md | wc -l` etc. against the checkout. - This file enumerates every shipped surface across all six families (agents, commands, workflows, references, CLI modules, hooks). Broad docs may render narrative or curated subsets; when they disagree with the filesystem, this file and the directory listings are authoritative. -- New surfaces should land here first, then propagate to the broad docs. The drift-control tests in `tests/inventory-manifest-sync.test.cjs`, `tests/commands-doc-parity.test.cjs`, `tests/agents-doc-parity.test.cjs`, `tests/cli-modules-doc-parity.test.cjs`, `tests/hooks-doc-parity.test.cjs`, and `tests/command-count-sync.test.cjs` anchor the roster contents against the filesystem. +- New surfaces should land here first, then propagate to the broad docs. The drift-control test in `tests/inventory-manifest-sync.test.cjs` anchors the roster contents against the filesystem. This is the authoritative roster of every shipped GSD Core surface. See the [docs index](README.md) to navigate by topic. diff --git a/docs/TESTING-SUITES.md b/docs/TESTING-SUITES.md index e8315f657..65feb9a51 100644 --- a/docs/TESTING-SUITES.md +++ b/docs/TESTING-SUITES.md @@ -137,10 +137,19 @@ The differential attribution check reports the file and the byte delta. To resol 1. **Justify the growth in your PR** (a sentence in the description is enough) — the acknowledgment entry (below) is the review record that the larger size was a deliberate, seen decision, not silent drift. -2. **Add an acknowledgment entry** in `tests/emitted-drift-ack.json` naming the - file and the reason, per `CONTEXT.md`'s `### Emitted Artifact Provenance` - entry. This is deliberately a committed file, not a flag — the entry appears - in your PR diff, so touching it *is* the visible signal. +2. **Add an acknowledgment fragment** under `tests/emitted-drift-acks/` naming + the file and the reason, per `CONTRIBUTING.md`'s "Editing shipped content" + section and `CONTEXT.md`'s `### Emitted Artifact Provenance` entry. Name the + fragment for your issue or PR (something nobody else is using) — the failure + output prints a minimal valid document you can paste. This is deliberately a + per-PR fragment, not one shared file: fragments can never conflict across + PRs, and a fragment appearing in your diff *is* the visible signal. If the + failure instead names a path a merged PR already acknowledged (a **spent** + entry sitting in an existing fragment), reword that fragment's `reason` in + place to explain the new ripple — do not add a duplicate entry for the same + path; two ack sources naming the same path is a hard, loudly-reported error. + The legacy single `tests/emitted-drift-ack.json` is still read and unioned + in for branches that carry it, but new acknowledgments never go there. 3. **Or shrink it instead of acknowledging.** Prefer extraction when the growth is incidental: for a workflow, move per-mode bodies to `workflows//modes/`, templates to `workflows//templates/`, and @@ -160,7 +169,8 @@ help — that is the signal to extract, per step 3. |---|---| | `scripts/workflow-size.cjs` | Single source of truth — LF-normalized byte counter (`lfByteCount`) + generic `measureMdFiles(dir, predicate)` (backs both workflows and agents) + workflow enumeration (`listWorkflowStems`, `measureWorkflows`). Imported by both guards and by `tests/helpers/emitted-runtime.cjs`'s `currentSizes()` so they can never measure differently. | | `tests/emitted-attribution.test.cjs` + `tests/helpers/emitted-diff.cjs` | The differential attribution check and its size ratchet (ADR-2719). The sole mechanism for both emitted-content propagation AND per-file size growth as of #2724. | -| `tests/emitted-drift-ack.json` | Committed acknowledgment file for unattributable emitted-content ripples and for size growth. Absent = no acks; its presence is the alarm. | +| `tests/emitted-drift-acks/` | Per-PR acknowledgment fragments (primary, #2914) for unattributable emitted-content ripples and for size growth. A fragment appearing in your diff *is* the alarm; absence is the healthy steady state. | +| `tests/emitted-drift-ack.json` | Legacy single acknowledgment file, superseded by the per-PR fragments above. Still read and unioned in for branches that carry it; must never gain new entries and must never persist on `next` (enforced by `guard-no-ack-on-next` via `scripts/lint-emitted-drift-ack.cjs --guard-next`). | | `npm run regen:derived` | Runs every remaining generator in dependency order (build → registry → ADR index → capability matrix → inventory manifest → manifest versions → `tests/fixtures/install-tree/*.json`). | | `tests/workflow-size-budget.test.cjs` | The workflow tier hard-cap guards, plus the `discuss-phase` progressive-disclosure checks. | | `tests/agent-size-budget.test.cjs` | The agent tier hard-cap guards (the agent analog). | diff --git a/docs/how-to/configure-model-profiles.md b/docs/how-to/configure-model-profiles.md index 58efb169f..7c4c0c380 100644 --- a/docs/how-to/configure-model-profiles.md +++ b/docs/how-to/configure-model-profiles.md @@ -16,7 +16,7 @@ Set `model_profile` in `.planning/config.json` or via `/gsd-config --profile **Todos os 33 agentes incluídos possuem atribuições explícitas de nível por perfil** no catálogo (`sdk/shared/model-catalog.json`). A tabela acima mostra um subconjunto representativo dos agentes mais usados. Para agentes não listados aqui, `model_overrides` aceita qualquer nome de agente incluído. Os dados autoritativos de perfil são derivados de `sdk/shared/model-catalog.json` via `gsd-core/bin/lib/model-catalog.cjs` e `sdk/src/model-catalog.ts`. +> **Todos os 33 agentes incluídos possuem atribuições explícitas de nível por perfil** no catálogo (`gsd-core/bin/shared/model-catalog.json`). A tabela acima mostra um subconjunto representativo dos agentes mais usados. Para agentes não listados aqui, `model_overrides` aceita qualquer nome de agente incluído. Os dados autoritativos de perfil são derivados de `gsd-core/bin/shared/model-catalog.json` via `src/model-catalog.cts`. ### Substituições por Agente diff --git a/docs/pt-BR/INVENTORY.md b/docs/pt-BR/INVENTORY.md index 00e3e5bbd..f1e158192 100644 --- a/docs/pt-BR/INVENTORY.md +++ b/docs/pt-BR/INVENTORY.md @@ -6,7 +6,7 @@ - As contagens aqui são derivadas do sistema de arquivos no pino v1.36.0 e podem divergir entre versões. Para contagens ao vivo, execute `ls commands/gsd/*.md | wc -l`, `ls agents/gsd-*.md | wc -l`, etc. na cópia local do repositório. - Este arquivo enumera toda superfície entregue em todas as seis famílias (agentes, comandos, workflows, referências, módulos de CLI, hooks). Documentações amplas podem apresentar narrativas ou subconjuntos curados; quando discordarem do sistema de arquivos, este arquivo e as listagens de diretório são autoritativos. -- Novas superfícies adicionadas após v1.36.0 devem aparecer aqui primeiro, depois propagar para as documentações amplas. Os testes de controle de drift em `tests/inventory-counts.test.cjs`, `tests/commands-doc-parity.test.cjs`, `tests/agents-doc-parity.test.cjs`, `tests/cli-modules-doc-parity.test.cjs`, `tests/hooks-doc-parity.test.cjs`, `tests/architecture-counts.test.cjs` e `tests/command-count-sync.test.cjs` ancoram as contagens e o conteúdo do registro ao sistema de arquivos. +- Novas superfícies adicionadas após v1.36.0 devem aparecer aqui primeiro, depois propagar para as documentações amplas. O teste de controle de drift em `tests/inventory-manifest-sync.test.cjs` ancora o conteúdo do registro ao sistema de arquivos. Este é o registro autoritativo de toda superfície do GSD Core entregue. Veja o [índice de documentação](README.md) para navegar por tópico. diff --git a/docs/pt-BR/how-to/configure-model-profiles.md b/docs/pt-BR/how-to/configure-model-profiles.md index 4f04d6b43..f797b697a 100644 --- a/docs/pt-BR/how-to/configure-model-profiles.md +++ b/docs/pt-BR/how-to/configure-model-profiles.md @@ -16,7 +16,7 @@ Defina `model_profile` em `.planning/config.json` ou via `/gsd-config --profile | `adaptive` | Opus | Sonnet | Sonnet | Sonnet | Resolve da mesma forma que os outros níveis em perfis cientes de runtime; use ao alternar entre runtimes com frequência | | `inherit` | (modelo da sessão) | (modelo da sessão) | (modelo da sessão) | (modelo da sessão) | Provedores não-Anthropic (OpenRouter, modelos locais) — todos os agentes seguem o modelo atual da sessão | -A tabela acima mostra um subconjunto representativo. Todos os 33 agentes incluídos possuem atribuições de nível explícitas por perfil em `sdk/shared/model-catalog.json`. Para a tabela completa, consulte [Perfis de Modelo](../CONFIGURATION.md#model-profiles) na referência de configuração. +A tabela acima mostra um subconjunto representativo. Todos os 33 agentes incluídos possuem atribuições de nível explícitas por perfil em `gsd-core/bin/shared/model-catalog.json`. Para a tabela completa, consulte [Perfis de Modelo](../CONFIGURATION.md#model-profiles) na referência de configuração. **Troca rápida via comando:** diff --git a/docs/skills/discovery-contract.md b/docs/skills/discovery-contract.md index a8e45528f..f1165ad56 100644 --- a/docs/skills/discovery-contract.md +++ b/docs/skills/discovery-contract.md @@ -49,20 +49,14 @@ This is not a skills root. Discovery code only checks whether it exists so inven ## Scanner Behavior -### `sdk/src/query/skills.ts` - -- Returns a de-duplicated list of discovered skill names. -- Scans project roots plus managed global roots. -- Does not scan the deprecated import-only root. - -### `gsd-core/bin/lib/profile-output.cjs` +### `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. -### `gsd-core/bin/lib/init.cjs` +### `src/init.cts` - Generates the skill inventory object for `skill-manifest`. - Reports `skills`, `roots`, `installation`, and `counts`. diff --git a/docs/zh-CN/CONFIGURATION.md b/docs/zh-CN/CONFIGURATION.md index dd20faa72..438b7563b 100644 --- a/docs/zh-CN/CONFIGURATION.md +++ b/docs/zh-CN/CONFIGURATION.md @@ -757,7 +757,7 @@ gsd-tools query config-set features.thinking_partner false | gsd-doc-writer | Opus | Sonnet | Haiku | Sonnet | Inherit | | gsd-doc-verifier | Sonnet | Sonnet | Haiku | Haiku | Inherit | -> **所有 33 个发布 agent 在目录（`sdk/shared/model-catalog.json`）中均有显式的按配置文件层级分配。** 上表显示最常用 agent 的代表性子集。对于此处未列出的 agent，`model_overrides` 接受任何已发布的 agent 名称。权威的配置文件数据通过 `gsd-core/bin/lib/model-catalog.cjs` 和 `sdk/src/model-catalog.ts` 从 `sdk/shared/model-catalog.json` 导出。 +> **所有 33 个发布 agent 在目录（`gsd-core/bin/shared/model-catalog.json`）中均有显式的按配置文件层级分配。** 上表显示最常用 agent 的代表性子集。对于此处未列出的 agent，`model_overrides` 接受任何已发布的 agent 名称。权威的配置文件数据通过 `src/model-catalog.cts` 从 `gsd-core/bin/shared/model-catalog.json` 导出。 ### 按 Agent 覆盖 diff --git a/docs/zh-CN/INVENTORY.md b/docs/zh-CN/INVENTORY.md index f76c490fe..5df0a30db 100644 --- a/docs/zh-CN/INVENTORY.md +++ b/docs/zh-CN/INVENTORY.md @@ -6,7 +6,7 @@ - 本文件中的数量基于 v1.36.0 快照，版本之间可能存在偏差。如需实时数量，请在检出目录中运行 `ls commands/gsd/*.md | wc -l`、`ls agents/gsd-*.md | wc -l` 等命令。 - 本文件列举了所有六大类别（代理、命令、工作流、参考资料、CLI 模块、钩子）中的每个已发布功能面。广义文档可能呈现叙述性内容或精选子集；当其与文件系统不一致时，本文件及目录清单为准。 -- v1.36.0 之后新增的功能面应首先在此处记录，再传播到广义文档中。`tests/inventory-counts.test.cjs`、`tests/commands-doc-parity.test.cjs`、`tests/agents-doc-parity.test.cjs`、`tests/cli-modules-doc-parity.test.cjs`、`tests/hooks-doc-parity.test.cjs`、`tests/architecture-counts.test.cjs` 和 `tests/command-count-sync.test.cjs` 中的漂移控制测试将数量和清单内容锚定到文件系统。 +- v1.36.0 之后新增的功能面应首先在此处记录，再传播到广义文档中。`tests/inventory-manifest-sync.test.cjs` 中的漂移控制测试将清单内容锚定到文件系统。 这是所有已发布 GSD Core 功能面的权威目录。请参阅 [文档索引](README.md) 按主题导航。 diff --git a/docs/zh-CN/how-to/configure-model-profiles.md b/docs/zh-CN/how-to/configure-model-profiles.md index 2bb89ae40..d667429c5 100644 --- a/docs/zh-CN/how-to/configure-model-profiles.md +++ b/docs/zh-CN/how-to/configure-model-profiles.md @@ -16,7 +16,7 @@ | `adaptive` | Opus | Sonnet | Sonnet | Sonnet | 与其他层级在运行时感知配置文件下的解析方式相同；在频繁切换运行时环境时使用 | | `inherit` | （会话模型） | （会话模型） | （会话模型） | （会话模型） | 非 Anthropic 提供商（OpenRouter、本地模型）——所有代理遵循当前会话模型 | -上表展示的是代表性子集。全部 33 个内置代理在 `sdk/shared/model-catalog.json` 中均有明确的按配置文件层级分配。完整表格请参阅配置参考中的 [模型配置文件](../CONFIGURATION.md#model-profiles)。 +上表展示的是代表性子集。全部 33 个内置代理在 `gsd-core/bin/shared/model-catalog.json` 中均有明确的按配置文件层级分配。完整表格请参阅配置参考中的 [模型配置文件](../CONFIGURATION.md#model-profiles)。 **通过命令快速切换：** diff --git a/gsd-core/workflows/update.md b/gsd-core/workflows/update.md index f67d937aa..7b1c44e09 100644 --- a/gsd-core/workflows/update.md +++ b/gsd-core/workflows/update.md @@ -78,7 +78,7 @@ Parse output: - Line 4 = resolved GSD config dir (e.g. `/Users/me/.claude`, `/Users/me/.gemini`); empty if scope is `UNKNOWN`. Capture this as `GSD_DIR` and pass it to subsequent steps so they don't re-derive the runtime path. - If scope is `UNKNOWN`, proceed to install using the `--claude --global` fallback. -`update-context` reproduces the previous detection cascade — preferred-config-dir fast path, local-over-global with same-path dedup (so `CWD=$HOME` does not misdetect as LOCAL), env-var overrides (`CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`, `KILO_CONFIG`, `XDG_CONFIG_HOME`, `CODEX_HOME`, …), and semver validation — but as a tested projection rather than ~280 lines of inline bash. Branch coverage lives in `tests/issue-498-update-context.test.cjs`. +`update-context` reproduces the previous detection cascade — preferred-config-dir fast path, local-over-global with same-path dedup (so `CWD=$HOME` does not misdetect as LOCAL), env-var overrides (`CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`, `KILO_CONFIG`, `XDG_CONFIG_HOME`, `CODEX_HOME`, …), and semver validation — but as a tested projection rather than ~280 lines of inline bash. Branch coverage lives in `tests/update-context.test.cjs`. If multiple runtime installs are detected and the invoking runtime cannot be determined from execution_context, ask the user which runtime to update before running install. diff --git a/scripts/changeset/lint.cjs b/scripts/changeset/lint.cjs index 7413bff5c..4fb010322 100755 --- a/scripts/changeset/lint.cjs +++ b/scripts/changeset/lint.cjs @@ -36,8 +36,6 @@ const USER_FACING_PREFIXES = [ 'agents/', 'commands/', 'hooks/', - 'sdk/src/', - 'sdk/prompts/', ]; // Exact-match user-facing files. Any direct edit to one of these without a