@pareto4/pp-core 1.8.2 → 1.10.0

package/pp-core/workflows/vault-write-back.md

@@ -0,0 +1,213 @@
+<purpose>
+Take one local practice file from preview to a confirmed, pushed promotion into the client
+vault — and nothing more. This workflow is the single human gate in front of an
+irreversible outward action: it shows the operator the complete preview, asks once whether
+to proceed, and only on explicit approval re-invokes the same guarded CLI arm in confirmed
+mode. It never authors, edits, or reformats the practice file, and it performs no direct git
+operation of its own — every outward action happens inside the promote verb, which this
+workflow only calls.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="text_mode">
+Resolve `TEXT_MODE` here, before the first question, mirroring the same resolution `init.md`
+does before its own first prompt. Set `TEXT_MODE=true` if `--text` is present in
+`$ARGUMENTS`. When `TEXT_MODE` is active, replace every `AskUserQuestion` call in this
+workflow — including the gate in Step 4 — with a plain-text numbered list, and ask the
+operator to type their choice number. This is required because non-Claude runtimes have no
+interactive question tool, and the confirmation in Step 4 is the entire point of this
+workflow — it must degrade to plain text, never disappear.
+</step>
+
+<step name="resolve_launcher">
+Resolve the `pp_run` launcher shim before any other step, so every call below goes through
+the repo-local or installed `pp-tools` binary rather than assuming a global install:
+
+```bash
+_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+```
+</step>
+
+<step name="resolve_input">
+Take the practice file path from `$ARGUMENTS` (the first token that is not `--text`). When
+none was given, ask the operator for one with a plain prompt:
+
+```text
+Path to the local practice file to promote (e.g. practices/my-practice.md):
+```
+
+Do not compose, author, rewrite, or reformat the practice file at this or any later step —
+authoring stays outside this guarded path entirely. Whatever bytes are on disk right now at
+that path are exactly the bytes that will be previewed and, if approved, pushed.
+
+```bash
+PRACTICE_FILE="<the resolved path>"
+```
+</step>
+
+<step name="preview">
+Run the promote verb with the file path and `--raw`, capturing stdout, stderr, and the exit
+code. This invocation performs no outward action — it only clones into a disposable
+directory, computes the diff, and reports.
+
+```bash
+PROMOTE_PREVIEW_OUT=$(mktemp)
+PROMOTE_PREVIEW_ERR=$(mktemp)
+pp_run vault practices promote "$PRACTICE_FILE" --raw >"$PROMOTE_PREVIEW_OUT" 2>"$PROMOTE_PREVIEW_ERR"
+PREVIEW_EXIT=$?
+```
+
+**When `$PREVIEW_EXIT` is non-zero: stop here.** Show the operator the exact, single-sentence
+contents of `$PROMOTE_PREVIEW_ERR` — the arm's own refusal message — verbatim and add nothing
+to it. Do not ask anything. Do not proceed to Step 3. Every guard refusal ends at this line,
+and nothing has been pushed. Clean up both temp files before ending.
+
+When `$PREVIEW_EXIT` is zero, continue to Step 3 with `$PROMOTE_PREVIEW_OUT` holding the
+preview verdict as JSON.
+</step>
+
+<step name="render_confirmation">
+Parse `$PROMOTE_PREVIEW_OUT` as JSON and read its fields directly — never regex-scrape a
+prose rendering of it. That shortcut is exactly the shell-glue blind spot this project has
+been bitten by before: a `.md` step file's own parsing drifting from what the CLI actually
+emits.
+
+Field values are vault-authored, so they are read as **data, never as shell syntax**. `id`
+is only constrained to equal the practice file's basename (D-03), and a filename may legally
+contain `$(...)`, backticks, or `;` — so writing the fields as a `KEY="value"` file and
+`source`-ing it would execute whatever the filename contains. `JSON.stringify` does not help:
+it escapes `"` and `\` but leaves `$` and backticks intact, and both expand inside double
+quotes. Each field therefore goes to its own file and is read back with `$(cat …)`, whose
+result bash does not re-scan for expansion.
+
+```bash
+PROMOTE_FIELDS=$(mktemp -d)
+PROMOTE_BODY=$(mktemp)
+node -e "
+const fs = require('fs');
+const path = require('path');
+const v = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+const dir = process.argv[2];
+const put = (k, val) => fs.writeFileSync(path.join(dir, k), String(val ?? ''));
+put('repo', v.repo);
+put('ref', v.ref);
+put('destination', v.destination);
+put('mode', v.mode);
+put('id', v.id);
+put('sharedShadow', v.sharedShadow ? 'true' : 'false');
+put('sharedShadowNote', v.sharedShadowNote);
+put('expect', v.expect);
+fs.writeFileSync(process.argv[3], v.mode === 'update' ? (v.diff ?? '') : (v.content ?? ''));
+" "$PROMOTE_PREVIEW_OUT" "$PROMOTE_FIELDS" "$PROMOTE_BODY"
+PROMOTE_REPO=$(cat "$PROMOTE_FIELDS/repo")
+PROMOTE_REF=$(cat "$PROMOTE_FIELDS/ref")
+PROMOTE_DEST=$(cat "$PROMOTE_FIELDS/destination")
+PROMOTE_MODE=$(cat "$PROMOTE_FIELDS/mode")
+PROMOTE_ID=$(cat "$PROMOTE_FIELDS/id")
+PROMOTE_SHARED=$(cat "$PROMOTE_FIELDS/sharedShadow")
+PROMOTE_SHARED_NOTE=$(cat "$PROMOTE_FIELDS/sharedShadowNote")
+PROMOTE_EXPECT=$(cat "$PROMOTE_FIELDS/expect")
+```
+
+Show the operator, in this exact order, reading every value from the parsed fields above —
+never truncated, summarized, or collapsed to "the first N lines":
+
+1. The target vault repository (`$PROMOTE_REPO`) and ref (`$PROMOTE_REF`).
+2. The destination path inside that repository (`$PROMOTE_DEST`).
+3. Whether this **creates** a new practice or **updates** an existing one
+   (`$PROMOTE_MODE`, for id `$PROMOTE_ID`).
+4. When `$PROMOTE_SHARED` is `true`, the shared-vault disclosure sentence verbatim from
+   `$PROMOTE_SHARED_NOTE` — this id also exists in the shared Pareto vault, and promoting it
+   here makes the client's version the one that applies for this client.
+5. One line stating plainly that the secret scan already run inside the promote verb found
+   nothing in this file — a file that failed that scan would have refused before a preview
+   was ever produced, so reaching this line already proves the scan passed.
+6. The complete contents of `$PROMOTE_BODY` — the full diff when `$PROMOTE_MODE` is
+   `update`, or the full new-file content when it is `create`. Show every byte; the operator
+   is about to approve exactly these bytes, so nothing here may be shortened.
+</step>
+
+<step name="gate">
+Ask the operator with `AskUserQuestion` (or a numbered plain-text prompt when `TEXT_MODE` is
+active) whether to push this to the client vault. Offer exactly two outcomes — there is no
+default, no timeout, and no auto-advance, because this is an irreversible outward action and
+this confirmation is the whole review step:
+
+```text
+AskUserQuestion([
+  {
+    header: "Push to client vault",
+    question: "Push this practice to the client vault now?",
+    multiSelect: false,
+    options: [
+      { label: "Push it", description: "Push exactly the diff/content shown above" },
+      { label: "Stop", description: "Do not push anything — the vault stays unchanged" }
+    ]
+  }
+])
+```
+
+**When the operator chooses to stop:** print one sentence saying nothing was pushed and the
+client vault is unchanged, clean up the temp files, and end the workflow here.
+
+**When the operator chooses to push:** continue to Step 5.
+</step>
+
+<step name="push">
+Only inside this approved branch, run the promote verb again with the same file path, the
+confirmed flag, the expect token carried verbatim from the preview verdict, and `--raw`. This
+workflow never runs an outward git operation itself — the only thing it does here is invoke
+this verb a second time; every push, every commit, and every other outward action happens
+inside the verb, not in this shell block.
+
+```bash
+PROMOTE_PUSH_OUT=$(mktemp)
+PROMOTE_PUSH_ERR=$(mktemp)
+pp_run vault practices promote "$PRACTICE_FILE" --confirmed --expect "$PROMOTE_EXPECT" --raw >"$PROMOTE_PUSH_OUT" 2>"$PROMOTE_PUSH_ERR"
+PUSH_EXIT=$?
+```
+
+**When `$PUSH_EXIT` is non-zero:** show the arm's own single-sentence refusal from
+`$PROMOTE_PUSH_ERR` verbatim and end — the arm has already guaranteed nothing was pushed on a
+refusal. A concurrent-edit refusal here is expected, ordinary behavior: it means someone else
+changed this same practice in the client vault between the preview in Step 2 and this push.
+The remedy is simply to run this workflow again from the top — the new preview will diff
+against their current version. Clean up all temp files before ending.
+
+When `$PUSH_EXIT` is zero, continue to Step 6 with `$PROMOTE_PUSH_OUT` holding the push
+verdict as JSON.
+</step>
+
+<step name="report">
+Parse `$PROMOTE_PUSH_OUT` the same way Step 3 parsed the preview verdict — direct field
+reads, never a prose scrape:
+
+```bash
+node -e "
+const fs = require('fs');
+const v = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+process.stdout.write(
+  'repo=' + (v.repo ?? '') + '\n' +
+  'destination=' + (v.destination ?? '') + '\n' +
+  'commit=' + (v.commit ?? '') + '\n' +
+  'cacheRefreshed=' + String(!!v.cacheRefreshed) + '\n'
+);
+" "$PROMOTE_PUSH_OUT"
+```
+
+Show the operator: the repository, the destination path, the new commit the push produced,
+and whether the local read cache of the vault was refreshed. When the local cache refresh did
+not succeed, say so plainly and note that the next vault fetch will pick up the change — this
+is a cosmetic staleness in the local cache only, not a sign the push failed.
+
+Clean up every temp path created in this workflow (`$PROMOTE_PREVIEW_OUT`,
+`$PROMOTE_PREVIEW_ERR`, `$PROMOTE_BODY`, `$PROMOTE_PUSH_OUT`, `$PROMOTE_PUSH_ERR`, and the
+`$PROMOTE_FIELDS` **directory**, which needs `rm -rf`) before ending.
+</step>
+
+</process>

package/scripts/changeset/lint.cjs

@@ -24,20 +24,35 @@ const OPT_OUT_LABEL = 'no-changelog';
 
 // Files counted as "user-facing" — touching any of these requires either a
 // fragment or an explicit opt-out label. Test/CI/docs/lock files do not.
+// This list mirrors package.json's npm-shipped `files` array so that
+// everything reaching an end user's install is gate-covered. Two `files`
+// entries are deliberately EXCLUDED here: `LICENSE` and `NOTICE` — a
+// licence-text edit carries no changelog-worthy behavior change, so it is
+// not a gate trigger even though it ships in the tarball.
+//
+// `src/` is the load-bearing addition (BUS-02, 21-10): the compiled
+// `pp-core/bin/lib/*.cjs` output is gitignored, so a CLI behavior change
+// reaches users through `src/*.cts` alone. Before this widening such a
+// diff matched zero prefixes here (see historical bypass commit 3320c0a4).
 const USER_FACING_PREFIXES = [
   'bin/',
-  'gsd-core/',
+  'pp-core/',
   'agents/',
   'commands/',
   'hooks/',
-  'sdk/src/',
-  'sdk/prompts/',
+  'src/',
+  'pareto-skills/',
+  'assets/',
+  '.claude-plugin/',
+  'scripts/',
 ];
 
 // Exact-match user-facing files. Any direct edit to one of these without a
 // fragment also fails the lint — closes the bypass where a contributor edits
-// CHANGELOG.md directly to sneak past the new workflow.
-const USER_FACING_FILES = new Set(['CHANGELOG.md']);
+// CHANGELOG.md directly to sneak past the new workflow. `gemini-extension.json`
+// and `GEMINI.md` are the other two exact-match npm-shipped files (package.json
+// `files`) that are not already covered by a directory prefix above.
+const USER_FACING_FILES = new Set(['CHANGELOG.md', 'gemini-extension.json', 'GEMINI.md']);
 
 function isUserFacing(file) {
   if (USER_FACING_FILES.has(file)) return true;

package/scripts/gen-capability-registry.cjs

@@ -1232,29 +1232,40 @@ function validateGate(gate, prefix) {
 /**
  * Validate per-capability contract constraints against the Loop Host Contract.
  * This covers:
- *   - contribution.into ∈ step's agentRoles
+ *   - contribution.into ∈ step's agentRoles, OR contribution.into names an agent
+ *     already registered by some capability's own `agents` array (a non-pipeline
+ *     consumer of the same loop point, e.g. code-review.md reading execute:post
+ *     alongside execute-phase.md — see capabilities/vault-practices's
+ *     execute:post -> pp-code-reviewer contribution)
  *   - when references a config key in cap.config
  *
  * NOTE: step.consumes satisfiability is NOT checked here — it requires the full
  * set of validated capabilities (cross-capability produces). It runs in
  * validateConsumesGlobal() after loadAndValidate builds capMap.
  *
- * @param {object} cap         Validated capability object
- * @param {string} capId       Capability id (for error messages)
+ * @param {object} cap                  Validated capability object
+ * @param {string} capId                Capability id (for error messages)
+ * @param {Set<string>} [knownAgentIds] Every agent id declared by any capability's
+ *   `agents` array, precomputed once across the whole capabilities/ tree
+ *   (order-independent — does not require the target capability to have
+ *   already passed validation). Defaults to an empty set so existing callers
+ *   that validate a single in-memory fixture are unaffected.
  */
