@hegemonart/get-design-done 1.41.0 → 1.42.0

package/dist/claude-code/.claude/skills/watch-authorities/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gdd-watch-authorities
+description: "Fetches the design-authority feed whitelist, diffs against .design/authority-snapshot.json, and writes .design/authority-report.md (consumed by /gdd:reflect). Authority monitoring only — no trend-watching."
+argument-hint: "[--refresh] [--since <date>] [--feed <name>] [--schedule <weekly|daily|monthly>]"
+tools: Read, Write, Task, Bash
+---
+
+# /gdd:watch-authorities
+
+Runs `design-authority-watcher` on demand. Fetches the curated design-authority feed whitelist, diffs against the prior snapshot, classifies new entries into five buckets, and writes `.design/authority-report.md`. Phase 11's reflector picks up the report automatically when you next run `/gdd:reflect`.
+
+Authority-monitoring only. Not trend-watching. See `reference/authority-feeds.md` §"Rejected kinds" for what this skill will never fetch.
+
+## Steps
+
+1. **Parse args.** Extract optional flags: `--refresh`, `--since <date>`, `--feed <name>`, `--schedule <cadence>`. Anything that doesn't match one of these is an error — print `Unknown flag: <arg>. Valid flags: --refresh --since <date> --feed <name> --schedule <weekly|daily|monthly>.` and STOP.
+
+   Mutual exclusion rules:
+   - `--schedule` is handled entirely by this skill — it does not combine with the other three. If `--schedule` is present alongside any of `--refresh | --since | --feed`, print `--schedule cannot combine with other flags. Schedule registration runs this skill with no flags at the configured cadence.` and STOP.
+   - `--refresh` and `--since` are mutually exclusive — print `--refresh and --since are mutually exclusive. --refresh re-seeds the snapshot silently; --since surfaces a backlog from a boundary date. Pick one.` and STOP.
+
+2. **Handle `--schedule <cadence>` branch** (early-return).
+
+   If `--schedule` is set:
+   - Validate cadence ∈ {`weekly`, `daily`, `monthly`}; else print `Unknown cadence: <value>. Use one of: weekly, daily, monthly.` and STOP.
+   - Probe for the scheduled-tasks MCP via ToolSearch:
+
+     ```
+     ToolSearch({ query: "scheduled-tasks", max_results: 3 })
+     ```
+
+   - If the probe returns an empty result set: print `scheduled-tasks MCP not connected. Install it with: claude mcp add scheduled-tasks ... then retry with --schedule.` — this is a documented fallback (not an error). Terminate with `## WATCH COMPLETE` and exit 0.
+   - If the probe returns one or more `scheduled-tasks` tools: register the cron. Discover the MCP's registration tool name at runtime from the ToolSearch result and follow its schema. Target command: `/gdd:watch-authorities` with NO flags (the cron invokes the default diff-and-report behavior). Cadence → cron expression mapping:
+     - `weekly`  → `0 9 * * 1` (Mondays 09:00 local)
+     - `daily`   → `0 9 * * *` (every day 09:00 local)
+     - `monthly` → `0 9 1 * *` (1st of each month 09:00 local)
+   - After registration: print `Scheduled /gdd:watch-authorities to run <cadence>.` and terminate with `## WATCH COMPLETE`.
+
+3. **Validate `--since <date>`** (if present).
+
+   Accept ISO8601 (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`). Sanity-check via Bash `date -d "<value>" +%s` (GNU) or the POSIX equivalent `python3 -c "from datetime import datetime; datetime.fromisoformat('<value>'.replace('Z','+00:00'))"`. On parse failure: print `Invalid --since value: <value>. Use ISO8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ).` and STOP.
+
+   If the parsed date is earlier than `2020-01-01`, ask: `Very old --since value: <value>. Did you mean something more recent? Proceed? [y/N]`. On anything other than `y`/`Y`, STOP.
+
+4. **Spawn the watcher.**
+
+   Build the `Task(subagent_type="design-authority-watcher", ...)` prompt. The prompt supplies the agent's required-reading block (watcher step 0), echoes the invocation flags verbatim (watcher Flags section), and instructs the agent to follow its own fetch/diff/classify/write loop:
+
+   ```
+   Task("design-authority-watcher", """
+   <required_reading>
+   @reference/authority-feeds.md
+   @.design/authority-snapshot.json
+   @.design/STATE.md
+   </required_reading>
+
+   Invocation flags: <joined flag list or "none">
+
+   Fetch the feeds listed in reference/authority-feeds.md, diff against .design/authority-snapshot.json,
+   classify new entries per the D-17 decision table, write .design/authority-snapshot.json and
+   .design/authority-report.md.
+
+   Terminate with ## WATCH COMPLETE.
+   """)
+   ```
+
+   `<joined flag list>` is the subset of `--refresh | --since <date> | --feed <name>` actually passed — e.g., `--refresh`, `--since 2026-03-01`, `--feed wai-aria-apg`, `--refresh --feed radix-ui-releases`, or literally `none` when no flags were supplied.
+
+5. **Print summary.**
+
+   After the agent returns:
+   - If STATE.md gained a `<blocker type="contract-violation">` on this run (snapshot version mismatch, hash-format violation, or over-200 entries per feed), surface the blocker verbatim and stop — do not print the default "review and reflect" line.
+   - Otherwise print the agent's one-line stdout summary (normal mode: `Surfaced N entries across M feeds. K skipped. See .design/authority-report.md.`; first-run / refresh mode: `Seeded snapshot for N feeds — next run will surface new entries.`) followed by: `Review and reflect: /gdd:reflect`.
+
+6. **Terminate with `## WATCH COMPLETE`.**
+
+## Do Not
+
+- Do not modify `agents/design-authority-watcher.md`.
+- Do not modify `agents/design-reflector.md` — Phase 13.2 does not touch the reflector agent (CONTEXT.md D-25).
+- Do not write to `.design/authority-snapshot.json` or `.design/authority-report.md` directly — those are the agent's writes.
+- Do not fetch URLs outside `reference/authority-feeds.md`. The whitelist is the allow-list.

