@pareto4/pp-core 1.13.0 → 1.18.0

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

@@ -1,11 +1,10 @@
 <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.
+Take one local standards document from preview to a confirmed, pushed promotion into the client
+vault, together with its INDEX.md entry, 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 verb in confirmed
+mode. It never authors, edits or reformats the document, and it performs no git operation of its
+own; every outward action happens inside `pp_run vault standards promote`.
 </purpose>
 
 <required_reading>
@@ -15,79 +14,64 @@ Read all files referenced by the invoking prompt's execution_context before star
 <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
-```
+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 below, with a plain-text numbered
+list, and ask the operator to type their choice number. The confirmation is the point of this
+workflow: it must degrade to plain text, never disappear.
 </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:
+Take from `$ARGUMENTS`:
 
-```text
-Path to the local practice file to promote (e.g. practices/my-practice.md):
-```
+- the document path: the first token that is not a flag (required; ask for it with a plain prompt
+  when it is missing: `Path to the local standards document to promote (e.g. docs/standards/api-errors.md):`);
+- `--path <vault-path>`: where the document goes in the vault (optional; defaults to
+  `standards/<file name>`);
+- `--entry "<what it is>; used when <…>"`: the document's INDEX.md entry text (required when the
+  vault's INDEX.md does not list the document yet; replaces the existing line when given for a
+  listed document);
+- `--section <title>`: the INDEX.md `##` section a new entry goes under (optional).
+
+When the document is new to the vault and no `--entry` was given, ask the operator for one plain
+sentence of the form `<what the document is>; used when <when a plan should follow it>`. Never
+invent it.
 
-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.
+Do not compose, rewrite or reformat the document at this or any later step. Whatever bytes are on
+disk at that path are exactly the bytes that will be previewed and, if approved, pushed.
 
 ```bash
-PRACTICE_FILE="<the resolved path>"
+DOC_FILE="<the resolved path>"
+PROMOTE_ARGS=()   # add --path, --entry and --section with their values, as given
 ```
 </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.
+Run the promote verb without `--confirmed`, capturing stdout, stderr and the exit code. This
+invocation performs no outward action: it clones the client vault into a disposable directory,
+writes the change there, and reports the diff.
 
 ```bash
 _PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; 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}"; 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}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; 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}"; 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}"; 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}"; 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}"; 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}"; 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}"; 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}"; 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}"; 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}"; 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}"; 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}"; 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}"; 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}"; 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}"; 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}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v 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
 PROMOTE_PREVIEW_OUT=$(mktemp)
 PROMOTE_PREVIEW_ERR=$(mktemp)
-pp_run vault practices promote "$PRACTICE_FILE" --raw >"$PROMOTE_PREVIEW_OUT" 2>"$PROMOTE_PREVIEW_ERR"
+pp_run vault standards promote "$DOC_FILE" "${PROMOTE_ARGS[@]}" --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 non-zero: stop here.** Show the operator the single-sentence refusal in
+`$PROMOTE_PREVIEW_ERR` verbatim and add nothing to it. Do not ask anything. 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.
+When `$PREVIEW_EXIT` is zero, `$PROMOTE_PREVIEW_OUT` holds 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.
+Read the verdict's fields directly, never by scraping a prose rendering. Each field is written to
+its own file and read back with `$(cat …)`, whose result bash does not re-scan for expansion, so a
+destination path containing `$(...)` or backticks is shown, never executed.
 
 ```bash
 PROMOTE_FIELDS=$(mktemp -d)
-PROMOTE_BODY=$(mktemp)
 node -e "
 const fs = require('fs');
 const path = require('path');
@@ -98,94 +82,78 @@ 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('indexChange', v.indexChange);
 put('expect', v.expect);
-fs.writeFileSync(process.argv[3], v.mode === 'update' ? (v.diff ?? '') : (v.content ?? ''));
-" "$PROMOTE_PREVIEW_OUT" "$PROMOTE_FIELDS" "$PROMOTE_BODY"
+put('diff', v.diff);
+put('notes', (v.notes || []).join('\n'));
+" "$PROMOTE_PREVIEW_OUT" "$PROMOTE_FIELDS"
 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_INDEX=$(cat "$PROMOTE_FIELDS/indexChange")
 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":
+Show the operator, in this order, never truncated or summarised:
 
 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.
