@pareto4/pp-core 1.18.0 → 1.19.0

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

@@ -38,6 +38,7 @@ Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `has_plans`,
 
 Then load phase details and list plans/summaries:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 pp_run query roadmap.get-phase "${phase_number}"
 grep -E "^| ${phase_number}" .planning/REQUIREMENTS.md 2>/dev/null || true
 ls "$phase_dir"/*-SUMMARY.md "$phase_dir"/*-PLAN.md 2>/dev/null || true
@@ -57,6 +58,7 @@ Extract **phase goal** from ROADMAP.md (the outcome to verify, not tasks), **req
 Use `pp-tools.cjs query` verify handlers (or legacy pp-tools) to extract must_haves from each PLAN:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 for plan in "$PHASE_DIR"/*-PLAN.md; do
   MUST_HAVES=$(pp_run query frontmatter.get "$plan" --field must_haves)
   echo "=== $plan ===" && echo "$MUST_HAVES"
@@ -124,6 +126,7 @@ For each truth: identify supporting artifacts → check artifact status → chec
 Use `pp-tools.cjs query verify.artifacts` (or legacy pp-tools) for artifact verification against must_haves in each PLAN:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 for plan in "$PHASE_DIR"/*-PLAN.md; do
   ARTIFACT_RESULT=$(pp_run query verify.artifacts "$plan")
   echo "=== $plan ===" && echo "$ARTIFACT_RESULT"
@@ -167,6 +170,7 @@ wiring or leftover code from plan revisions.
 Use `pp-tools.cjs query verify.key-links` (or legacy pp-tools) for key link verification against must_haves in each PLAN:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 for plan in "$PHASE_DIR"/*-PLAN.md; do
   LINKS_RESULT=$(pp_run query verify.key-links "$plan")
   echo "=== $plan ===" && echo "$LINKS_RESULT"
@@ -223,6 +227,7 @@ phase.
 no `<decisions>` block.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 GATE_CFG=$(pp_run query config-get workflow.context_coverage_gate 2>/dev/null || echo "true")
 if [ "$GATE_CFG" != "false" ]; then
   # Discover the phase CONTEXT.md via glob expansion rather than `ls | head`

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

@@ -38,6 +38,7 @@ If $ARGUMENTS contains a phase number, load context:
 
 ```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
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 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)
@@ -51,6 +52,7 @@ AGENT_SKILLS_CHECKER=$(pp_run query agent-skills pp-plan-checker)
 Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`, `uat_path`.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # MVP mode detection via the centralized phase.mvp-mode resolver.
 # verify-work has no --mvp CLI flag (mode is inherited from the planned phase),
 # so we omit --cli-flag — the verb falls through roadmap → config → false.
@@ -111,6 +113,7 @@ Continue to `create_uat_file`.
 Before UAT, check UI capability activation and whether Playwright/Puppeteer MCP tools are available.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 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)
 ```
@@ -148,6 +151,7 @@ UI checkpoints: {N} auto-verified, {M} queued for manual review
 Use `phase_dir` from init (or run init if not already done).
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls "$phase_dir"/*-SUMMARY.md 2>/dev/null || true
 ```
 
@@ -167,6 +171,7 @@ When `MVP_MODE=false` (mode is null, absent, or the phase has no `**Mode:**` lin
 **User-story format guard.** When `MVP_MODE=true`, also verify the phase's goal is in User Story format via the centralized validator:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PHASE_GOAL=$(pp_run query roadmap.get-phase "${phase_number}" ${GSD_WS} --pick goal)
 USER_STORY_VALID=$(pp_run query user-story.validate --story "$PHASE_GOAL" --pick valid)
 if [ "$USER_STORY_VALID" != "true" ]; then
@@ -434,7 +439,7 @@ Clear Current Test section:
 
 Commit the UAT file:
 ```bash
-pp_run query commit "test({phase_num}): complete UAT - {passed} passed, {issues} issues" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
+pp_run query commit "docs(planning): complete UAT - {passed} passed, {issues} issues" --phase "{phase_num}" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
 ```
 
 Present summary:
@@ -458,6 +463,7 @@ Present summary:
 **If issues == 0:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 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)
@@ -478,6 +484,7 @@ Skill(skill="pp-${ref.skill}", args="{phase}")
 After the skill returns, refresh `SECURITY_FILE`:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
 ```
 

package/scripts/prompt-injection-scan.sh

@@ -84,7 +84,7 @@ PATTERNS=(
 ALLOWLIST=(
   'scripts/prompt-injection-scan.sh::the PATTERNS array above is the literal source of every phrase this scanner looks for, so the file matches itself by construction; measured 4 pattern hits at HEAD on 2026-09-19'
   'scripts/base64-scan.sh::decodes base64 blobs and re-scans the recovered plaintext against the same injection vocabulary, so it names those phrases inline; measured 2 pattern hits at HEAD on 2026-09-19'
-  'scripts/secret-scan.sh::third of the three diff-mode scan scripts CI runs together in the security_scan job of .github/workflows/ci.yml; measured 0 pattern hits at HEAD on 2026-09-19, retained because its own exemption list at line 223 already names security-prompt-injection.security.test.cjs and grows with that vocabulary'
+  'scripts/secret-scan.sh::third of the three diff-mode scan scripts CI runs together in the pr_gates job of .github/workflows/ci.yml; measured 0 pattern hits at HEAD on 2026-09-19, retained because its own exemption list at line 223 already names security-prompt-injection.security.test.cjs and grows with that vocabulary'
   'tests/security-scan.security.test.cjs::the behavioural suite for this very scanner, so every positive case embeds a real injection phrase as fixture input; measured 28 pattern hits at HEAD on 2026-09-19'
   'tests/security.test.cjs::the adversarial suite for the library sanitisers, whose fixtures are real override and role-manipulation strings asserted to be neutralised; measured 54 pattern hits at HEAD on 2026-09-19'
   'tests/prompt-injection-scan.security.test.cjs::drives scanForInjection in the compiled security library with crafted payloads, and carries a second allowlist of its own for that separate scanner; measured 11 pattern hits at HEAD on 2026-09-19'

package/scripts/sync-runtime-launcher.cjs

@@ -12,6 +12,13 @@
  *      (document order) that contains a pp_run call. All other bash blocks
  *      keep their pp_run calls with NO preamble. (Define once per file,
  *      use across blocks — original footprint.)
+ *   4. Start every bash/sh/shell/zsh block that zsh would run differently
+ *      from bash with ZSH_GUARD (right after the preamble where the block
+ *      carries one), and drop the guard from a block that no longer needs it.
+ *      Each block may run in its own shell, and an agent's shell is often zsh:
+ *      the guard makes zsh read the block as sh (unmatched globs stay literal,
+ *      `====` is a word, unquoted words split, arrays index from 0) and is a
+ *      no-op under bash. See needsZshGuard for what counts.
  *
  * Run: node scripts/sync-runtime-launcher.cjs
  */