package/dist/claude-code/.claude/skills/zoom-out/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: zoom-out
+description: "Asks the agent to go up a layer of abstraction and map the relevant modules and callers using the project's CONTEXT.md vocabulary. Use when the user is working in an unfamiliar area of code and needs orientation before deep work."
+disable-model-invocation: true
+argument-hint: "[scope]"
+---
+
+Source: mattpocock/skills (MIT) — adapted with permission. See `../NOTICE` for the full attribution block.
+
+# Zoom Out
+
+**Role:** Give the user a map, not a fix.
+
+I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary (`CONTEXT.md`) vocabulary.
+
+When invoked, produce a one-screen map that names:
+
+1. **Modules in scope** — one-line description of each, using terms from `CONTEXT.md` (see `./../reference/context-md-format.md` for the schema). Do not invent terms.
+2. **Callers** — who calls these modules from elsewhere, with file paths.
+3. **Seams** — where data crosses module boundaries, named per `./../reference/architecture-vocabulary.md`.
+
+Do not propose fixes. Do not write code. The output is a map.
+
+If `CONTEXT.md` is absent, suggest `/gdd:discuss` to start one, but still produce the map using basenames and inferred terms.
+
+## ZOOM-OUT COMPLETE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.41.0",
+  "version": "1.42.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -23,6 +23,7 @@
     "sdk/",
     "recipes/",
     "docs/i18n/",
+    "dist/claude-code/",
     "scripts/lib/",
     "scripts/cli/",
     "scripts/install.cjs",
