@pareto4/pp-core 1.11.0 → 1.12.0

package/pp-core/bin/lib/verify.cjs

@@ -31,6 +31,8 @@ const schema_detect_cjs_1 = require("./schema-detect.cjs");
 const artifacts_cjs_1 = require("./artifacts.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- agent-install-check.cjs is an export= CommonJS module
 const agentInstallCheck = require("./agent-install-check.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- milestone.cjs is an export= CommonJS module
+const milestoneMod = require("./milestone.cjs");
 const { checkAgentsInstalled } = agentInstallCheck;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
@@ -42,15 +44,16 @@ const { loadConfig, CONFIG_DEFAULTS } = configLoaderMod;
 const phaseIdMod = require("./phase-id.cjs");
 const { normalizePhaseName, phaseTokenMatches, escapeRegex, getMilestoneFromPhaseId } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal } = phaseLocatorMod;
+const phaseScopeMod = require("./phase-scope.cjs");
+const { resolvePhaseForRead } = phaseScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
-const { getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone } = roadmapParserMod;
+const { getDeclaredMilestoneInfo, stripShippedMilestones, extractCurrentMilestone } = roadmapParserMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const worktreeSafetyMod = require("./worktree-safety.cjs");
 const { inspectWorktreeHealth } = worktreeSafetyMod;
-const { planningDir } = planningWorkspace;
+const plan_graph_cjs_1 = require("./plan-graph.cjs");
+const { planningDir, milestonePathsFor, resolveProjectFile } = planningWorkspace;
 const { extractFrontmatter, parseMustHavesBlock } = frontmatterMod;
 const { writeStateMd } = stateMod;
 const { MODEL_PROFILES } = modelProfilesMod;
@@ -538,6 +541,16 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
         if (fm[field] === undefined)
             errors.push(`Missing required frontmatter field: ${field}`);
     }
+    // `title:` is required on every plan not yet executed. A plan that already has a
+    // SUMMARY predates the rule (or ran without it): its missing title only warns.
+    const titleProblem = (0, plan_graph_cjs_1.planTitleProblem)(fm['title']);
+    if (titleProblem) {
+        const summaryPath = fullPath.replace(/PLAN\.md$/, 'SUMMARY.md');
+        if (summaryPath !== fullPath && node_fs_1.default.existsSync(summaryPath))
+            warnings.push(`${titleProblem} (executed plan: warning only)`);
+        else
+            errors.push(titleProblem);
+    }
     const taskPattern = /<task[^>]*>([\s\S]*?)<\/task>/g;
     const tasks = [];
     let taskMatch;