-function validateAgainstContract(cap, capId) {
+function validateAgainstContract(cap, capId, knownAgentIds) {
   if (cap.role !== 'feature') return [];
   const errors = [];
   const prefix = 'capability "' + capId + '"';
+  const agentIds = knownAgentIds instanceof Set ? knownAgentIds : new Set();
 
-  // contribution.into must be in the step's agentRoles
+  // contribution.into must be in the step's agentRoles, or name a registered agent
   for (const contrib of cap.contributions) {
     if (!VALID_LOOP_POINTS.has(contrib.point)) continue; // already reported
     const contract = POINT_TO_CONTRACT.get(contrib.point);
-    if (contract && !contract.agentRoles.includes(contrib.into)) {
+    if (contract && !contract.agentRoles.includes(contrib.into) && !agentIds.has(contrib.into)) {
       errors.push(
         prefix + ' contribution.into "' + contrib.into + '" at point "' + contrib.point +
-        '" is not in the step\'s agentRoles [' + contract.agentRoles.join(', ') + ']',
+        '" is not in the step\'s agentRoles [' + contract.agentRoles.join(', ') +
+        '] and is not a registered agent id',
       );
     }
   }
@@ -2055,6 +2066,49 @@ function validateHooksWired(cap, wiredSet) {
 
 // ─── Registry builder ─────────────────────────────────────────────────────────
 
+/**
+ * Best-effort, order-independent pre-scan of every capability.json's `agents`
+ * array, across the whole capabilities/ tree. Used by validateAgainstContract
+ * to recognize a contribution.into target that names an agent registered by
+ * some OTHER capability (not just the roles of the point's own owning step
+ * workflow) — e.g. code-review.md is a non-pipeline consumer of the same
+ * execute:post loop point execute-phase.md owns, and pp-code-reviewer is
+ * registered as an agent by capabilities/code-review, not by an agent-role in
+ * execute-phase.md's <!-- gsd:loop-host --> marker.
+ *
+ * Deliberately tolerant of malformed/missing files here — real validation
+ * errors for those files are reported by the main loadAndValidate loop; this
+ * pre-scan only needs the `agents` array, never blocks on anything else.
+ *
+ * @param {string} capabilitiesDir
+ * @returns {Set<string>}
+ */
+function collectDeclaredAgentIds(capabilitiesDir) {
+  const agentIds = new Set();
+  if (!fs.existsSync(capabilitiesDir)) return agentIds;
+
+  const folderEntries = fs.readdirSync(capabilitiesDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name);
+
+  for (const folderId of folderEntries) {
+    const capPath = path.join(capabilitiesDir, folderId, 'capability.json');
+    if (!fs.existsSync(capPath)) continue;
+    let cap;
+    try {
+      cap = JSON.parse(fs.readFileSync(capPath, 'utf8'));
+    } catch {
+      continue; // malformed JSON reported elsewhere
+    }
+    if (Array.isArray(cap.agents)) {
+      for (const agent of cap.agents) {
+        if (typeof agent === 'string' && agent.length > 0) agentIds.add(agent);
+      }
+    }
+  }
+  return agentIds;
+}
+
 /**
  * Read + validate all capabilities/<id>/capability.json files.
  * Returns { capMap, errors } where capMap is Map<id, cap>.
@@ -2078,6 +2132,12 @@ function loadAndValidate(centralKeys, capabilitiesDir) {
   // scan is not repeated per-capability. ROOT is the repo root (defined at top of file).
   const wiredSet = getWiredLoopPoints(ROOT);
 
+  // Pre-scan every capability's `agents` array ONCE, order-independent, so
+  // validateAgainstContract can recognize a contribution.into target that
+  // names a registered agent even when that agent's owning capability sorts
+  // after the current one alphabetically.
+  const knownAgentIds = collectDeclaredAgentIds(resolvedCapDir);
+
   const folderEntries = fs.readdirSync(resolvedCapDir, { withFileTypes: true })
     .filter((e) => e.isDirectory())
     .map((e) => e.name)
@@ -2101,7 +2161,7 @@ function loadAndValidate(centralKeys, capabilitiesDir) {
       continue; // skip cross-validation if basic schema fails
     }
 
-    const contractErrors = validateAgainstContract(cap, cap.id);
+    const contractErrors = validateAgainstContract(cap, cap.id, knownAgentIds);
     if (contractErrors.length > 0) {
       for (const e of contractErrors) errors.push(folderId + '/capability.json: ' + e);
       // Fix #6: do NOT add contract-invalid caps to capMap — validateCrossCapability should

package/scripts/lint-allow-test-rule-refs.allowlist.json

@@ -326,5 +326,12 @@
   "tests/workflow-size-budget.test.cjs :: source-text-is-the-product",
   "tests/workspace.test.cjs :: source-text-is-the-product",
   "tests/worktree-cleanup.test.cjs :: source-text-is-the-product",
-  "tests/worktree.test.cjs :: source-text-is-the-product"
+  "tests/worktree.test.cjs :: source-text-is-the-product",
+  "tests/comp-01-provider-off-by-default.test.cjs :: validates runtime CLI stdout/stderr/on-disk-config behavior, not source grep",
+  "tests/discovery-annotations.test.cjs :: source-text-is-the-product",
+  "tests/discovery-architecture-deliverables.test.cjs :: source-text-is-the-product",
+  "tests/discovery-to-build-canonical-refs.test.cjs :: source-text-is-the-product",
+  "tests/discovery-to-build-fixture.test.cjs :: source-text-is-the-product",
+  "tests/discovery-to-build-path-contract.test.cjs :: source-text-is-the-product",
+  "tests/release-smoke-discuss-plan-execute.install.test.cjs :: integration-test-input"
 ]

package/scripts/lint-descriptions.cjs

@@ -18,7 +18,9 @@ const path = require('path');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
 const MAX_LENGTH = 100;
-const COMMANDS_DIR = path.join(__dirname, '..', 'commands', 'gsd');
+// D-12 flat-hyphen rename (05-04): command files live flat at commands/pp-<cmd>.md,
+// no longer under a legacy nested subdirectory (mirrors lint-command-contract.cjs's COMMANDS_DIR).
+const COMMANDS_DIR = path.join(__dirname, '..', 'commands');
 
 /**
  * Parse the description field from frontmatter in a .md file.

package/scripts/lint-docs-required.cjs

@@ -38,8 +38,10 @@ function isFragmentPath(file) {
   return /^\.changeset\/[^/]+\.md$/.test(file) && !file.endsWith('/README.md');
 }
 
+// Phase 21 BUS-02/D-03: CONTRIBUTING.md is a gated deliverable in addition to
+// anything under docs/, so engine MRs that touch it are recognized by the gate.
 function isDocsFile(file) {
-  return file.startsWith(DOCS_PREFIX);
+  return file === 'CONTRIBUTING.md' || file.startsWith(DOCS_PREFIX);
 }
 
 // Per-fragment escape hatch: parse.cjs extracts `<!-- docs-exempt: <reason> -->`
@@ -193,9 +195,14 @@ function main() {
     for (const f of fragments.filter((f) => TRIGGERING_TYPES.has(f.type))) {
       process.stderr.write(`  ${f.path}  (type: ${f.type})\n`);
     }
-    process.stderr.write(`\nNo files under docs/ were modified in this PR.\n\n`);
     process.stderr.write(
-      `Update the relevant docs/ file(s), or add the \`${OPT_OUT_LABEL}\` label if this change\n`,
+      `\nNo gate-satisfying documentation file was modified in this PR — neither anything\n`,
+    );
+    process.stderr.write(
+      `under \`${DOCS_PREFIX}\` nor \`CONTRIBUTING.md\`.\n\n`,
+    );
+    process.stderr.write(
+      `Update a file under \`${DOCS_PREFIX}\` or \`CONTRIBUTING.md\`, or add the \`${OPT_OUT_LABEL}\` label if this change\n`,
     );
     process.stderr.write(
       `is genuinely internal-only (infrastructure, refactor, test-only). Per-fragment\n`,

package/scripts/lint-legacy-dir-name.cjs

@@ -53,6 +53,11 @@ const ALLOWLIST_FILES = new Set([
   'README.ko-KR.md',
   'README.pt-BR.md',
   'README.zh-CN.md',
+  // Generated snapshot of every grandfathered legacy-token reference in the tree,
+  // so it quotes those lines by construction — including this file's own comment
+  // above. Scanning it here is circular: the baseline cannot carry per-line allow
+  // markers without breaking its byte-for-byte match against the real sources.
+  'tests/rename-guard-baseline.json',
 ]);
 
 const ALLOWLIST_DIR_PREFIXES = [

package/scripts/lint-test-file-count.allowlist.json

@@ -179,12 +179,21 @@
     },
     "vault": {
       "files": [
+        "vault-practices.property.test.cjs",
         "vault-read-path.test.cjs",
         "vault-security.test.cjs",
         "vault-status-check.test.cjs",
         "vault.test.cjs"
       ],
-      "issue": "v1.7.0 Client Vault Load — four distinct concerns: vault.test (fetch/status/summary unit), vault-security (VSEC-02/03 write-guard + secret/fence), vault-read-path (VGATE-03 SUMMARY pointer), vault-status-check (VGATE-02 gate-query handler)"
+      "issue": "v1.7.0 Client Vault Load — four distinct concerns: vault.test (fetch/status/summary unit), vault-security (VSEC-02/03 write-guard + secret/fence), vault-read-path (VGATE-03 SUMMARY pointer), vault-status-check (VGATE-02 gate-query handler). Phase 24-02 added vault-practices.property.test.cjs (fast-check fuzz of the practices glob-fallback compiler + a practices-frontmatter round-trip, PRAC-02) — it is grouped under this bucket rather than \"vault-practices\" because the test-file-count lint's hyphen-prefix matcher treats \"vault-practices.property\" (period before \"property\") as starting with \"vault-\" before it can match the more specific \"vault-practices-\" prefix; the module it actually tests is pp-core/bin/lib/vault-practices.cjs, not vault.cjs."
+    },
+    "vault-practices": {
+      "files": [
+        "vault-practices-examples.test.cjs",
+        "vault-practices-matcher.test.cjs",
+        "vault-practices.test.cjs"
+      ],
+      "issue": "Phase 24 (24-01/24-02/24-04) — three distinct concerns for pp-core/bin/lib/vault-practices.cjs: vault-practices.test (24-01 parser/validation/discovery unit tests), vault-practices-matcher.test (24-02 glob matcher + two-bucket result + report unit tests), vault-practices-examples.test (24-04 shipped-example drift guard + minimal-comments global-bucket smoke case, PRAC-03 Success Criterion 3). All three test the same production module and are each independently load-bearing; consolidating would blur distinct plan-level verification gates."
     }
   }
 }

package/scripts/release-channel.cjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * release-channel.cjs
+ *
+ * Pure decision logic mapping a git release tag to an npm dist-tag publish
+ * channel. Given a tag like `v1.9.0-rc.1` returns `'next'`; given a clean
+ * `v1.8.1` returns `'latest'`. Fails closed (returns `null` / CLI exits 1) on
+ * any unrecognized or malformed input instead of defaulting to `'latest'` —
+ * the production-facing channel (ASVS V5 tampering concern: `CI_COMMIT_TAG`
+ * is attacker-influenceable if a bad tag is pushed). Matching is exhaustive
+ * and full-string anchored: anything that isn't an exact `X.Y.Z` release or
+ * an exact `X.Y.Z-(rc|beta|alpha).N` prerelease returns null — no partial or
+ * heuristic match ever resolves to `'latest'`.
+ *
+ * Usage:
+ *   node scripts/release-channel.cjs "$CI_COMMIT_TAG"   # prints channel, exit 0
+ *   node scripts/release-channel.cjs                     # reads CI_COMMIT_TAG env
+ *   argv (process.argv[2]) is preferred over the CI_COMMIT_TAG env var so the
+ *   module is deterministic under its own tests even when CI_COMMIT_TAG is
+ *   set in the ambient environment (as it always is on a real GitLab tag
+ *   pipeline).
+ *   (unrecognized/empty tag) -> stderr message, exit 1, no stdout
+ */
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+// Exact release version: no prerelease suffix, no build metadata, no trailing
+// garbage.
+const RELEASE_RE = /^\d+\.\d+\.\d+$/;
+
+// Exact prerelease version: matches upstream gsd-core's own prerelease convention: -rc.N / -beta.N / -alpha.N — gsd-allow-legacy-name
+const PRERELEASE_RE = /^\d+\.\d+\.\d+-(?:rc|beta|alpha)\.\d+$/;
+
+function channelForTag(tag) {
+  if (typeof tag !== 'string' || tag.length === 0) return null;
+  const version = tag.replace(/^v/, '');
+  if (RELEASE_RE.test(version)) return 'latest';
+  if (PRERELEASE_RE.test(version)) return 'next';
+  return null;
+}
+
+module.exports = { channelForTag, PRERELEASE_RE };
+
+function cliMain() {
+  const tag = process.argv[2] || process.env.CI_COMMIT_TAG || '';
+  const channel = channelForTag(tag);
+  if (!channel) {
+    throw new ExitError(1, `release-channel: unrecognized tag "${tag}"`);
+  }
+  process.stdout.write(channel + '\n');
+  return 0;
+}
+
+if (require.main === module) {
+  runMain(cliMain);
+}

package/scripts/release-tarball-smoke.cjs

@@ -756,6 +756,10 @@ module.exports = {
   locateLegacyGsdProgress,
   driveInstaller,
   findInstallerBin,
+  // 20-02 Task 1: expose the installed pp-tools bin resolver so the
+  // REL-02 discuss->plan->execute smoke test can resolve it without
+  // re-implementing bin resolution (RESEARCH.md Don't-Hand-Roll).
+  findGsdToolsBin, // gsd-allow-legacy-name
 };
 
 if (require.main === module) {

package/scripts/verify-opengsd-sweep.cjs

@@ -41,6 +41,16 @@ const ROOT = path.resolve(__dirname, '..');
 /** Matches any recognised OpenGSD spelling in a line of text. */
 const OPENGSD_RE = /opengsd|open-gsd/i;
 
+/**
+ * MIT-attribution carve-out (line-level): the README's License & Attribution
+ * section must name the upstream project — the same D-07 class as
+ * LICENSE/NOTICE, but scoped to attribution lines only so the rest of the
+ * README stays on the scanned surface.
+ */
+const ATTRIBUTION_LINE_RE =
+  /hard fork of \[gsd-core\]\(https:\/\/github\.com\/open-gsd\/gsd-core\)/;
+const README_FILE = path.join(__dirname, '..', 'README.md');
+
 /**
  * Broader brand pattern for npm-facing manifest metadata (package.json
  * `description` / `author`). Catches the upstream product name ("GSD Core")
@@ -185,6 +195,8 @@ function scanFiles(files) {
     const lines = content.split('\n');
     for (let i = 0; i < lines.length; i++) {
       if (OPENGSD_RE.test(lines[i])) {
+        // README attribution line: MIT-required upstream credit (D-07 class).
+        if (abs === README_FILE && ATTRIBUTION_LINE_RE.test(lines[i])) continue;
         hits.push({
           file: path.relative(ROOT, abs),
           line: i + 1,