@@ -47,6 +48,8 @@
   },
   "scripts": {
     "build:bundles": "node scripts/build-distribution-bundles.cjs",
+    "build:skills": "node scripts/build-skills.cjs",
+    "build:skills:check": "node scripts/build-skills.cjs --check",
     "build:sdk": "node scripts/build-sdk-bins.cjs",
     "prepack": "npm run build:sdk",
     "postpack": "node scripts/build-sdk-bins.cjs --clean",
@@ -60,6 +63,7 @@
     "lint:changelog": "node scripts/lint-changelog.cjs",
     "lint:design": "node bin/gdd-detect test/fixtures/detect/negative --json",
     "sync:rule-catalogue": "node scripts/sync-rule-catalogue.cjs --check",
+    "validate:manifest": "node scripts/validate-manifest.cjs --check",
     "validate:schemas": "node --experimental-strip-types scripts/validate-schemas.ts",
     "validate:frontmatter": "node --experimental-strip-types scripts/validate-frontmatter.ts agents/",
     "detect:stale-refs": "node scripts/detect-stale-refs.cjs",

package/reference/DEPRECATIONS.md

@@ -28,6 +28,20 @@ the scanner pattern list in lockstep.
 - **`scan`** (stage name) → merged/renamed into `explore` in Phase 3. Migration: references to the `scan` stage in shipped skills and agents were replaced with `explore`.
 - **`discover`** (stage name) → merged/renamed into `explore` in Phase 3. Migration: references to the `discover` stage in shipped skills and agents were replaced with `explore`.
 
+## Authoring surfaces
+
+- **`skills/` as the authoring source** → **`source/skills/`** — deprecated in Phase 42 (multi-harness
+  source compilation). Skills are now authored once in `source/skills/` with placeholders
+  (`{{command_prefix}}` et al.; see `reference/skill-placeholders.md`) and compiled per-harness by
+  `scripts/build-skills.cjs`. The committed `skills/` tree is now a **generated artifact** (the Claude-Code
+  compile target) — CI's `npm run build:skills:check` drift-gates `committed === generated`.
+
+  Migration for contributors: **edit `source/skills/`, never `skills/` directly**, then run
+  `npm run build:skills` (or `gdd-sdk build skills`) and commit the regenerated `skills/` +
+  `dist/claude-code/`. `.claude-plugin/plugin.json`'s `"skills": ["./skills/"]` is unchanged — the plugin
+  still loads `skills/`, now produced from `source/skills/`. This is a path/authoring move only; no
+  stale-ref token is emitted (both paths are live), so the `detect-stale-refs.cjs` list is not extended.
+
 ## Scanner scope
 
 `scripts/detect-stale-refs.cjs` flags these tokens (line-granular match):

package/reference/registry.json

@@ -1042,6 +1042,13 @@
       "type": "meta-rules",
       "phase": 40.5,
       "description": "Phase 40.5 CLI-localization contract: locale resolution (config.locale > env LANG > en) + fallback chain locale->base->en + flat-JSON message tables via scripts/lib/i18n/index.cjs; tables at scripts/lib/i18n/messages/{en,ru,uk,de,fr,zh,ja}.json (en source-complete, ru full, 5 placeholders with en fallback); the opt-in description_i18n frontmatter (descriptionFor falls back to English); /gdd:locale skill; warn-only completeness; the add-a-locale contribution path (translate table + NOTICE credit + PR). Distinct from reference/i18n.md (which covers USER-design i18n)."
+    },
+    {
+      "name": "skill-placeholders",
+      "path": "reference/skill-placeholders.md",
+      "type": "meta-rules",
+      "phase": 42,
+      "description": "Phase 42 multi-harness skill-placeholder catalogue: the four placeholders ({{command_prefix}}/{{model}}/{{config_file}}/{{ask_instruction}}) + per-harness substitution table + the \\{{...}} escape + the <!-- harness-only: a,b --> block rule. Skills authored once in source/skills/, compiled per-harness by scripts/build-skills.cjs via scripts/lib/build/factory.cjs reading scripts/lib/manifest/harnesses.json."
     }
   ]
 }

package/reference/skill-placeholders.md