@@ -592,7 +605,7 @@ function cmdVerifyPhaseCompleteness(cwd, phase, raw) {
     if (!phase) {
         error('phase required');
     }
-    const phaseInfoRaw = findPhaseInternal(cwd, phase);
+    const phaseInfoRaw = resolvePhaseForRead(cwd, phase);
     if (!phaseInfoRaw || !phaseInfoRaw['found']) {
         output({ error: 'Phase not found', phase }, raw);
         return;
@@ -898,7 +911,10 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
     }, raw, allVerified ? 'valid' : 'invalid');
 }
 function listMilestoneArchiveDirs(planBase) {
-    const milestonesDir = node_path_1.default.join(planBase, 'milestones');
+    // CARRY-05: one owner for the archive-directory location, shared with the
+    // `milestone complete` writer. planBase is planningDir(cwd) at every call
+    // site, so this already followed --ws; routing it here keeps it that way.
+    const milestonesDir = milestonePathsFor(planBase).milestonesArchive;
     try {
         return node_fs_1.default
             .readdirSync(milestonesDir, { withFileTypes: true })
@@ -938,7 +954,7 @@ function getActiveMilestoneArchiveDir(planBase) {
             const m = state.match(/^\s*(?:\*\*)?milestone(?:\*\*)?:\s*\*{0,2}\s*([^\s*\r\n#][^\s\r\n#]*)/mi);
             if (m && m[1]) {
                 const milestone = m[1].trim();
-                const candidate = node_path_1.default.join(planBase, 'milestones', `${milestone}-phases`);
+                const candidate = node_path_1.default.join(milestonePathsFor(planBase).milestonesArchive, `${milestone}-phases`);
                 return archiveDirs.includes(candidate) ? candidate : null;
             }
         }
@@ -1113,7 +1129,9 @@ function cmdValidateHealth(cwd, options, raw) {
         return;
     }
     const planBase = planningDir(cwd);
-    const projectPath = node_path_1.default.join(planBase, 'PROJECT.md');
+    // D1 (261007-jkl): E002/W001 judge the PROJECT.md that answers for this cwd —
+    // the workstream's own, else the shared one — not a workstream path nothing creates.
+    const projectPath = resolveProjectFile(cwd).path;
     const roadmapPath = node_path_1.default.join(planBase, 'ROADMAP.md');
     const statePath = node_path_1.default.join(planBase, 'STATE.md');
     const configPath = node_path_1.default.join(planBase, 'config.json');
@@ -1134,7 +1152,7 @@ function cmdValidateHealth(cwd, options, raw) {
             info.push(issue);
     };
     if (!node_fs_1.default.existsSync(planBase)) {
-        addIssue('error', 'E001', '.planning/ directory not found', `Run ${slash('new-project')} to initialize`);
+        addIssue('error', 'E001', '.planning/ directory not found', `Run ${slash('init')} to initialize`);
         output({ status: 'broken', errors, warnings, info, repairable_count: 0 }, raw);
         return;
     }
@@ -1440,8 +1458,8 @@ function cmdValidateHealth(cwd, options, raw) {
     catch {
         /* W021 check is advisory — skip on error */
     }
-    const milestonesPath = node_path_1.default.join(planBase, 'MILESTONES.md');
-    const milestonesArchiveDir = node_path_1.default.join(planBase, 'milestones');
+    // CARRY-05: W018's two paths come from the owner, not a local join.
+    const { milestones: milestonesPath, milestonesArchive: milestonesArchiveDir } = milestonePathsFor(planBase);
     const missingFromRegistry = [];
     try {
         if (node_fs_1.default.existsSync(milestonesArchiveDir)) {
@@ -1530,8 +1548,13 @@ function cmdValidateHealth(cwd, options, raw) {
     }
     // ─── Perform repairs if requested ─────────────────────────────────────────
     const repairActions = [];
-    if (options['repair'] && repairs.length > 0) {
+    // 261007-rly D-9: `--backfill` alone runs the backfill W018 names as its
+    // remedy (health.md documents it as "triggered by `--backfill`"); every other
+    // repair still needs `--repair`.
+    if ((options['repair'] || options['backfill']) && repairs.length > 0) {
         for (const repair of repairs) {
+            if (!options['repair'] && repair !== 'backfillMilestones')
+                continue;
             try {
                 switch (repair) {
                     case 'createConfig':
@@ -1564,22 +1587,24 @@ function cmdValidateHealth(cwd, options, raw) {
                             node_fs_1.default.copyFileSync(statePath, backupPath);
                             repairActions.push({ action: 'backupState', success: true, path: backupPath });
                         }
-                        const milestone = getMilestoneInfo(cwd);
+                        const milestone = getDeclaredMilestoneInfo(cwd); // 261007-ixt W4: never a guessed milestone
+                        // D1 (261007-jkl): reference the PROJECT.md that answers for this cwd.
                         const projectRef = node_path_1.default
-                            .relative(cwd, node_path_1.default.join(planningDir(cwd), 'PROJECT.md'))
+                            .relative(cwd, resolveProjectFile(cwd).path)
                             .split(node_path_1.default.sep)
                             .join('/');
                         let stateContent = `# Session State\n\n`;
                         stateContent += `## Project Reference\n\n`;
                         stateContent += `See: ${projectRef}\n\n`;
                         stateContent += `## Position\n\n`;
-                        stateContent += `**Milestone:** ${milestone.version} ${milestone.name}\n`;
+                        stateContent += `**Milestone:** ${milestone ? `${milestone.version} ${milestone.name}` : 'none declared in ROADMAP.md'}\n`;
                         stateContent += `**Current phase:** (determining...)\n`;
                         stateContent += `**Status:** Resuming\n\n`;
                         stateContent += `## Session Log\n\n`;
                         stateContent += `- ${new Date().toISOString().split('T')[0]}: STATE.md regenerated by ${slash('health')} --repair\n`;
-                        writeStateMd(statePath, stateContent, cwd);
-                        repairActions.push({ action: repair, success: true, path: 'STATE.md' });
+                        // 261007-ixt D-3: the repair names every frontmatter key it wrote.
+                        const stateReport = writeStateMd(statePath, stateContent, cwd);
+                        repairActions.push({ action: repair, success: true, path: 'STATE.md', frontmatter_updated: stateReport.frontmatter_updated });
                         break;
                     }
                     case 'addNyquistKey': {
@@ -1647,20 +1672,17 @@ function cmdValidateHealth(cwd, options, raw) {
                                 const milestonesContent = node_fs_1.default.existsSync(milestonesPath)
                                     ? node_fs_1.default.readFileSync(milestonesPath, 'utf-8')
                                     : '';
-                                if (!milestonesContent.trim()) {
-                                    (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, `# Milestones\n\n${entry}`);
-                                }
-                                else {
-                                    const headerMatch = milestonesContent.match(/^(#{1,3}\s+[^\n]*\n\n?)/);
-                                    if (headerMatch) {
-                                        const header = headerMatch[1];
-                                        const rest = milestonesContent.slice(header.length);
-                                        (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, header + entry + rest);
-                                    }
-                                    else {
-                                        (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, entry + milestonesContent);
-                                    }
-                                }
+                                // 261007-rly D-6: the same record writer `milestone complete` uses —
+                                // one index row (the version and the snapshot read are all a backfill
+                                // knows; every other cell is the unknown marker) and the section after
+                                // the table, never between the H1 and the table.
+                                const snapshotLink = node_path_1.default.relative(node_path_1.default.dirname(milestonesPath), snapshotPath).split(node_path_1.default.sep).join('/');
+                                const record = milestoneMod.insertMilestoneRecord(milestonesContent, {
+                                    version: ver,
+                                    entry,
+                                    cells: { version: ver, archive: `[${ver}-ROADMAP.md](${snapshotLink})` },
+                                });
+                                (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, record.content);
                                 backfilled++;
                             }
                             catch {

package/pp-core/bin/lib/workstream.cjs

@@ -102,7 +102,7 @@ function cmdWorkstreamCreate(cwd, name, options, raw) {
     }
     const baseDir = planningRoot(cwd);
     if (!node_fs_1.default.existsSync(baseDir)) {
-        error(`.planning/ directory not found — run ${(0, runtime_slash_cjs_1.formatGsdSlash)('new-project', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} first`);
+        error(`.planning/ directory not found — run ${(0, runtime_slash_cjs_1.formatPpSlash)('init', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} first`);
     }
     const wsRoot = node_path_1.default.join(baseDir, 'workstreams');
     const wsDir = node_path_1.default.join(wsRoot, slug);

package/pp-core/bin/lib/worktree-safety.cjs

@@ -409,9 +409,10 @@ function defaultFindSummaryFiles(worktreePath) {
  * For each *SUMMARY.md found under <worktreePath>/.planning/:
  *   - compute relative path from worktree root  → .planning/<id>-SUMMARY.md
  *   - if the file is ALREADY COMMITTED on the worktree branch
- *     (`git cat-file -e HEAD:<relPath>` returns exit 0), skip the copy entirely:
- *     the merge will carry it naturally and copying it as an untracked file would
- *     cause a "untracked working tree files would be overwritten by merge" collision.
+ *     (`git ls-tree -z --full-tree --name-only HEAD -- <relPath>` prints the path),
+ *     skip the copy entirely: the merge will carry it naturally and copying it as
+ *     an untracked file would cause a "untracked working tree files would be
+ *     overwritten by merge" collision.  Empty ls-tree output means not committed.
  *     On timeout or fatal exit (128) the rescue is also skipped (fail-closed).
  *     (#706 — execute-phase committed-SUMMARY contract)
  *   - destination = <repoRoot>/<relPath>
@@ -442,27 +443,37 @@ function rescueSummaryArtifacts(worktreePath, repoRoot, deps) {
         // output works on Windows too (git always emits forward slashes in porcelain output).
         const relPath = absPath.slice(worktreePath.length).replace(/^[/\\]/, '').replace(/\\/g, '/');
         // #706: skip rescue when the SUMMARY is already committed on the branch.
-        // Use `git cat-file -e HEAD:<relPath>` (not `ls-files --error-unmatch`) so
-        // the check is against the committed tree, not the index.  ls-files also
-        // matches staged-but-uncommitted files, which would skip rescue when the
-        // file is staged but not yet committed — the merge wouldn't carry it, and
-        // the executor's content could be lost.  cat-file -e HEAD:<path> returns
-        // exit 0 only when the object exists in the committed HEAD tree.
+        // Ask the committed HEAD tree directly with `git ls-tree -z --name-only
+        // HEAD -- <relPath>` (not `ls-files --error-unmatch`, which also matches
+        // staged-but-uncommitted files the merge would NOT carry).  ls-tree exits 0
+        // in both answers: the path on stdout when it is in HEAD, empty stdout when
+        // it is not.  That is the property the previous form lacked: `cat-file -e
+        // HEAD:<relPath>` resolves the object NAME first and dies (exit 128, "path
+        // '…' does not exist in 'HEAD'") for any path not in HEAD — on every git
+        // from 1.7 through 2.55 — while its exit 1 is reserved for a raw OID missing
+        // from the store.  So the fail-closed arm below swallowed every uncommitted
+        // SUMMARY and cleanup-wave blocked with worktree_dirty on each /pp-quick
+        // worktree run (261002 vault-gate probe).  `-z` keeps the comparison byte-
+        // exact: without it core.quotePath would C-quote a non-ASCII path and a
+        // committed file would read as absent, re-creating the #706 collision.
         //
         // Fail-closed on timeout/fatal git errors: if we cannot determine whether
         // the file is committed, do NOT rescue it (rescuing an actually-committed
         // file would re-create the untracked collision; the merge will surface the
         // issue).  The cleanup will be blocked by merge_failed in the worst case,
         // which is the observable behaviour before this fix and is recoverable.
-        const catFileResult = execGit(['-C', worktreePath, 'cat-file', '-e', `HEAD:${relPath}`], { cwd: repoRoot });
-        if (catFileResult.exitCode !== 1) {
-            // Rescue only when cat-file definitively reports the object is absent (exit 1).
-            //   exit 0  → object exists (committed on HEAD) — merge will carry it, skip.
+        const treeCheck = execGit(['-C', worktreePath, 'ls-tree', '-z', '--full-tree', '--name-only', 'HEAD', '--', relPath], { cwd: repoRoot });
+        if (!gitResultOk(treeCheck)) {
             //   exit 128 → fatal git error (corrupt store, unborn HEAD, etc.) — uncertain,
             //              fail-closed: do NOT rescue to avoid recreating the #706 collision.
             //   timedOut / null / other → unreliable result — same fail-closed policy.
-            // In all non-1 cases the merge will either succeed naturally (0) or surface
-            // the problem safely (128/timeout), which is the recoverable pre-fix behaviour.
+            // The merge then surfaces the problem safely, which is the recoverable
+            // pre-fix behaviour.
+            continue;
+        }
+        const committedOnHead = (treeCheck.stdout || '').split('\0').some((line) => line === relPath);
+        if (committedOnHead) {
+            // Object exists in the committed HEAD tree — the merge will carry it, skip.
             continue;
         }
         const dest = node_path_1.default.join(repoRoot, relPath);

package/pp-core/bin/portable-timeout.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# portable-timeout.sh — THE portable timeout wrapper for this repository (D-09-03).
+#
+# SOURCED, never executed. It defines three functions and nothing else, and it
+# deliberately sets no `set -e` / `set -u`: it is sourced into shells that may
+# or may not use them.
+#
+# Consumers:
+#   - scripts/base64-scan.sh                  (CI, executed)
+#   - the gate blocks in pp-core/workflows/   (runtime; wired by plan 09-02)
+#
+# Why it lives in pp-core/bin/ rather than scripts/:
+#   `scripts/` shell files are not installed — pp-file-manifest.json carries no
+#   `scripts/*.sh` entry, so an installed workflow can neither find nor source
+#   scripts/base64-scan.sh (which also ends in an unguarded `main "$@"`).
+#   `pp-core/` is copied wholesale at install time — bin/install.js's
+#   copyWithPathReplacement() falls through to fs.copyFileSync for any non-.md
+#   file, so a .sh arrives byte-identical — it is in package.json "files", and
+#   it already hosts the tracked shell launcher `pp_run`. `pp-core/bin/lib/` was
+#   deliberately NOT used: several .cjs files there are gitignored build output
+#   and the directory reads as compiler output.
+#
+# MEASURED exit-code matrix (macOS 26.5, bash 3.2.57, no timeout and no
+# gtimeout on PATH, perl at /usr/bin/perl; re-measured 2026-09-19 and pinned by
+# tests/gate-shell-owners.test.cjs):
+#
+#   run_with_timeout 1 sleep 5                      -> 142 (perl) / 124 (GNU)
+#   run_with_timeout 5 bash -c '<missing command>'  -> 127 under every backend
+#   run_with_timeout 5 <missing binary>             ->   2 under perl, 127 GNU
+#   run_with_timeout 5 true                         ->   0
+#   run_with_timeout 5 bash -c 'exit 7'             ->   7
+#
+#   CAVEAT, and the reason that third row is pinned by a test: under the perl
+#   backend a DIRECT exec of a missing binary exits 2 — perl's own
+#   `die "exec: $!"` — not 127. A caller that wants a portable "never ran"
+#   signal must wrap its command in `bash -c "$CMD"`. Every gate block does,
+#   except the two that exec a binary directly (code-review.md's Fallow binary
+#   and ship.md's ${REVIEW_CMD}); those see 2, not 127, when the binary is absent.
+#
+# Backend selection is injectable for tests by assigning _TIMEOUT_CMD AFTER
+# sourcing (`. portable-timeout.sh; _TIMEOUT_CMD=perl_alarm`) — _init_timeout_cmd
+# returns early when it is already set, so no edit to the moved block was needed
+# to make the backend selectable.
+#
+# Everything below this line is moved BYTE-VERBATIM from
+# scripts/base64-scan.sh:42-83, which now sources this file instead.
+
+# -- Portable timeout wrapper (#116) ------------------------------------------
+# macOS does not ship GNU coreutils timeout.  We probe for it (or gtimeout
+# from homebrew coreutils), falling back to perl alarm(N)+exec.
+# Exit codes: GNU timeout uses 124 on timeout; perl SIGALRM produces 142.
+# Both are treated as timeout exits by is_timeout_exit() below.
+# Usage: run_with_timeout <seconds> <command> [args...]
+_TIMEOUT_CMD=""
+# shellcheck disable=SC2329  # intentionally defined for use by callers; not called in main loop
+_init_timeout_cmd() {
+  if [[ -n "$_TIMEOUT_CMD" ]]; then return; fi
+  if command -v timeout >/dev/null 2>&1; then
+    _TIMEOUT_CMD="timeout"
+  elif command -v gtimeout >/dev/null 2>&1; then
+    _TIMEOUT_CMD="gtimeout"
+  else
+    _TIMEOUT_CMD="perl_alarm"
+  fi
+}
+
+# shellcheck disable=SC2329  # intentionally defined for use by callers; not called in main loop
+run_with_timeout() {
+  local secs="$1"; shift
+  _init_timeout_cmd
+  case "$_TIMEOUT_CMD" in
+    timeout|gtimeout)
+      "$_TIMEOUT_CMD" "$secs" "$@"
+      ;;
+    perl_alarm)
+      # perl sets SIGALRM after N seconds, then exec()s the command.
+      # Exit 142 (SIGALRM) when timed out.
+      perl -e '
+        my $secs = shift @ARGV;
+        alarm($secs);
+        exec(@ARGV) or die "exec: $!\n";
+      ' -- "$secs" "$@"
+      ;;
+  esac
+}
+
+# is_timeout_exit: returns 0 (true) if rc indicates a timeout kill.
+# shellcheck disable=SC2329  # intentionally defined for use by callers; not called in main loop
+is_timeout_exit() { [[ "$1" -eq 124 || "$1" -eq 142 ]]; }

package/pp-core/bin/pp-tools.cjs

@@ -57,6 +57,7 @@
  *   milestone complete <version>       Archive milestone, create MILESTONES.md
  *     [--name <name>]
  *     [--archive-phases]               Move phase dirs to milestones/vX.Y-phases/
+ *     [--stopped-at <text>]            New Session "Stopped at:" (else stopped_at is kept)
  *
  * User Story Validation:
  *   user-story validate --story "..."  Validate "As a / I want to / so that" format
@@ -525,7 +526,7 @@ async function main() {
   const TOP_LEVEL_USAGE = 'Usage: pp-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>] [--json-errors]\n' +
     'Commands: agent, agent-skills, audit-open, audit-uat, check, check-commit, commit, commit-to-subrepo, ' +
     'compose-bindings, config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, ' +
-    'current-timestamp, detect-custom-files, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
+    'current-timestamp, detect-custom-files, discovery, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
     'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
     'generate-client-context, generate-dev-preferences, generate-slug, graphify, history-digest, init, init-contract, intel, ' +
     'capability, classify-confidence, git, learnings, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, platform-bindings, profile-questionnaire, ' +
@@ -713,8 +714,8 @@ function extractField(obj, fieldPath) {
  * (Phase 34-09's own design hazard) so the interactive flow stays testable
  * with a scripted fake and no pty.
  */
-function createReadlinePrompter() {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+function createReadlinePrompter({ input = process.stdin, output = process.stdout } = {}) {
+  const rl = readline.createInterface({ input, output });
   return {
     ask(question) {
       let rendered = question.prompt;
@@ -725,16 +726,29 @@ function createReadlinePrompter() {
           )
           .join(' / ');
         rendered += `\n  Options: ${optionsRendered}`;
+      } else if (question.preselected) {
+        // INIT-PATCH-C: an option-less question carrying a `preselected`
+        // (e.g. a detected org profile) rendered no default at all today —
+        // render one, naming it via `preselectedLabel` when present.
+        rendered += `\n  Default: ${question.preselectedLabel || question.preselected} (press Enter to accept)`;
       }
       if (question.optionalAnswer) {
-        rendered += '\n  (press Enter to skip)';
+        // The unconditional "Enter skips" hint would be a lie once a
+        // default is carried — Enter now ACCEPTS the default above, so the
+        // skip hint must point at "none" instead. The question text may
+        // already carry that hint (both org profile prompts do), so it is
+        // added only for an optional question whose text lacks it (I-1).
+        const skipHint = question.preselected ? 'type "none" to skip' : 'press Enter to skip';
+        if (!String(question.prompt).toLowerCase().includes(skipHint.toLowerCase())) {
+          rendered += `\n  (${skipHint})`;
+        }
       }
       return new Promise((resolve) => {
         rl.question(`${rendered}\n> `, (answer) => resolve(answer));
       });
     },
     print(text) {
-      process.stdout.write(`${text}\n`);
+      output.write(`${text}\n`);
     },
     close() {
       rl.close();
@@ -811,6 +825,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
     case 'init-contract': {
       // init-contract [--questions] [--verify] [--session-next]
       //   [--session-answer <stepId>=<value>] [--session-reset] [--offline]
+      //   [--arm-vault]
       // --questions (also the no-flag default, D-05): read-only, always
       // exits 0, prints the canonical /pp-init question set as data.
       // --verify: runs the end-state invariant check (Phase 34-07 gap
@@ -844,7 +859,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       );
       if (unrecognizedIcFlag !== undefined) {
         error(
-          `Unrecognized flag "${unrecognizedIcFlag}" for init-contract. Supported: --questions, --verify, --session-next, --session-answer, --session-reset, --offline.`,
+          `Unrecognized flag "${unrecognizedIcFlag}" for init-contract. Supported: --questions, --verify, --session-next, --session-answer, --session-reset, --offline, --arm-vault.`,
           ERROR_REASON.SDK_FAIL_FAST,
         );
         break;
@@ -862,6 +877,9 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
           icOptions.sessionReset = true;
         } else if (a === '--offline') {
           icOptions.offline = true;
+        } else if (a === '--arm-vault') {
+          // Pack 6 D-09: set vault.enabled true only where absent.
+          icOptions.armVault = true;
         }
       }
       if (sessionAnswerRaw !== undefined) {
@@ -1402,9 +1420,10 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       const subcommand = args[1];
       if (subcommand === 'complete') {
         const milestoneName = parseMultiwordArg(args, 'name');
+        const stoppedAt = parseMultiwordArg(args, 'stopped-at');
         const archivePhases = args.includes('--archive-phases');
         const force = args.includes('--force');
-        milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases, force }, raw);
+        milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases, force, stoppedAt }, raw);
       } else {
         error('Unknown milestone subcommand. Available: complete', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
@@ -1497,6 +1516,8 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
         if (!process.stdin.isTTY) {
           error(
             '"pp-tools init" requires an interactive terminal (stdin is not a TTY) and will not prompt. ' +
+              'This command cannot run inside an AI-agent shell or a piped session — open a regular ' +
+              'terminal window (e.g. Terminal, iTerm, or Windows Terminal) and run it there. ' +
               'For a non-interactive/CI-driven session, use "pp-tools query init-contract --session-next" / ' +
               '"--session-answer <stepId>=<value>" directly instead.',
             ERROR_REASON.INIT_NON_INTERACTIVE,
@@ -1563,9 +1584,24 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
           }
           loopActiveCap = value;
         }
+        // --phase <N> / --tier <light|standard|heavy>: resolve the phase's
+        // ceremony tier and read the gate booleans from it (pack 9).
+        const loopValue = (flag) => {
+          const eq = args.find(arg => arg.startsWith(`--${flag}=`));
+          if (eq) return eq.slice(flag.length + 3).trim();
+          const idx = args.indexOf(`--${flag}`);
+          if (idx === -1) return undefined;
+          const value = args[idx + 1];
+          if (!value || value.startsWith('--')) {
+            error(`Missing value for --${flag}`, ERROR_REASON ? ERROR_REASON.USAGE : undefined);
+          }
+          return value;
+        };
         loopResolver.cmdLoopRenderHooks(cwd, args[2], raw, {
           configDir: loopConfigDir ? path.resolve(loopConfigDir) : undefined,
           activeCap: loopActiveCap,
+          phase: loopValue('phase'),
+          tier: loopValue('tier'),
         });
       } else {
         error(
@@ -2299,6 +2335,120 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       break;
     }
 
+    // ─── Discovery ─────────────────────────────────────────────────────────
+    //
+    // discovery rollup <path> [--check]
+    //
+    // Read-only rollup of a discovery _requirements.md artifact (discovery-v2
+    // Phase 1, REQM-04). Plain mode always exits 0 with JSON + rendered totals
+    // table; --check exits non-zero on drift, marker problems, or parse
+    // failure (D-07/D-08). The dotted form `query discovery.rollup` reaches
+    // here via the dispatcher dot-split above.
+    //
+    // discovery input-check
+    //
+    // Input-package enforcement (discovery-v2 Phase 2, INPUT-02/INPUT-03).
+    // No positional path — fixed convention paths resolve against cwd. Exits
+    // non-zero (discovery_input_check_failed) when a session is Completed
+    // with [TO CONFIRM] markers remaining, a completeness_score counts
+    // unconfirmed topics (D-18/D-19), or git tracks a file under
+    // .planning/discovery-input/confidential/ (D-22). Non-git projects,
+    // missing input packages, and marker-free engagements exit 0. The dotted
+    // form `query discovery.input-check` reaches here the same way.
+    //
+    // discovery research-check
+    //
+    // Research-track enforcement (discovery-v2 Phase 3, RTRK-01/02/03 +
+    // TRACE-05). No positional path — fixed convention paths resolve against
+    // cwd. Exits non-zero (discovery_research_check_failed) on any STRUCTURAL
+    // fault in .planning/discovery/_research.md, _risks.md or _sparring.md, or
+    // in a ⚠️ CONDITIONAL marker that cites them (D-42). Never-blocks contract
+    // (D-43): unfinished research is NOT a fault — an Open Gates-MVP item exits
+    // 0 and is reported under open_by_priority, so a still-running research
+    // item can never block Session 13 sign-off. A project with no research
+    // artifacts, a register absent while a sibling is present, and an absent
+    // _requirements.md all exit 0. The dotted form
+    // `query discovery.research-check` reaches here the same way.
+    //
+    // discovery screen-check
+    //
+    // Screen-inventory and feedback-loop enforcement (discovery-v2 Phase 4,
+    // TRACE-02/TRACE-03/TRACE-04 + GUARD-01). No positional path — fixed
+    // convention paths resolve against cwd. Exits non-zero
+    // (discovery_screen_check_failed) on any STRUCTURAL fault in
+    // .planning/discovery/_screens.md or _feedback.md, in the D-51 computed
+    // coverage block, or in the D-54 build-tree scan that asserts discovery
+    // instrumentation never shipped. Never-blocks contract (D-43): an
+    // unprocessed feedback row is NOT a fault — a round whose every Processing
+    // cell is Open exits 0 and is reported under open_feedback, and the
+    // outstanding-work payload is emitted on the failure path too. Graceful
+    // arms: a project with no discovery package, an absent _screens.md, an
+    // absent _requirements.md, and an absent _risks.md/_research.md all exit 0,
+    // and the build-tree scan does not run at all unless a discovery artifact
+    // was found. The dotted form `query discovery.screen-check` reaches here
+    // the same way.
+    //
+    // discovery element-sweep [--check]
+    //
+    // Lists every functional element of the prototype under
+    // .planning/discovery/prototype/ so each is decided once in _sweep.md;
+    // --check fails (discovery_element_sweep_failed) while one is undecided.
+
+    case 'discovery': {
+      const subcommand = args[1];
+      if (subcommand === 'rollup') {
+        const rollup = require('./lib/discovery-rollup.cjs');
+        try {
+          rollup.cmdDiscoveryRollup(cwd, args, raw);
+        } catch (rollupErr) {
+          error(`discovery rollup: ${rollupErr && rollupErr.message ? rollupErr.message : String(rollupErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'input-check') {
+        const inputCheck = require('./lib/discovery-input-check.cjs');
+        try {
+          inputCheck.cmdDiscoveryInputCheck(cwd, args, raw);
+        } catch (inputCheckErr) {
+          error(`discovery input-check: ${inputCheckErr && inputCheckErr.message ? inputCheckErr.message : String(inputCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'research-check') {
+        const researchTrack = require('./lib/discovery-research-track.cjs');
+        try {
+          researchTrack.cmdDiscoveryResearchCheck(cwd, args, raw);
+        } catch (researchCheckErr) {
+          error(`discovery research-check: ${researchCheckErr && researchCheckErr.message ? researchCheckErr.message : String(researchCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'screen-check') {
+        const screens = require('./lib/discovery-screens.cjs');
+        try {
+          screens.cmdDiscoveryScreenCheck(cwd, args, raw);
+        } catch (screenCheckErr) {
+          error(`discovery screen-check: ${screenCheckErr && screenCheckErr.message ? screenCheckErr.message : String(screenCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'element-sweep') {
+        const sweep = require('./lib/discovery-sweep.cjs');
+        try {
+          sweep.cmdDiscoveryElementSweep(cwd, args, raw);
+        } catch (sweepErr) {
+          error(`discovery element-sweep: ${sweepErr && sweepErr.message ? sweepErr.message : String(sweepErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'rebaseline-check') {
+        const rebaseline = require('./lib/discovery-rebaseline.cjs');
+        try {
+          rebaseline.cmdDiscoveryRebaselineCheck(cwd, args, raw);
+        } catch (rebaselineCheckErr) {
+          error(`discovery rebaseline-check: ${rebaselineCheckErr && rebaselineCheckErr.message ? rebaselineCheckErr.message : String(rebaselineCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else {
+        // WIRING, NOT HELP TEXT: tests/discovery-artifacts.test.cjs derives each
+        // subcommand spelling by regexing `<namespace>_<subcommand>_failed` out of
+        // the engine's exported exit identity, splits this string on commas and
+        // asserts membership. A spelling missing here is a command the engine
+        // claims to be and the router does not dispatch.
+        error('Unknown discovery subcommand. Available: rollup, input-check, research-check, screen-check, element-sweep, rebaseline-check', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+      }
+      break;
+    }
+
     case 'effort': {
       const subcommand = args[1];
       if (subcommand === 'sync') {
@@ -2519,4 +2669,4 @@ if (require.main === module) {
 // ─── Exports (for tests) ──────────────────────────────────────────────────────
 // ADR-959: export dispatchCapabilityCommand so tests can exercise it with
 // synthetic registry + requireModule injections.
-module.exports = { dispatchCapabilityCommand };
+module.exports = { dispatchCapabilityCommand, createReadlinePrompter };

package/pp-core/bin/shared/config-defaults.manifest.json

@@ -93,5 +93,12 @@
   "plan_review": {
     "source_grounding": true,
     "source_grounding_authority": "grep"
+  },
+  "size_budget": {
+    "per_file_bytes": 1024,
+    "per_commit_bytes": 4096
+  },
+  "phase": {
+    "tier": "standard"
   }
 }

package/pp-core/bin/shared/config-schema.manifest.json

@@ -31,6 +31,9 @@
     "workflow.plan_bounce",
     "workflow.plan_bounce_script",
     "workflow.plan_bounce_passes",
+    "size_budget.per_file_bytes",
+    "size_budget.per_commit_bytes",
+    "phase.tier",
     "workflow.plan_chunked",
     "workflow.plan_review_convergence",
     "code_quality.fallow.enabled",