+2. The destination path in the vault (`$PROMOTE_DEST`), and whether this **creates** a new
+   standards document or **updates** an existing one (`$PROMOTE_MODE`).
+3. What happens to INDEX.md (`$PROMOTE_INDEX`): `added` (a new line), `replaced` (its line gets the
+   new entry text) or `unchanged`.
+4. One line stating that the secret scan inside the promote verb found nothing; a document that
+   failed it would have been refused before any preview existed.
+5. Any notes in `$PROMOTE_FIELDS/notes`.
+6. The complete contents of `$PROMOTE_FIELDS/diff`: the document and the INDEX.md change, every
+   byte. The operator is about to approve exactly these bytes.
 </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:
+Ask once whether to push. Exactly two outcomes, no default, no timeout, no auto-advance:
 
 ```text
 AskUserQuestion([
   {
     header: "Push to client vault",
-    question: "Push this practice to the client vault now?",
+    question: "Push this standards document to the client vault now?",
     multiSelect: false,
     options: [
-      { label: "Push it", description: "Push exactly the diff/content shown above" },
+      { label: "Push it", description: "Push exactly the diff 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 stop:** say in one sentence that nothing was pushed and the client
+vault is unchanged, clean up the temp paths, and end.
 
-**When the operator chooses to push:** continue to Step 5.
+**When the operator chooses to push:** continue.
 </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.
+Only inside this approved branch, run the verb again with the same arguments, `--confirmed`, and the
+expect token carried verbatim from the preview.
 
 ```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"
+pp_run vault standards promote "$DOC_FILE" "${PROMOTE_ARGS[@]}" --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.
+**When `$PUSH_EXIT` is non-zero:** show the verb's single-sentence refusal from `$PROMOTE_PUSH_ERR`
+verbatim and end; a refusal guarantees nothing was pushed. A concurrent-edit refusal is ordinary:
+someone changed the document or INDEX.md in the vault since the preview. The remedy is to run this
+workflow again from the top. Clean up all temp paths before ending.
 </step>
 
 <step name="report">
-Parse `$PROMOTE_PUSH_OUT` the same way Step 3 parsed the preview verdict — direct field
-reads, never a prose scrape:
+Read the push verdict's fields the same way, then show the operator the repository, the destination,
+the new commit, what happened to INDEX.md, and whether the local vault cache was refreshed. When the
+refresh did not succeed, say so plainly: the next vault fetch picks the change up; the push itself
+succeeded.
 
 ```bash
 node -e "
@@ -195,19 +163,14 @@ process.stdout.write(
   'repo=' + (v.repo ?? '') + '\n' +
   'destination=' + (v.destination ?? '') + '\n' +
   'commit=' + (v.commit ?? '') + '\n' +
+  'indexChange=' + (v.indexChange ?? '') + '\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.
+Clean up every temp path created in this workflow (`$PROMOTE_PREVIEW_OUT`, `$PROMOTE_PREVIEW_ERR`,
+`$PROMOTE_PUSH_OUT`, `$PROMOTE_PUSH_ERR`, and the `$PROMOTE_FIELDS` directory with `rm -rf`).
 </step>
 
 </process>

package/pp-core/workflows/verify-work.md

@@ -41,16 +41,14 @@ _PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_
 GSD_WS=""
 echo "$ARGUMENTS" | grep -qE -- '--ws[[:space:]]+[^[:space:]]+' && GSD_WS=$(echo "$ARGUMENTS" | grep -oE -- '--ws[[:space:]]+[^[:space:]]+')
 PHASE_ARG=$(echo "$ARGUMENTS" | sed -E 's/--ws[[:space:]]+[^[:space:]]+//g' | xargs)
-TIER_FLAG=$(printf '%s\n' "$ARGUMENTS" | grep -oE -- '--tier[[:space:]=]+(light|standard|heavy)' | head -1 | sed -E 's/^--tier[[:space:]=]+/--tier=/')
-PHASE_ARG=$(echo "$PHASE_ARG" | sed -E 's/--tier[[:space:]]+[a-z]+//g' | xargs)
 
-INIT=$(pp_run query init.verify-work "${PHASE_ARG}" ${GSD_WS} ${TIER_FLAG})
+INIT=$(pp_run query init.verify-work "${PHASE_ARG}" ${GSD_WS})
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_PLANNER=$(pp_run query agent-skills pp-planner)
 AGENT_SKILLS_CHECKER=$(pp_run query agent-skills pp-plan-checker)
 ```
 
-Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `plan_checker_enabled`, `plan_check_passes`, `phase_tier` (the phase's ceremony tier), `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`, `uat_path`.
+Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`, `uat_path`.
 
 ```bash
 # MVP mode detection via the centralized phase.mvp-mode resolver.
@@ -113,7 +111,7 @@ Continue to `create_uat_file`.
 Before UAT, check UI capability activation and whether Playwright/Puppeteer MCP tools are available.
 
 ```bash
-PLAN_HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "${phase_number}" ${TIER_FLAG}) || exit 1
+PLAN_HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw)
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 ```
 
@@ -460,12 +458,14 @@ Present summary:
 **If issues == 0:**
 
 ```bash
-VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${phase_number}" ${GSD_WS} ${TIER_FLAG}) || exit 1
-VERIFY_POST_GATES_JSON=$(pp_run loop run-gates verify:post --phase "${phase_number}" ${GSD_WS} ${TIER_FLAG}) || exit 1
+VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
+printf '%s' "$VERIFY_POST_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('VERIFY_POST_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
 ```
 
-`loop run-gates` runs every active `verify:post` gate and owns the halt: exit 1 (a `⛔` line) means a blocking gate blocked — stop, relay it, do not mark the phase complete. `⚠` lines are advisories: relay and continue.
+**Vault gates.** Read `pp-core/workflows/execute-phase/steps/verify-post-gate.md` — it
+dispatches this point's blocking gates to the generic enforcer, which owns the halt. Rendering the
+payload above is not enforcing it, and the branch below marks the phase complete.
 
 Resolve active step hooks from `VERIFY_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "secure-phase"`.
 
@@ -624,8 +624,6 @@ On return:
 <step name="verify_gap_plans">
 **Verify fix plans with checker:**
 
-**Skip if** `plan_checker_enabled` is false (the tier, or the project's explicit `false`) — go to `present_ready`.
-
 Run this Bash command to emit the branded Validate stage banner (renders on stderr, auto-degrades on non-TTY — do NOT print an inline ASCII banner, that would double-print):
 ```bash
 pp_run banner validate "VERIFYING"
@@ -677,11 +675,11 @@ On return:
 </step>
 
 <step name="revision_loop">
-**Iterate planner ↔ checker until plans pass (max `plan_check_passes`):**
+**Iterate planner ↔ checker until plans pass (max 3):**
 
-**If iteration_count < plan_check_passes:**
+**If iteration_count < 3:**
 
-Display: `Sending back to planner for revision... (iteration {N}/{plan_check_passes})`
+Display: `Sending back to planner for revision... (iteration {N}/3)`
 
 Spawn pp-planner with revision context:
 
@@ -720,7 +718,7 @@ Do NOT replan from scratch unless issues are fundamental.
 After planner returns → spawn checker again (verify_gap_plans logic)
 Increment iteration_count
 
-**If iteration_count >= plan_check_passes:**
+**If iteration_count >= 3:**
 
 Display: `Max iterations reached. {N} issues remain.`
 

package/scripts/changeset/cli.cjs

@@ -90,11 +90,12 @@ function parseArgs(argv) {
   return { ok: true, opts };
 }
 
-// Bare-checkout verify. A release tag job may run `verify` on a bare checkout:
-// no `npm ci`, no `build:lib`, and the compiled semver module under
-// pp-core/bin/lib is gitignored build output. Requiring that module at the top
-// of this file made `verify` (and `render`) die at require time on such a
-// checkout.
+// Release tag gate (#71924 gap plan 01-06). CI's
+// `tag_version_check` job runs `verify` on a bare checkout: no `npm ci`, no
+// `build:lib`, and the compiled semver module under pp-core/bin/lib is
+// gitignored build output. The first shipped version of that step required the
+// compiled module at the top of this file, so it died at require time on every
+// hosted checkout (never observed live: the step was skipped on every probe).
 // `verify` and `render` therefore require node builtins and tracked files only;
 // the compiled dependency is loaded lazily by `extract`, which the update
 // workflow runs on built trees.

package/scripts/changeset/new.cjs

@@ -4,56 +4,42 @@
 /**
  * Scaffolds a new changeset fragment (#2975).
  *
- *   npm run changeset -- --type Fixed --pr 1234 --body "fix the thing"
+ *   npm run changeset -- --type Fixed --pr 1234 --body "fix the thing" [--name <slug>]
  *
- * Writes `.changeset/<adjective>-<noun>-<noun>.md` with frontmatter
- * + body. The random three-word filename minimizes filename collision
- * across concurrent PRs.
+ * Writes `.changeset/<pr>-<slug>.md` with frontmatter + body. The slug is
+ * --name, else derived from the bold lead sentence; a taken name gets -2, -3, ...
+ * FORK-ONLY (PBI 74336): upstream draws a random three-word name.
  */
 
 const fs = require('node:fs');
 const path = require('node:path');
 const { ExitError, runMain } = require('../lib/cli-exit.cjs');
 
-// Small word lists — keep the function simple and dependency-free.
-// Together this gives ~40 * 40 * 40 = 64,000 distinct names. The lint
-// rejects any duplicate filename, so collisions are caught even when
-// the random draw repeats.
-const ADJECTIVES = [
-  'silly', 'brave', 'calm', 'eager', 'gentle', 'happy', 'jolly', 'kind',
-  'lively', 'merry', 'nimble', 'plucky', 'quick', 'sturdy', 'witty', 'zesty',
-  'bold', 'clever', 'daring', 'fierce', 'graceful', 'humble', 'lucky', 'noble',
-  'proud', 'rapid', 'sharp', 'tidy', 'vivid', 'wise', 'agile', 'curious',
-  'eager', 'gallant', 'mellow', 'patient', 'serene', 'steady', 'sturdy', 'sunny',
-];
-const NOUNS_A = [
-  'bears', 'birds', 'cats', 'dogs', 'elks', 'foxes', 'goats', 'hawks',
-  'ibex', 'jays', 'koalas', 'lynx', 'moles', 'newts', 'otters', 'pumas',
-  'quails', 'rams', 'seals', 'tigers', 'voles', 'wolves', 'yaks', 'zebras',
-  'badgers', 'cranes', 'deer', 'eagles', 'finches', 'geese', 'herons', 'jaguars',
-  'lemurs', 'mice', 'orcas', 'pandas', 'ravens', 'sloths', 'tunas', 'wasps',
-];
-const NOUNS_B = [
-  'dance', 'sing', 'leap', 'run', 'jump', 'climb', 'fly', 'swim',
-  'rest', 'wake', 'roam', 'greet', 'wander', 'gather', 'forage', 'travel',
-  'glide', 'sprint', 'tumble', 'wave', 'cheer', 'rally', 'parade', 'march',
-  'hop', 'frolic', 'caper', 'romp', 'zip', 'dart', 'snooze', 'munch',
-  'chatter', 'squeak', 'howl', 'bark', 'purr', 'roar', 'hum', 'click',
-];
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SLUG_STOPWORDS = new Set(['a', 'an', 'the', 'and', 'or', 'of', 'to', 'for', 'in', 'on', 'is', 'are', 'now', 'its']);
+const SLUG_MAX_WORDS = 7;
 
-function pick(arr) {
-  return arr[Math.floor(Math.random() * arr.length)];
+// Kebab-case slug from the bold lead sentence (or the first sentence), minus filler words.
+function deriveFragmentSlug(body) {
+  const bold = /\*\*([^*]+)\*\*/.exec(body || '');
+  const lead = bold ? bold[1] : String(body || '').trim().split(/[.!?\n]/)[0];
+  const words = lead
+    .toLowerCase()
+    .replace(/'s\b/g, '')
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w && !SLUG_STOPWORDS.has(w));
+  return words.slice(0, SLUG_MAX_WORDS).join('-') || 'change';
 }
 
-function generateFragmentName() {
-  return `${pick(ADJECTIVES)}-${pick(NOUNS_A)}-${pick(NOUNS_B)}`;
+function fragmentBaseName({ pr, body, name }) {
+  return `${pr}-${name || deriveFragmentSlug(body)}`;
 }
 
 // Allowed Keep-a-Changelog section types. Used by both scaffoldFragment
 // (sanitization at write time) and parse.cjs (validation at consume time).
 const ALLOWED_TYPES = new Set(['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']);
 
-function scaffoldFragment({ repo, type, pr, body }) {
+function scaffoldFragment({ repo, type, pr, body, name = null }) {
   // Sanitize: reject any type value not on the allowlist BEFORE embedding it
   // in frontmatter. A newline in `type` would corrupt the fragment; an
   // unrecognized value would be rejected later by parse.cjs but with a
@@ -63,28 +49,24 @@ function scaffoldFragment({ repo, type, pr, body }) {
       `scaffoldFragment: type=${JSON.stringify(type)} is not one of [${[...ALLOWED_TYPES].join(', ')}]`,
     );
   }
+  if (name !== null && !SLUG_RE.test(name)) {
+    throw new Error(`scaffoldFragment: name=${JSON.stringify(name)} is not kebab-case (a-z, 0-9, hyphens)`);
+  }
   const dir = path.join(repo, '.changeset');
   fs.mkdirSync(dir, { recursive: true });
   const content = `---\ntype: ${type}\npr: ${pr}\n---\n${body}\n`;
-  // Atomic create: writeFileSync with `flag: 'wx'` fails (EEXIST) when the
-  // file already exists, so concurrent invocations can't race past
-  // `existsSync` and overwrite each other. Re-roll the random name on
-  // collision; fail loudly after exhausting the retry budget.
-  for (let i = 0; i < 16; i++) {
-    const name = generateFragmentName();
-    const target = path.join(dir, `${name}.md`);
+  // flag 'wx' fails with EEXIST instead of overwriting, so concurrent runs cannot clobber a fragment.
+  const base = fragmentBaseName({ pr, body, name });
+  for (let i = 1; i <= 50; i++) {
+    const target = path.join(dir, `${i === 1 ? base : `${base}-${i}`}.md`);
     try {
       fs.writeFileSync(target, content, { flag: 'wx' });
       return target;
     } catch (e) {
       if (e.code !== 'EEXIST') throw e;
-      // collision — try another random draw
     }
   }
-  throw new Error(
-    'scaffoldFragment: 16 random filename draws all collided; ' +
-    'expand the word lists or investigate corrupted .changeset/ state',
-  );
+  throw new Error(`scaffoldFragment: ${base}.md and 49 numbered variants already exist; pass --name`);
 }
 
 function parseArgs(argv) {
@@ -102,7 +84,7 @@ function parseArgs(argv) {
 
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--type' || a === '--pr' || a === '--body' || a === '--repo') {
+    if (a === '--type' || a === '--pr' || a === '--body' || a === '--name' || a === '--repo') {
       const r = requireValue(a, i);
       if (!r.ok) return { ok: false, error: r.error };
       if (a === '--type') opts.type = r.value;
@@ -114,6 +96,7 @@ function parseArgs(argv) {
         const trimmed = r.value.trim();
         opts.pr = /^\d+$/.test(trimmed) ? Number(trimmed) : NaN;
       } else if (a === '--body') opts.body = r.value;
+      else if (a === '--name') opts.name = r.value;
       else if (a === '--repo') opts.repo = r.value;
       i++;
       continue;
@@ -127,7 +110,7 @@ function main() {
   const parsed = parseArgs(process.argv.slice(2));
   if (!parsed.ok) {
     process.stderr.write(`${parsed.error}\n`);
-    process.stderr.write('usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..."\n');
+    process.stderr.write('usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..." [--name <slug>]\n');
     throw new ExitError(2);
   }
   const { opts } = parsed;
@@ -140,7 +123,7 @@ function main() {
   const prMissing = opts.pr === null;
   const prNaN = typeof opts.pr === 'number' && Number.isNaN(opts.pr);
   if (!opts.type || prMissing || prNaN || !opts.body) {
-    throw new ExitError(2, 'usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..."');
+    throw new ExitError(2, 'usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..." [--name <slug>]');
   }
   const file = scaffoldFragment(opts);
   process.stdout.write(`${path.relative(process.cwd(), file)}\n`);
@@ -148,4 +131,4 @@ function main() {
 
 if (require.main === module) runMain(main);
 
-module.exports = { generateFragmentName, scaffoldFragment, parseArgs, ALLOWED_TYPES };
+module.exports = { deriveFragmentSlug, fragmentBaseName, scaffoldFragment, parseArgs, ALLOWED_TYPES };