@@ -0,0 +1,71 @@
+# Skill Placeholders — Multi-Harness Source Compilation
+
+> Phase 42. Skills are authored once in `source/skills/` with placeholders and compiled per-harness into
+> `dist/<bundle>/<config-dir>/skills/...` by `scripts/build-skills.cjs` (the pure transform lives in
+> `scripts/lib/build/factory.cjs`; the per-harness values in `scripts/lib/build/harness-configs.cjs`,
+> which reads the Phase 41.5 manifest root `scripts/lib/manifest/harnesses.json`). The Claude-Code
+> compile target is the committed `skills/` tree; CI asserts `committed === generated` (the drift gate).
+
+## The four placeholders
+
+| Placeholder           | Meaning                                              | Claude value (round-trip anchor) |
+|-----------------------|------------------------------------------------------|----------------------------------|
+| `{{command_prefix}}`  | The slash-command invocation prefix before a verb.   | `/gdd:` (so `{{command_prefix}}audit` -> `/gdd:audit`) |
+| `{{model}}`           | How the skill refers to the active model.            | `your configured Claude model`   |
+| `{{config_file}}`     | The harness's settings/config file path.             | `.claude/settings.json`          |
+| `{{ask_instruction}}` | How the skill tells the user to query the agent.     | `ask Claude Code`                |
+
+Only `{{command_prefix}}` is currently woven through the migrated source (every literal `/gdd:` became
+`{{command_prefix}}`); the other three are documented + factory-supported for authors who need them.
+Because Claude's `command_prefix` is exactly `/gdd:`, `compile(source, claude)` reproduces `skills/`
+byte-for-byte — that pure-inverse property is what makes the drift gate safe.
+
+## Per-harness substitution table
+
+| Harness id    | `{{command_prefix}}` | `{{config_file}}`           |
+|---------------|----------------------|-----------------------------|
+| `claude`      | `/gdd:`              | `.claude/settings.json`     |
+| `codex`       | `/gdd-`             | `.codex/config.toml`        |
+| `gemini`      | `/gdd:`              | `.gemini/settings.json`     |
+| `qwen`        | `/gdd:`              | `.qwen/settings.json`       |
+| `kilo`        | `/gdd:`              | `.kilo/config.json`         |
+| `copilot`     | `/gdd:`              | `.copilot/config.json`      |
+| `cursor`      | `/gdd:`              | `.cursor/settings.json`     |
+| `windsurf`    | `/gdd:`              | `.windsurf/settings.json`   |
+| `antigravity` | `/gdd:`              | `.antigravity/config.json`  |
+| `augment`     | `/gdd:`              | `.augment/config.json`      |
+| `trae`        | `/gdd:`              | `.trae/config.json`         |
+| `codebuddy`   | `/gdd:`              | `.codebuddy/config.json`    |
+| `cline`       | `/gdd:`              | `.cline/config.json`        |
+| `opencode`    | `/gdd:`              | `.opencode/config.json`     |
+
+`codex` is the deliberate outlier: its custom-prompt grammar is flat (`/gdd-audit`), not the namespaced
+`/gdd:audit`. `{{model}}` and `{{ask_instruction}}` follow the pattern `your configured <Name> model` and
+`ask <Name>` respectively (see `harness-configs.cjs` for exact strings). Adding a 15th harness is one new
+entry in `scripts/lib/manifest/harnesses.json` plus an optional row in `harness-configs.cjs`.
+
+## Escaping a literal placeholder
+
+To emit a literal `{{command_prefix}}` (or any `{{...}}`) without substitution, backslash-escape the
+opening braces: write `\{{command_prefix}}`. The factory strips the backslash and leaves the braces
+untouched. Use this only when documenting the placeholder syntax itself.
+
+## Harness-only blocks
+
+To include a span of content for specific harnesses only, wrap it in an HTML-comment fence (it survives
+Markdown and is easy to grep):
+
+```
+<!-- harness-only: cursor,codex -->
+This sentence ships only in the Cursor and Codex bundles.
+<!-- /harness-only -->
+```
+
+The block body is kept iff the compiling harness's `id` appears in the comma list; otherwise it is removed
+entirely. Full per-harness content forking beyond placeholders and these blocks is intentionally out of
+scope (a maintenance trap) — see the Phase 42 CONTEXT.
+
+## Validation
+
+`test/suite/phase-42-placeholders.test.cjs` asserts that every placeholder actually used across
+`source/skills/` is documented in this file, and that `source/skills/` mirrors the `skills/` skill count.

package/scripts/lib/build/factory.cjs