@@ -28,6 +35,57 @@ const SNIPPET_FILE = path.join(WORKFLOWS_DIR, '_runtime-launcher.snippet.sh');
  */
 const LAUNCHER_HEAD = '_PP_SHIM_NAME="pp-tools.cjs"; ';
 
+/**
+ * The first line of every shell block (issue #12 items 2-4). Exits 0 under
+ * bash, so a block's status never depends on it.
+ */
+const ZSH_GUARD = '[ -z "${ZSH_VERSION:-}" ] || emulate -R sh';
+const GUARDED_LANGS = Object.freeze(['bash', 'sh', 'shell', 'zsh']);
+
+/**
+ * True when zsh would run `lines` differently from bash: an unquoted glob
+ * character, a word starting with `=` plus more (`====`, `==`), an unquoted
+ * `$var` (zsh does not split it), or array syntax (zsh indexes from 1). Errs
+ * towards true — a needless guard costs a line, a missing one breaks a run.
+ * The launcher preamble is zsh-safe and is never inspected.
+ */
+function needsZshGuard(lines) {
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line === '' || line.startsWith('#') || isLauncherLine(line) || line === ZSH_GUARD) continue;
+    if (/\$\{#?\w+\[/.test(line) || /\b\w+\+?=\(/.test(line)) return true;
+    // Neither shell globs, splits or `=`-expands inside `[[ … ]]` (syntax, not
+    // a command), in a case pattern (`*)`), or on an assignment's right side.
+    const bare = line
+      .replace(/'[^']*'/g, "''")
+      .replace(/"(?:\\.|[^"\\])*"/g, '""')
+      .replace(/\[\[\s.*?\s\]\]/g, '[[ ]]')
+      .replace(/(^|[\s;(|])\*\)/g, '$1)')
+      .replace(/(^|[\s;&|])([A-Za-z_]\w*)=\$(?=[{\w])/g, '$1$2=');
+    if (/(^|[\s;|&(])=[^\s]/.test(bare)) return true;
+    if (/\$(\w|\{)/.test(bare)) return true;
+    if (/[*?]/.test(bare.replace(/\$[*?#@!$-]/g, ''))) return true;
+    if (/[^\s\[]\[[^\]\s]*\]/.test(bare)) return true;
+  }
+  return false;
+}
+
+/**
+ * Make `lines` carry ZSH_GUARD exactly when needsZshGuard says so: at the top
+ * (after leading blanks, and after the preamble when the block starts with
+ * it), indented like the fence. Idempotent.
+ */
+function insertZshGuard(lines, preamble, indent) {
+  const rest = lines.filter((l) => l.trim() !== ZSH_GUARD);
+  if (!needsZshGuard(rest)) return rest.length === lines.length ? lines : rest;
+  let at = 0;
+  while (at < rest.length && rest[at].trim() === '') at++;
+  if (at === rest.length) return lines;
+  if (preamble.length > 0 && preamble.every((p, k) => rest[at + k] === p)) at += preamble.length;
+  const out = [...rest.slice(0, at), indent + ZSH_GUARD, ...rest.slice(at)];
+  return out.join('\n') === lines.join('\n') ? lines : out;
+}
+
 /**
  * Launcher carriers that live OUTSIDE this script's two roots
  * (pp-core/workflows/ and agents/).
@@ -387,7 +445,7 @@ function transformFile(content, preamble) {
     if (i < allLines.length) i++;
 
     if (isShellBlock) {
-      shellBlockRanges.push({ openLineIdx, contentStart, contentEnd, closingLineIdx });
+      shellBlockRanges.push({ openLineIdx, contentStart, contentEnd, closingLineIdx, lang, indent });
     }
   }
 
@@ -418,10 +476,9 @@ function transformFile(content, preamble) {
 
   // Insert preamble into the first pp_run block only
   const finalBlocks = strippedBlocks.map((stripped, bi) => {
-    if (bi === firstPpRunBlockIdx) {
-      return insertPreamble(stripped, preamble);
-    }
-    return stripped;
+    const withPreamble = bi === firstPpRunBlockIdx ? insertPreamble(stripped, preamble) : stripped;
+    const range = shellBlockRanges[bi];
+    return GUARDED_LANGS.includes(range.lang) ? insertZshGuard(withPreamble, preamble, range.indent) : withPreamble;
   });
 
   // --- Pass 3: splice back into output (reverse order to preserve indices) ---
@@ -443,6 +500,43 @@ function transformFile(content, preamble) {
   return outputLines.join('\n');
 }
 
+/**
+ * Guard-only pass for the roots whose launcher lines are kept in place
+ * (commands/, pp-core/references/): every non-empty bash/sh/shell/zsh block
+ * gets ZSH_GUARD, after a launcher line that opens it. pp-core/templates/ is
+ * never passed here — its blocks are text written into the user's project.
+ * Returns new content, or null when nothing changes.
+ */
+function guardOnlyTransform(content) {
+  const lines = content.split('\n');
+  const out = [];
+  let changed = false;
+  let i = 0;
+  while (i < lines.length) {
+    const open = lines[i].match(/^(\s*)```(\w+)?\s*$/);
+    out.push(lines[i]);
+    i++;
+    if (!open) continue;
+    const indent = open[1];
+    const lang = (open[2] || '').toLowerCase();
+    const closing = new RegExp('^' + escapeRegExp(indent) + '```\\s*$');
+    const body = [];
+    while (i < lines.length && !closing.test(lines[i])) body.push(lines[i++]);
+    let next = body;
+    if (GUARDED_LANGS.includes(lang)) {
+      const first = body.find((l) => l.trim() !== '');
+      next = insertZshGuard(body, first !== undefined && isLauncherLine(first) ? [first] : [], indent);
+      if (next !== body) changed = true;
+    }
+    out.push(...next);
+    if (i < lines.length) out.push(lines[i++]);
+  }
+  return changed ? out.join('\n') : null;
+}
+
+/** The roots that get only the guard pass. */
+const GUARD_ONLY_DIRS = Object.freeze(['commands', path.join('pp-core', 'references')]);
+
 function escapeRegExp(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -511,6 +605,18 @@ function main() {
     }
   }
 
+  for (const dir of GUARD_ONLY_DIRS) {
+    for (const f of collectFiles(path.join(repoRoot, dir))) {
+      const content = fs.readFileSync(f, 'utf8');
+      const result = guardOnlyTransform(content);
+      if (result !== null) {
+        fs.writeFileSync(f, result, 'utf8');
+        transformedCount++;
+        console.log(`transformed (guard): ${path.relative(repoRoot, f)}`);
+      }
+    }
+  }
+
   console.log(`\nDone. ${transformedCount} files transformed, ${unchangedCount} unchanged.`);
 }
 
@@ -523,6 +629,10 @@ module.exports = {
   replaceCanonicalLines,
   EXTRA_CARRIERS,
   LAUNCHER_HEAD,
+  ZSH_GUARD,
+  needsZshGuard,
+  guardOnlyTransform,
+  GUARD_ONLY_DIRS,
 };
 
 if (require.main === module) {