@@ -0,0 +1,62 @@
+'use strict';
+// Phase 42 — pure transformer factory (impeccable-style). compile(text, config) => string.
+// Pure: no filesystem, no I/O, no module imports. The orchestrator (scripts/build-skills.cjs)
+// does all reading/writing; this layer only transforms a single skill body for one harness config.
+//
+// Transform order (deterministic):
+//   1. harness-only blocks   <!-- harness-only: a,b -->BODY<!-- /harness-only --> kept iff config.id in {a,b}
+//   2. protect escapes       \{{ x }}  -> sentinel  (emit literal {{ x }}, never substituted)
+//   3. substitute            {{command_prefix}} {{model}} {{config_file}} {{ask_instruction}}
+//   4. restore escapes       sentinel -> {{ x }}
+//
+// D-01: for the Claude config (command_prefix === '/gdd:') this is the exact inverse of the migration
+// (/gdd: -> {{command_prefix}}), so compile(source, claude) reproduces skills/ byte-for-byte.
+
+const PLACEHOLDERS = ['command_prefix', 'model', 'config_file', 'ask_instruction'];
+const ESCAPE_OPEN = '@@GDD_ESC_';
+const ESCAPE_CLOSE = '@@';
+
+function stripHarnessOnly(text, id) {
+  const re = /<!--\s*harness-only:\s*([^>]*?)\s*-->([\s\S]*?)<!--\s*\/harness-only\s*-->/g;
+  return text.replace(re, (_m, list, body) => {
+    const ids = String(list).split(',').map((s) => s.trim()).filter(Boolean);
+    return ids.includes(id) ? body : '';
+  });
+}
+
+function compile(text, config) {
+  if (typeof text !== 'string') throw new TypeError('compile: text must be a string');
+  if (!config || typeof config !== 'object') throw new TypeError('compile: config object is required');
+
+  let out = stripHarnessOnly(text, config.id);
+
+  // 2. protect \{{ ... }} escapes
+  const escapes = [];
+  out = out.replace(/\\\{\{([\s\S]*?)\}\}/g, (_m, inner) => {
+    escapes.push('{{' + inner + '}}');
+    return ESCAPE_OPEN + (escapes.length - 1) + ESCAPE_CLOSE;
+  });
+
+  // 3. substitute placeholders
+  for (const key of PLACEHOLDERS) {
+    if (config[key] == null) continue;
+    out = out.split('{{' + key + '}}').join(String(config[key]));
+  }
+
+  // 4. restore escapes as literal {{ ... }}
+  out = out.replace(/@@GDD_ESC_(\d+)@@/g, (_m, i) => escapes[Number(i)]);
+  return out;
+}
+
+/** Placeholders genuinely substituted (escaped \{{...}} excluded) — used by the catalogue test. */
+function placeholdersUsed(text) {
+  if (typeof text !== 'string') return new Set();
+  const scrubbed = String(text).replace(/\\\{\{[\s\S]*?\}\}/g, '');
+  const used = new Set();
+  const re = /\{\{([a-z_]+)\}\}/g;
+  let m;
+  while ((m = re.exec(scrubbed)) !== null) used.add(m[1]);
+  return used;
+}
+
+module.exports = { compile, placeholdersUsed, stripHarnessOnly, PLACEHOLDERS };

package/scripts/lib/build/harness-configs.cjs

@@ -0,0 +1,64 @@
+'use strict';
+// Phase 42 — per-harness build/compile config. The base record (id / name / configDir) comes from the
+// Phase 41.5 manifest SoT (scripts/lib/manifest/harnesses.json); this layer adds the four placeholder
+// substitutions + frontmatter-strip rules + the dist bundle slug. Adding a 15th harness = one manifest
+// entry (+ an optional OVERRIDES row); everything else falls back to DEFAULTS.
+//
+// command_prefix is the ONLY field that affects the byte-identical Claude round-trip: it MUST be '/gdd:'
+// for claude (the migration replaced literal '/gdd:' with {{command_prefix}}; the Claude compile reverses it).
+
+const { readHarnesses } = require('../manifest/index.cjs');
+
+const DEFAULTS = {
+  command_prefix: '/gdd:',
+  config_file: 'config.json',
+  model: 'your configured model',
+  ask_instruction: 'ask your agent',
+  stripFrontmatter: [],
+};
+
+// Per-harness overrides. Only `codex` diverges on command_prefix (its custom-prompt grammar is flat,
+// `/gdd-audit`, not the namespaced `/gdd:audit`); the rest share Claude's slash-command namespace.
+const OVERRIDES = {
+  claude:      { bundleSlug: 'claude-code', command_prefix: '/gdd:', config_file: '.claude/settings.json',     model: 'your configured Claude model',      ask_instruction: 'ask Claude Code' },
+  codex:       { command_prefix: '/gdd-',  config_file: '.codex/config.toml',        model: 'your configured Codex model',       ask_instruction: 'ask Codex' },
+  gemini:      { command_prefix: '/gdd:',  config_file: '.gemini/settings.json',     model: 'your configured Gemini model',      ask_instruction: 'ask Gemini' },
+  qwen:        { command_prefix: '/gdd:',  config_file: '.qwen/settings.json',       model: 'your configured Qwen model',        ask_instruction: 'ask Qwen Code' },
+  kilo:        { command_prefix: '/gdd:',  config_file: '.kilo/config.json',         model: 'your configured Kilo model',        ask_instruction: 'ask Kilo Code' },
+  copilot:     { command_prefix: '/gdd:',  config_file: '.copilot/config.json',      model: 'your configured Copilot model',     ask_instruction: 'ask Copilot' },
+  cursor:      { command_prefix: '/gdd:',  config_file: '.cursor/settings.json',     model: 'your configured Cursor model',      ask_instruction: 'ask Cursor' },
+  windsurf:    { command_prefix: '/gdd:',  config_file: '.windsurf/settings.json',   model: 'your configured Windsurf model',    ask_instruction: 'ask Cascade' },
+  antigravity: { command_prefix: '/gdd:',  config_file: '.antigravity/config.json',  model: 'your configured Antigravity model', ask_instruction: 'ask Antigravity' },
+  augment:     { command_prefix: '/gdd:',  config_file: '.augment/config.json',      model: 'your configured Augment model',     ask_instruction: 'ask Augment' },
+  trae:        { command_prefix: '/gdd:',  config_file: '.trae/config.json',         model: 'your configured Trae model',        ask_instruction: 'ask Trae' },
+  codebuddy:   { command_prefix: '/gdd:',  config_file: '.codebuddy/config.json',    model: 'your configured CodeBuddy model',   ask_instruction: 'ask CodeBuddy' },
+  cline:       { command_prefix: '/gdd:',  config_file: '.cline/config.json',        model: 'your configured Cline model',       ask_instruction: 'ask Cline' },
+  opencode:    { command_prefix: '/gdd:',  config_file: '.opencode/config.json',     model: 'your configured OpenCode model',    ask_instruction: 'ask OpenCode' },
+};
+
+function buildConfigs(opts) {
+  const { harnesses } = readHarnesses(opts);
+  return harnesses.map((h) => {
+    const ov = OVERRIDES[h.id] || {};
+    return {
+      id: h.id,
+      name: h.name,
+      configDir: h.config_dir,
+      bundleSlug: ov.bundleSlug || h.id,
+      ...DEFAULTS,
+      ...ov,
+    };
+  });
+}
+
+const CONFIGS = buildConfigs();
+
+function byId(id) {
+  return CONFIGS.find((c) => c.id === id) || null;
+}
+
+function claude() {
+  return byId('claude');
+}
+
+module.exports = { CONFIGS, byId, claude, buildConfigs, DEFAULTS };

package/scripts/lib/manifest/README.md

@@ -0,0 +1,46 @@
+# `scripts/lib/manifest/` — Cross-Phase Source-of-Truth Root
+
+Phase 41.5. This directory is the **single source-of-truth root** for roadmap-wide cross-phase
+metadata. Before it existed, Phase 42 / 44 / 45 / 47 each scoped its own "single source" in a different
+corner (`scripts/lib/build/`, `scripts/lib/prose/`, `reference/harness-matrix.json`,
+`scripts/skill-metadata.json`) — four formats, four schemas, four CI drift gates. This is the one root,
+one schema directory, one validator.
+
+## Files
+
+| File | Owner / writer | Read by |
+|---|---|---|
+| `harnesses.json` (+ `harnesses.cjs` view) | Phase 41.5 seed → **42** (build config) + **45** (capability matrix) extend it | the build pipeline, the harness matrix, the multi-harness compiler |
+| `skills.json` | Phase 41.5 seed (live `skills/` names) → **47** enriches (aliases, pin, description budget) | skill-UX tooling |
+| `prose-denylist.json` | Phase 41.5 seed → **43** + **44** | `scripts/lint-prose.cjs` (the editorial gate) |
+| `schemas/*.schema.json` | one JSON Schema per manifest file | `scripts/validate-manifest.cjs` |
+| `loader.cjs` | Phase 41.5 | every consumer |
+| `index.cjs` | Phase 41.5 | every consumer (`readHarnesses` / `readSkills` / `readProseDenylist`) |
+
+## Contract
+
+- **One canonical record, multiple views.** `harnesses.json` is the canonical harness record; Phase 42's
+  build config and Phase 45's capability matrix are *views* of it, not separate files. Consumers extend
+  the records with new fields (every schema sets `additionalProperties: true`) — they do not fork the file.
+- **Read through `index.cjs`.** Never `require` a manifest JSON directly. `readHarnesses()` /
+  `readSkills()` / `readProseDenylist()` return a well-shaped object even when the file is absent.
+- **Graceful out-of-order shipping.** `loader.cjs` returns an empty manifest + a one-line warning when a
+  file is missing or unparseable — a phase that ships before its data exists never crashes. (D-03)
+- **mtime cache.** A manifest is re-read only when its file mtime changes. (D-02)
+- **One CI gate.** `scripts/validate-manifest.cjs` (`npm run validate:manifest`) ajv-validates every
+  manifest against its schema. This is the only drift gate — 43/44/45/47 do NOT add their own.
+
+## Migration note (for Phase 42 / 43 / 44 / 45 / 47 plan-phases)
+
+When you plan your phase, **target this root from day one**. Do not create
+`scripts/lib/build/harness-configs.cjs`, `scripts/lib/prose/denylist.json`,
+`reference/harness-matrix.json`, or `scripts/skill-metadata.json` as new SoTs — extend
+`manifest/harnesses.json` / `manifest/prose-denylist.json` / `manifest/skills.json` instead, read them
+via `index.cjs`, and let `validate-manifest.cjs` be your drift gate. (Phase 46's SoT-consolidation
+paragraph delegates here.)
+
+## Boundaries
+
+This root holds **structured cross-phase data** (JSON + typed readers). It does not unify with the
+`reference/*.md` prose registries (a different consumer pattern), and it does not auto-generate
+frontmatter (Phase 46 territory).

package/scripts/lib/manifest/harnesses.cjs

@@ -0,0 +1,3 @@
+'use strict';
+// Phase 41.5 — typed re-export of harnesses.json (the .cjs view per D-01).
+module.exports = require('./harnesses.json').harnesses;

package/scripts/lib/manifest/harnesses.json

@@ -0,0 +1,91 @@
+{
+  "schema_version": 1,
+  "generated_at": null,
+  "note": "Canonical cross-phase harness record (Phase 41.5 SoT root). Phase 42 adds build/compile config; Phase 45 adds the capability matrix — both as views of this one record. Model tiers live in reference/runtime-models.md.",
+  "harnesses": [
+    {
+      "id": "claude",
+      "name": "Claude Code",
+      "config_dir": ".claude",
+      "runtime_models_ref": "reference/runtime-models.md#claude"
+    },
+    {
+      "id": "codex",
+      "name": "OpenAI Codex CLI",
+      "config_dir": ".codex",
+      "runtime_models_ref": "reference/runtime-models.md#codex"
+    },
+    {
+      "id": "gemini",
+      "name": "Gemini CLI",
+      "config_dir": ".gemini",
+      "runtime_models_ref": "reference/runtime-models.md#gemini"
+    },
+    {
+      "id": "qwen",
+      "name": "Qwen Code",
+      "config_dir": ".qwen",
+      "runtime_models_ref": "reference/runtime-models.md#qwen"
+    },
+    {
+      "id": "kilo",
+      "name": "Kilo Code",
+      "config_dir": ".kilo",
+      "runtime_models_ref": "reference/runtime-models.md#kilo"
+    },
+    {
+      "id": "copilot",
+      "name": "GitHub Copilot CLI",
+      "config_dir": ".copilot",
+      "runtime_models_ref": "reference/runtime-models.md#copilot"
+    },
+    {
+      "id": "cursor",
+      "name": "Cursor",
+      "config_dir": ".cursor",
+      "runtime_models_ref": "reference/runtime-models.md#cursor"
+    },
+    {
+      "id": "windsurf",
+      "name": "Windsurf (Cascade)",
+      "config_dir": ".windsurf",
+      "runtime_models_ref": "reference/runtime-models.md#windsurf"
+    },
+    {
+      "id": "antigravity",
+      "name": "Antigravity",
+      "config_dir": ".antigravity",
+      "runtime_models_ref": "reference/runtime-models.md#antigravity"
+    },
+    {
+      "id": "augment",
+      "name": "Augment",
+      "config_dir": ".augment",
+      "runtime_models_ref": "reference/runtime-models.md#augment"
+    },
+    {
+      "id": "trae",
+      "name": "Trae",
+      "config_dir": ".trae",
+      "runtime_models_ref": "reference/runtime-models.md#trae"
+    },
+    {
+      "id": "codebuddy",
+      "name": "CodeBuddy",
+      "config_dir": ".codebuddy",
+      "runtime_models_ref": "reference/runtime-models.md#codebuddy"
+    },
+    {
+      "id": "cline",
+      "name": "Cline",
+      "config_dir": ".cline",
+      "runtime_models_ref": "reference/runtime-models.md#cline"
+    },
+    {
+      "id": "opencode",
+      "name": "OpenCode",
+      "config_dir": ".opencode",
+      "runtime_models_ref": "reference/runtime-models.md#opencode"
+    }
+  ]
+}

package/scripts/lib/manifest/index.cjs

@@ -0,0 +1,26 @@
+'use strict';
+// Phase 41.5 — manifest/index.cjs — typed readers over the shared loader. Every cross-phase consumer
+// imports from here: `const { readHarnesses } = require('scripts/lib/manifest')`. Each reader returns
+// a well-shaped object even when the underlying file is absent (graceful empty fallback per loader D-03).
+
+const loader = require('./loader.cjs');
+
+/** @returns {{ schema_version: number, generated_at: string|null, harnesses: object[] }} */
+function readHarnesses(opts) {
+  return loader.load('harnesses', { ...opts, fallback: { schema_version: 1, generated_at: null, harnesses: [] } });
+}
+
+/** @returns {{ schema_version: number, skills: object[] }} */
+function readSkills(opts) {
+  return loader.load('skills', { ...opts, fallback: { schema_version: 1, skills: [] } });
+}
+
+/** @returns {{ schema_version: number, tells: object[] }} */
+function readProseDenylist(opts) {
+  return loader.load('prose-denylist', { ...opts, fallback: { schema_version: 1, tells: [] } });
+}
+
+module.exports = {
+  readHarnesses, readSkills, readProseDenylist,
+  reset: loader.reset, MANIFEST_DIR: loader.MANIFEST_DIR,
+};

package/scripts/lib/manifest/loader.cjs

@@ -0,0 +1,51 @@
+'use strict';
+// Phase 41.5 — manifest/loader.cjs — the ONE shared reader for every cross-phase SoT manifest under
+// scripts/lib/manifest/. Phases 42 (harnesses), 43/44 (prose denylist), 45 (capability matrix), and
+// 47 (skill metadata) all read through here instead of hand-rolling their own loader + drift gate.
+//
+// Graceful (D-03): a missing or unparseable manifest returns the caller's `fallback` (an empty
+// manifest) plus a one-line stderr warning — NEVER a throw — so a phase shipping before its data file
+// exists does not crash. File-mtime cache (D-02): a file is re-read only when its mtime changes.
+//
+// Dep-free (no ajv here — validation lives in scripts/validate-manifest.cjs, the CI gate). No require
+// of any third-party module.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MANIFEST_DIR = __dirname;
+const _cache = new Map(); // absPath -> { mtimeMs, data }
+
+/** Clear the in-process cache (tests). */
+function reset() { _cache.clear(); }
+
+/**
+ * Load a manifest JSON by base name (no extension).
+ * @param {string} name e.g. 'harnesses' | 'skills' | 'prose-denylist'
+ * @param {{ dir?: string, fallback?: any, quiet?: boolean }} [opts]
+ * @returns the parsed manifest, or `fallback` (default {}) on missing/parse-error.
+ */
+function load(name, opts) {
+  const o = opts || {};
+  const dir = o.dir || MANIFEST_DIR;
+  const fallback = Object.prototype.hasOwnProperty.call(o, 'fallback') ? o.fallback : {};
+  const abs = path.join(dir, `${name}.json`);
+
+  let stat;
+  try { stat = fs.statSync(abs); } catch {
+    if (!o.quiet) process.stderr.write(`manifest: ${name}.json not found — using empty fallback (a consumer phase may not have shipped its data yet)\n`);
+    return fallback;
+  }
+  const cached = _cache.get(abs);
+  if (cached && cached.mtimeMs === stat.mtimeMs) return cached.data;
+  try {
+    const data = JSON.parse(fs.readFileSync(abs, 'utf8'));
+    _cache.set(abs, { mtimeMs: stat.mtimeMs, data });
+    return data;
+  } catch (e) {
+    if (!o.quiet) process.stderr.write(`manifest: ${name}.json parse error (${e.message}) — using empty fallback\n`);
+    return fallback;
+  }
+}
+
+module.exports = { load, reset, MANIFEST_DIR };