@pareto4/pp-core 1.7.1 → 1.8.1

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

@@ -23,6 +23,10 @@ exports.CLUSTERS = Object.freeze({
         'init',
         'new-project',
         'discovery',
+        // Discovery→build handoff: canonical + retained alias, grouped with the
+        // other project-lifecycle entrypoints (routed via pp-ns-project).
+        'discovery-to-build',
+        'build-handoff',
         'discuss-phase',
         'plan-phase',
         'execute-phase',

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

@@ -240,7 +240,7 @@ function intelUpdate(planningDir) {
         return disabledResponse();
     return {
         action: 'spawn_agent',
-        message: 'Run pp-tools intel update or spawn gsd-intel-updater agent for full refresh',
+        message: 'Run pp-tools intel update or spawn pp-intel-updater agent for full refresh',
     };
 }
 /**

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

@@ -210,6 +210,119 @@ function error(message, reason = ERROR_REASON.UNKNOWN) {
     }
     process.exit(1);
 }
+// ─── Pareto visual brand: banner engine (Phase 17 / UIBR-01, UIBR-02) ─────────
+//
+// A hand-rolled ANSI banner emitter (no color library — CLAUDE.md constraint).
+// The pure/impure split (formatBanner vs banner) lets the whole degrade ladder
+// be asserted by injecting `level`, with no PTY. Branding is routed to fd 2
+// (stderr) ONLY; output() (fd 1) is left byte-for-byte unchanged, so machine-
+// readable payloads physically cannot carry branding bytes (UIBR-02, D-03).
+/**
+ * Pareto Blue — the single signal color for the banner rule (D-01). Every
+ * banner rule renders in this hue at every color tier; only the per-phase Crew
+ * glyph carries the phase accent. #2251FF.
+ */
+const PARETO_BLUE = [34, 81, 255];
+/**
+ * Frozen phase→Crew-identity map (mirrors the ERROR_REASON frozen-object idiom
+ * at ~163). Keyed by the six Crew phases; each entry carries the locked glyph
+ * (D-01) and its accent at three color tiers. Accent hexes are verbatim from
+ * pareto-skills/pp-brand/SKILL.md Crew Accent Palette (D-02).
+ */
+const CREW = Object.freeze({
+    discovery: { glyph: '◎', ascii: '(o)', rgb: [246, 180, 55], c256: 221, c16: '33' }, // Amber       #F6B437
+    plan: { glyph: '◆', ascii: '<>', rgb: [20, 111, 244], c256: 33, c16: '34' }, // Steel       #146FF4
+    build: { glyph: '⬢', ascii: '#', rgb: [34, 81, 255], c256: 27, c16: '34' }, // Pareto Blue #2251FF
+    validate: { glyph: '◈', ascii: '<*>', rgb: [62, 207, 142], c256: 42, c16: '32' }, // Mint        #3ECF8E
+    deploy: { glyph: '▲', ascii: '^', rgb: [255, 107, 74], c256: 209, c16: '31' }, // Coral       #FF6B4A
+    run: { glyph: '▶', ascii: '>', rgb: [168, 132, 255], c256: 141, c16: '35' }, // Violet      #A884FF
+});
+/**
+ * Wrap `text` in the SGR foreground escape for the given color `level`, always
+ * reset-terminated. level>=3 → 24-bit truecolor; 2 → 256-color; 1 → 16-color;
+ * 0 → plain text, no escapes at all (D-04 ladder bottom).
+ */
+function paint(text, rgb, level, c256, c16) {
+    const [r, g, b] = rgb;
+    if (level >= 3)
+        return `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`;
+    if (level === 2)
+        return `\x1b[38;5;${c256}m${text}\x1b[0m`;
+    if (level === 1)
+        return `\x1b[${c16}m${text}\x1b[0m`;
+    return text;
+}
+/**
+ * Detect the terminal color capability of `stream` (default: process.stderr,
+ * since banners target fd 2). Returns 0 = none, 1 = 16-color, 2 = 256-color,
+ * 3 = truecolor. Gates on COLOR CAPABILITY only — never on the runtime — so the
+ * brand renders on any color-capable TTY and degrades cleanly on no-color /
+ * non-TTY environments (D-04). Honors NO_COLOR (no-color.org) and FORCE_COLOR.
+ */
+function colorLevel(stream = process.stderr) {
+    const env = process.env;
+    // 1. NO_COLOR present-and-nonempty disables color (no-color.org).
+    if (env.NO_COLOR != null && env.NO_COLOR !== '')
+        return 0;
+    // 2. FORCE_COLOR override (force a specific tier, e.g. on a pipe in tests).
+    const fc = env.FORCE_COLOR;
+    if (fc === '0' || fc === 'false')
+        return 0;
+    if (fc === '1' || fc === 'true')
+        return 1;
+    if (fc === '2')
+        return 2;
+    if (fc === '3')
+        return 3;
+    // 3. Not a TTY → plain (piped, redirected, tool-harness capture).
+    if (!stream || !stream.isTTY)
+        return 0;
+    // 4. Truecolor advertised.
+    if (env.COLORTERM === 'truecolor' || env.COLORTERM === '24bit')
+        return 3;
+    // 5. 256-color terminals.
+    const term = env.TERM || '';
+    if (/-256(color)?$/.test(term))
+        return 2;
+    if (term === 'dumb')
+        return 0;
+    // 6. Known ANSI terminal families → 16-color floor; unknown TTY → safe 16.
+    if (/xterm|screen|vt100|vt220|rxvt|color|ansi|cygwin|linux|tmux/i.test(term))
+        return 1;
+    return 1;
+}
+/**
+ * PURE: build the three-line brand banner for `phaseKey` at color `level`. No
+ * I/O and no env reads — `level` is injected so every ladder tier is unit-
+ * testable without a PTY. The rule always renders in Pareto Blue (the D-01
+ * signal color); only the glyph carries the phase accent. At level 0 the rule
+ * is plain ASCII and the glyph is kept as a plain char — zero escapes (D-04).
+ *
+ * `stageText` is treated as an opaque literal: it is interpolated verbatim and
+ * never parsed, so embedded \x1b sequences are never re-interpreted into new
+ * SGR state (V5 / T-17-01 ANSI-injection mitigation).
+ */
+function formatBanner(phaseKey, stageText, level) {
+    const RULE = '━'.repeat(51);
+    const crew = CREW[phaseKey] ?? CREW.build;
+    if (level === 0) {
+        return `${RULE}\n ${crew.glyph} pp-core ► ${stageText}\n${RULE}\n`;
+    }
+    const rule = paint(RULE, PARETO_BLUE, level, 27, '34');
+    const glyph = paint(crew.glyph, crew.rgb, level, crew.c256, crew.c16);
+    return `${rule}\n ${glyph} pp-core ► ${stageText}\n${rule}\n`;
+}
+/**
+ * IMPURE: render the banner for `phaseKey`/`stageText` and write it to fd 2
+ * (stderr) via the back-pressure-safe writeAllSync. The color level is detected
+ * from opts.stream (default process.stderr) unless opts.forceLevel is given.
+ * NEVER touches output()/stdout — fd separation is the structural UIBR-02
+ * guarantee (D-03, T-17-02).
+ */
+function banner(phaseKey, stageText, opts = {}) {
+    const level = opts.forceLevel ?? colorLevel(opts.stream ?? process.stderr);
+    writeAllSync(2, formatBanner(phaseKey, stageText, level));
+}
 module.exports = {
     GSD_TEMP_DIR,
     ensureGsdTempDir,
@@ -219,4 +332,11 @@ module.exports = {
     setJsonErrorMode,
     getJsonErrorMode,
     error,
+    // Pareto visual brand banner engine (Phase 17 / UIBR-01, UIBR-02)
+    PARETO_BLUE,
+    CREW,
+    paint,
+    colorLevel,
+    formatBanner,
+    banner,
 };

package/pp-core/bin/lib/profile-pipeline-command-router.cjs

@@ -44,7 +44,7 @@ function routeExtractMessages({ args, cwd, raw, error, _pipeline }) {
   // args[0] = 'extract-messages' (family name), args[1] = project positional
   const projectArg = args[1];
   if (!projectArg || projectArg.startsWith('--')) {
-    error('Usage: gsd-tools extract-messages <project> [--session <id>] [--limit N] [--path <dir>]\nRun scan-sessions first to see available projects.', ERROR_REASON.USAGE);
+    error('Usage: pp-tools extract-messages <project> [--session <id>] [--limit N] [--path <dir>]\nRun scan-sessions first to see available projects.', ERROR_REASON.USAGE);
     return;
   }
   // cmdExtractMessages is async — do NOT return the Promise.

package/pp-core/bin/lib/roadmap-parser.cjs

@@ -344,7 +344,7 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
         const hasVersionedMilestonesGlobal = /^#{1,3}\s+.*v\d+\.\d+/mi.test(roadmapContent);
         const hasPhaseHeadings = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+[\w]/i.test(roadmapContent);
         if (!hasVersionedMilestonesGlobal && hasPhaseHeadings && phaseIdConvention === 'milestone-prefixed') {
-            console.warn('[gsd] Deprecated: free-form ROADMAP.md detected (no versioned milestone headings). ' +
+            console.warn('[pp-core] Deprecated: free-form ROADMAP.md detected (no versioned milestone headings). ' +
                 'The project has phase_id_convention set to "milestone-prefixed" in config.json but the ' +
                 'ROADMAP does not use versioned milestone headings. Run `pp-tools roadmap upgrade --convention milestone-prefixed` to migrate (dry-run by default).');
         }

package/pp-core/bin/lib/runtime-artifact-conversion.cjs

@@ -427,8 +427,8 @@ function convertClaudeCommandToKimiSkill(content, skillName, _runtime = null, cm
     const kimiSkillName = normalizeKimiSkillName(skillName);
     const names = cmdNames || readGsdCommandNames();
     const description = frontmatter
-        ? extractFrontmatterField(frontmatter, 'description') || `Run GSD workflow ${kimiSkillName}.`
-        : `Run GSD workflow ${kimiSkillName}.`;
+        ? extractFrontmatterField(frontmatter, 'description') || `Run pp-core workflow ${kimiSkillName}.`
+        : `Run pp-core workflow ${kimiSkillName}.`;
     const normalizedBody = convertGsdCommandReferencesToKimiSkillInvocations(frontmatter ? body : content, names);
     return `---\nname: ${kimiSkillName}\ndescription: ${yamlQuote(toSingleLine(description))}\n---\nInvoke this pp-core skill with \`/skill:${kimiSkillName}\`.\n\n${normalizedBody}`;
 }

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

@@ -348,7 +348,7 @@ function pruneSkillDirs(skillsDir, retainedNames, prefix, manifest) {
             // The dir must also be in the manifest to be considered GSD-owned.
             // A user-created gsd-* dir that isn't in the manifest is preserved with a warning.
             if (!canonicalStems.has(entry.slice(prefix.length))) {
-                process.stderr.write(`[gsd] Warning: ${entry} matches GSD prefix '${prefix}' but is not in the manifest — preserving (user-owned or unknown)\n`);
+                process.stderr.write(`[pp-core] Warning: ${entry} matches GSD prefix '${prefix}' but is not in the manifest — preserving (user-owned or unknown)\n`);
                 continue;
             }
             isGsdOwned = true;

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

@@ -920,13 +920,13 @@ function cmdWorktreeReapOrphans(cwd) {
     }
     catch (err) {
         // Surface failure as a one-line warning; keep exit-zero so workflows don't break.
-        process.stderr.write(`[gsd] worktree.reap-orphans failed: ${err && err.message ? err.message : String(err)}\n`);
+        process.stderr.write(`[pp-core] worktree.reap-orphans failed: ${err && err.message ? err.message : String(err)}\n`);
         result = [];
     }
     const skippedCount = result.filter((r) => r.status === 'skipped').length;
     if (skippedCount > 0) {
         // Surface skipped entries so operators are aware of unresolved orphans.
-        process.stderr.write(`[gsd] worktree.reap-orphans: ${skippedCount} orphan(s) skipped (run with DEBUG=1 for details)\n`);
+        process.stderr.write(`[pp-core] worktree.reap-orphans: ${skippedCount} orphan(s) skipped (run with DEBUG=1 for details)\n`);
     }
     process.stdout.write(`${JSON.stringify({ ok: true, reaped: result.filter((r) => r.status === 'reaped').length, entries: result }, null, 2)}\n`);
 }

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

@@ -709,6 +709,29 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       break;
     }
 
+    case 'banner': {
+      // Pareto brand banner (Phase 17 / UIBR-02). Workflows shell out via
+      // `pp_run banner <phaseKey> "<STAGE TEXT>"`. The banner reaches the
+      // terminal ONLY via io.banner → fd 2 (stderr); output()/stdout is never
+      // touched, so machine-readable payloads physically cannot carry branding
+      // bytes (D-03, T-17-02). The `--raw` flag is already stripped upstream and
+      // is irrelevant here — stdout stays clean regardless.
+      const phaseKey = args[1];
+      const stageText = args[2] ?? '';
+      if (!phaseKey || !Object.prototype.hasOwnProperty.call(io.CREW, phaseKey)) {
+        // Unknown key → fail loud, never render a partial/garbage banner
+        // (T-17-03, ASVS V5). io.error writes to fd 2 and exits non-zero.
+        error(
+          `banner: unknown phase key "${phaseKey ?? ''}" — expected one of: ${Object.keys(io.CREW).join(', ')}`,
+          ERROR_REASON.SDK_MISSING_ARG,
+        );
+      }
+      // stageText is passed as an opaque literal — no re-interpretation of
+      // embedded escapes (V5 / T-17-01 ANSI-injection mitigation).
+      io.banner(phaseKey, stageText);
+      break;
+    }
+
     case 'generate-client-context': {
       // generate-client-context --from-json <path> [--output <path>] [--force]
       // generate-client-context --read [--output <path>]

package/pp-core/references/ui-brand.md

@@ -4,24 +4,86 @@ Visual patterns for user-facing pp-core output. Orchestrators @-reference this f
 
 ## Stage Banners
 
-Use for major workflow transitions.
+Use for major workflow transitions. The banner is a three-line block: a rule, a
+title line ` {glyph} pp-core ► {STAGE NAME}`, and a closing rule.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- pp-core ► {STAGE NAME}
+ {glyph} pp-core ► {STAGE NAME}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+**Color rule (D-01):** the two rules are **ALWAYS Pareto Blue `#2251FF`** — the
+single signal color. Only the **glyph** carries the phase accent (the per-phase
+Crew color below). The rule hue never changes with the phase; this keeps the
+brand's one signal color constant while the glyph communicates which Crew phase
+is active.
+
+### Phase → glyph → accent-hex mapping (D-02)
+
+Each major transition belongs to one of the six Pareto Crew phases. The glyph and
+its accent color are fixed per phase (all glyphs are BMP for wide font coverage):
+
+| Crew phase | phaseKey | Glyph | Codepoint | Accent | Hex | RGB | ASCII fallback | Stage banners |
+|-----------|----------|:-----:|-----------|--------|-----|-----|:--------------:|---------------|
+| Discovery | `discovery` | ◎ | U+25CE BULLSEYE | Amber | `#F6B437` | 246,180,55 | `(o)` | QUESTIONING · RESEARCHING · DEFINING REQUIREMENTS · CREATING ROADMAP |
+| Plan | `plan` | ◆ | U+25C6 BLACK DIAMOND | Steel | `#146FF4` | 20,111,244 | `<>` | PLANNING PHASE {N} · PATTERN MAPPING |
+| Build | `build` | ⬢ | U+2B22 BLACK HEXAGON | Pareto Blue | `#2251FF` | 34,81,255 | `#` | EXECUTING WAVE {N} |
+| Validate | `validate` | ◈ | U+25C8 WHITE DIAMOND CONTAINING BLACK SMALL DIAMOND | Mint | `#3ECF8E` | 62,207,142 | `<*>` | VERIFYING · PHASE {N} COMPLETE ✓ |
+| Deploy | `deploy` | ▲ | U+25B2 BLACK UP-POINTING TRIANGLE | Coral | `#FF6B4A` | 255,107,74 | `^` | ship · PR BRANCH · MILESTONE COMPLETE 🎉 |
+| Run | `run` | ▶ | U+25B6 BLACK RIGHT-POINTING TRIANGLE | Violet | `#A884FF` | 168,132,255 | `>` | autonomous · progress · resume |
+
+Build's accent equals Pareto Blue by design, so at the Build transition the glyph
+and rule share a hue.
+
 **Stage names (uppercase):**
-- `QUESTIONING`
-- `RESEARCHING`
-- `DEFINING REQUIREMENTS`
-- `CREATING ROADMAP`
-- `PLANNING PHASE {N}`
-- `EXECUTING WAVE {N}`
-- `VERIFYING`
-- `PHASE {N} COMPLETE ✓`
-- `MILESTONE COMPLETE 🎉`
+- `QUESTIONING` (Discovery ◎)
+- `RESEARCHING` (Discovery ◎)
+- `DEFINING REQUIREMENTS` (Discovery ◎)
+- `CREATING ROADMAP` (Discovery ◎)
+- `PLANNING PHASE {N}` (Plan ◆)
+- `PATTERN MAPPING PHASE {N}` (Plan ◆)
+- `EXECUTING WAVE {N}` (Build ⬢)
+- `VERIFYING` (Validate ◈)
+- `PHASE {N} COMPLETE ✓` (Validate ◈)
+- `PR BRANCH` (Deploy ▲)
+- `MILESTONE COMPLETE 🎉` (Deploy ▲)
+
+### How banners are emitted (the shell-out call)
+
+Banners are **not** printed as LLM prose. Workflows emit them via the CLI, which
+writes the rendered banner to **stderr (fd 2)** and auto-degrades on non-TTY:
+
+```bash
+pp_run banner <phaseKey> "<STAGE TEXT>"
+```
+
+For example, at the research transition a workflow runs
+`pp_run banner discovery "RESEARCHING PHASE {X}"`; at wave start it runs
+`pp_run banner build "EXECUTING WAVE {N}"`. The `<phaseKey>` is the Crew key from
+the table above; the stage text is passed as an opaque literal.
+
+**Degrade ladder (D-04):** the emitter gates on **color capability, not runtime**.
+It detects the terminal level from fd 2 and steps down cleanly:
+
+- **truecolor (level 3):** 24-bit `\x1b[38;2;R;G;Bm` — full accent hex.
+- **256-color (level 2):** nearest xterm-256 index for rule and glyph.
+- **16-color (level 1):** basic ANSI SGR for rule and glyph.
+- **none (level 0):** plain ASCII — no escapes at all; the glyph is kept as a
+  plain character (or its ASCII fallback where a terminal can't render it).
+
+Because level 0 is exactly the non-TTY / piped / no-color case, branding
+auto-degrades in precisely the environments where ANSI wouldn't render anyway,
+and `NO_COLOR` / `FORCE_COLOR` are honored.
+
+**Double-print rule (Pitfall 4):** the inline ASCII block shown above is the
+**documented visual spec only**. A workflow that adopts the `pp_run banner` call
+MUST drop its own inline `━━━ / pp-core ► {STAGE} / ━━━` block at that transition —
+otherwise the banner prints twice. Keep the inline block here in `ui-brand.md`;
+remove it from the adopting workflow.
+
+The `✓` / `🎉` status symbols below remain additive to the stage text (e.g.
+`PHASE {N} COMPLETE ✓`).
 
 ---
 

package/pp-core/templates/codebase/structure.md

@@ -145,10 +145,10 @@ pp-core/
 - Key files: install.js - handles npx installation
 - Subdirectories: None
 
-**commands/gsd/**
-- Purpose: Slash command definitions for Claude Code
-- Contains: *.md files (one per command)
-- Key files: new-project.md, plan-phase.md, execute-plan.md
+**commands/**
+- Purpose: Slash command definitions for Claude Code (pp-* flat-hyphen layout)
+- Contains: pp-*.md files (one per command)
+- Key files: pp-new-project.md, pp-plan-phase.md, pp-execute-phase.md
 - Subdirectories: None (flat structure)
 
 **pp-core/references/**
@@ -206,7 +206,7 @@ pp-core/
 ## Where to Add New Code
 
 **New Slash Command:**
-- Primary code: `commands/gsd/{command-name}.md`
+- Primary code: `commands/pp-{command-name}.md`
 - Tests: `tests/commands/{command-name}.test.js` (if testing implemented)
 - Documentation: Update `README.md` with new command
 

package/pp-core/templates/spec.md

@@ -232,7 +232,7 @@ The database has a `posts` table and `follows` table. No feed query or feed UI e
 
 ## Goal
 
-A `gsd backup` CLI command creates a reproducible database snapshot that can be restored by `gsd restore` (a separate phase).
+A `myapp backup` CLI command creates a reproducible database snapshot that can be restored by `myapp restore` (a separate phase).
 
 ## Background
 
@@ -242,8 +242,8 @@ No backup tooling exists. The project uses PostgreSQL. Developers currently use
 
 1. **Backup creation**: CLI command executes a full database backup.
    - Current: No `backup` subcommand exists in the CLI
-   - Target: `gsd backup` connects to the database (via `DATABASE_URL` env or `--db` flag), runs pg_dump, writes output to `./backups/YYYY-MM-DD_HH-MM-SS.dump`
-   - Acceptance: Running `gsd backup` on a test database creates a `.dump` file; running `pg_restore` on that file recreates the database without error
+   - Target: `myapp backup` connects to the database (via `DATABASE_URL` env or `--db` flag), runs pg_dump, writes output to `./backups/YYYY-MM-DD_HH-MM-SS.dump`
+   - Acceptance: Running `myapp backup` on a test database creates a `.dump` file; running `pg_restore` on that file recreates the database without error
 
 2. **Network retry**: Transient network failures are retried automatically.
    - Current: pg_dump fails immediately on network error
@@ -258,13 +258,13 @@ No backup tooling exists. The project uses PostgreSQL. Developers currently use
 ## Boundaries
 
 **In scope:**
-- `gsd backup` subcommand (full dump only)
+- `myapp backup` subcommand (full dump only)
 - Output to `./backups/` directory (created if missing)
 - Network retry (3 attempts)
 - Partial file cleanup on failure
 
 **Out of scope:**
-- `gsd restore` — that is Phase 3
+- `myapp restore` — that is Phase 3
 - Incremental backups — separate backlog item (full dump only for now)
 - S3 or remote storage — separate backlog item
 - Encryption — separate backlog item
@@ -277,8 +277,8 @@ No backup tooling exists. The project uses PostgreSQL. Developers currently use
 
 ## Acceptance Criteria
 
-- [ ] `gsd backup` creates a `.dump` file in `./backups/YYYY-MM-DD_HH-MM-SS.dump` format
-- [ ] `gsd backup` uses `DATABASE_URL` env var or `--db` flag for connection
+- [ ] `myapp backup` creates a `.dump` file in `./backups/YYYY-MM-DD_HH-MM-SS.dump` format
+- [ ] `myapp backup` uses `DATABASE_URL` env var or `--db` flag for connection
 - [ ] 3 retries on network failure, then exit code 1 with stderr message
 - [ ] `--no-retry` flag skips retries and fails immediately on first error
 - [ ] No partial `.dump` file left after a failed backup

package/pp-core/workflows/add-backlog.md

@@ -1,6 +1,6 @@
 # Add Backlog Item Workflow
 
-Invoked by `/pp:capture --backlog` (`commands/gsd/capture.md`).
+Invoked by `/pp:capture --backlog` (`commands/pp-capture.md`).
 
 Adds an idea to the ROADMAP.md backlog parking lot using 999.x numbering. Backlog items
 are unsequenced ideas that aren't ready for active planning — they live outside the normal

package/pp-core/workflows/autonomous.md

@@ -342,10 +342,10 @@ Read `frontend` and `hasUiSpec` from `GATE` (in-context).
 **Otherwise (frontend phase + no UI-SPEC):** For each active step hook (the `kind == "step"` set from above, in array order):
 
 ```
-Skill(skill="gsd-${ref.skill}", args="${PHASE_NUM}")
+Skill(skill="pp-${ref.skill}", args="${PHASE_NUM}")
 ```
 
-(Prepend `gsd-` to `ref.skill` — so `ui-phase` → `pp-ui-phase`. Bare `${PHASE_NUM}` args — autonomous style, same pattern as the verify:post dispatch.) Entries where `kind == "gate"` are silently ignored — autonomous is always pipeline mode, there is no blocking gate here.
+(Prepend `pp-` to `ref.skill` — so `ui-phase` → `pp-ui-phase`. Bare `${PHASE_NUM}` args — autonomous style, same pattern as the verify:post dispatch.) Entries where `kind == "gate"` are silently ignored — autonomous is always pipeline mode, there is no blocking gate here.
 
 After all step hooks return, re-read:
 
@@ -465,7 +465,7 @@ If no active code-review step hook exists: display "Code review skipped (code-re
 For each active code-review step hook, dispatch the skill using the registry-provided stem:
 
 ```
-Skill(skill="gsd-${ref.skill}", args="${PHASE_NUM}")
+Skill(skill="pp-${ref.skill}", args="${PHASE_NUM}")
 ```
 
 Parse status from REVIEW.md frontmatter. If "clean" or "skipped": proceed to 3d. If findings found after the capability-dispatched review, auto-invoke the consolidated fix entry point:
@@ -590,7 +590,7 @@ For each entry in `activeHooks` in array order where `kind == "step"` and `ref.s
 - Invoke:
 
 ```
-Skill(skill="gsd-${ref.skill}", args="${PHASE_NUM}")
+Skill(skill="pp-${ref.skill}", args="${PHASE_NUM}")
 ```
 
 (i.e. prepend `pp-` to `ref.skill` — so `ui-review` → `pp-ui-review`.)

package/pp-core/workflows/debug.md

@@ -1,6 +1,6 @@
 # Debug Workflow
 
-Invoked by `/pp:debug` (`commands/gsd/debug.md`).
+Invoked by `/pp:debug` (`commands/pp-debug.md`).
 
 Systematic debugging using the scientific method with subagent isolation.
 Orchestrates symptom gathering, session creation, and delegation to `pp-debug-session-manager`.

package/pp-core/workflows/{build-handoff.md → discovery-to-build.md}

@@ -22,6 +22,9 @@ Valid pp-core subagent types (use exact names — do not fall back to 'general-p
 **Flags (parse from `$ARGUMENTS`):**
 - `--skip-validation` — Skip the Discovery completion check (use when sessions are intentionally incomplete)
 - `--scaffold` — After initialization, also scaffold lightweight application structure from the Session 5 tech stack
+- `--text` — Text mode: render every interactive prompt as a plain-text numbered list (for non-Claude runtimes)
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call in this workflow with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
 
 **Prerequisites:**
 - A Pareto project with a `Discovery/` folder (created by `pareto-project-setup`)
@@ -36,7 +39,6 @@ Valid pp-core subagent types (use exact names — do not fall back to 'general-p
 Resolve the `pp_run` helper before anything else. Every `pp_run` call below uses this shim.
 
 ```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 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" "$@"; }; else echo "ERROR: pp-tools.cjs not found. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi
 ```
 
 ---
@@ -95,7 +97,7 @@ AskUserQuestion([
 **If "Complete discovery first":** Exit with guidance:
 ```
 Run /pp-discovery to see progress and continue with the next session.
-When all sessions are complete, run /pp-build-handoff again.
+When all sessions are complete, run /pp-discovery-to-build again.
 ```
 
 **If "Proceed anyway":** Continue to Step 3, noting which sessions are incomplete.
@@ -326,7 +328,7 @@ AskUserQuestion([
 ```
 
 **If "Review first":** Wait for the user to review, then remind them to say "continue" or
-re-run `/pp-build-handoff` when ready.
+re-run `/pp-discovery-to-build` when ready.
 
 **If "Regenerate":** Ask what's wrong, adjust, and regenerate Step 3.
 
@@ -343,6 +345,7 @@ workflow uses.
 ### 5a. Run init
 
 ```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
 mkdir -p .planning
 INIT=$(pp_run query init.new-project 2>/dev/null)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

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

@@ -539,6 +539,14 @@ increases monotonically across waves. `{status}` is `complete` (success),
    [checkpoint] phase {PHASE_NUMBER} wave {N}/{M} starting, {wave_plan_count} plan(s), {P}/{Q} plans done
    ```
 
+   **Emit the branded Build stage banner (the marquee wave-start transition).**
+   Run this Bash command — it renders on stderr and auto-degrades on non-TTY; do
+   NOT print an inline ASCII banner alongside it:
+
+   ```bash
+   pp_run banner build "EXECUTING WAVE {N}"
+   ```
+
    Then read each plan's `<objective>`. Extract what's being built and why.
 
    ```
@@ -1184,7 +1192,7 @@ If no active code-review step hook exists: display "Code review skipped (code-re
 
 **Invoke review:**
 ```
-Skill(skill="gsd-${ref.skill}", args="${PHASE_NUMBER}")
+Skill(skill="pp-${ref.skill}", args="${PHASE_NUMBER}")
 ```
 
 **Check results using deterministic path (not glob):**

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

@@ -488,12 +488,13 @@ If user selects "Skip research": skip to step 6.
 
 **If `--auto` and `research_enabled` is false:** Skip research silently (preserves automated behavior).
 
-Display banner:
+Run this Bash command to emit the branded Discovery 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 discovery "RESEARCHING PHASE {X}"
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- pp-core ► RESEARCHING PHASE {X}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+Then announce the spawn:
+```
 ◆ Spawning researcher... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
@@ -501,7 +502,7 @@ Display banner:
 
 ```bash
 if pp_run query teams-status --active >/dev/null 2>&1; then
-  echo "⚠️  CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS detected. pp-core's multi-agent orchestration is not validated under claude-code agent-teams and may stall (a subagent's completion can fail to route to the orchestrator). Recommend disabling agent-teams for GSD workflows. See https://github.com/open-gsd/pp-core/issues/1355" >&2
+  echo "⚠️  CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS detected. pp-core's multi-agent orchestration is not validated under claude-code agent-teams and may stall (a subagent's completion can fail to route to the orchestrator). Recommend disabling agent-teams for pp-core workflows. See https://github.com/open-gsd/pp-core/issues/1355" >&2
 fi
 ```
 
@@ -634,12 +635,12 @@ Read the `activeHooks` array directly from `PLAN_PRE_HOOKS_JSON` / `HOOKS_JSON`
 **Branch 1 — all plan:pre hooks inactive (`activeHooks` is empty or absent):** Skip to step 6.
 
 **Generic step hook dispatch contract:** For each active entry where `kind == "step"`:
-- If `ref.skill` is set, dispatch with `Skill(skill="gsd-${ref.skill}", args="${PHASE} --auto ${GSD_WS}")` when pipeline mode allows auto-chaining. Prepend `gsd-` to `ref.skill` — `ui-phase` → `pp-ui-phase`.
+- If `ref.skill` is set, dispatch with `Skill(skill="pp-${ref.skill}", args="${PHASE} --auto ${GSD_WS}")` when pipeline mode allows auto-chaining. Prepend `pp-` to `ref.skill` — `ui-phase` → `pp-ui-phase`.
 - If `ref.agent` is set, dispatch with `Agent(prompt=filled_hook_fragment, subagent_type=ref.agent, model="{researcher_model}")`. Use the hook's `fragment.inline` as the prompt body and fill phase fields before spawning.
 - The `research` hook is handled by §5.1's research decision. The `pattern-mapper` hook is handled by §7.8 after `RESEARCH_PATH` is known. Future plan:pre agent hooks use the same `ref.agent` fragment contract.
 
 **AI integration capability:** If the active `ai-integration` step hook is present, `AI_SPEC_PATH` is empty, and the phase goal contains AI keywords (`agent`, `llm`, `rag`, `chatbot`, `embedding`, `langchain`, `llamaindex`, `crewai`, `langgraph`, `openai`, `anthropic`, `vector`, `eval`, `ai system`), then:
-- In pipeline / `--auto` mode, invoke the hook's `ref.skill` via `Skill(skill="gsd-${ref.skill}", args="${PHASE} --auto ${GSD_WS}")`.
+- In pipeline / `--auto` mode, invoke the hook's `ref.skill` via `Skill(skill="pp-${ref.skill}", args="${PHASE} --auto ${GSD_WS}")`.
 - In manual mode, display the existing non-blocking `/pp:ai-integration-phase {N}` recommendation and let the user continue planning without AI-SPEC or stop to run the capability workflow first.
 
 Run the UI deterministic gate whenever **any** `plan:pre` UI hook is active — including the step-only case (`workflow.ui_safety_gate` off). (`check.query` = `"ui.plan-gate"`; router normalizes dots→hyphens.)
@@ -674,7 +675,7 @@ AUTO_CHAIN=$(pp_run query check auto-mode --pick auto_chain_active 2>/dev/null |
 **Branch 5 — `AUTO_CHAIN` is `true` (pipeline / `--auto`):** Fire each active UI **step** hook — runs independently of whether a gate is active (covers `{ui_phase:true,ui_safety_gate:false}`). For each entry in `activeHooks` (in array order) where `kind == "step"` and `ref.skill` is set:
 
 ```
-Skill(skill="gsd-${ref.skill}", args="${PHASE} --auto ${GSD_WS}")
+Skill(skill="pp-${ref.skill}", args="${PHASE} --auto ${GSD_WS}")
 ```
 
 After all UI step hooks return, re-read:
@@ -827,12 +828,13 @@ Continue to step 8.
 
 ## 8. Spawn pp-planner Agent
 
-Display banner:
+Run this Bash command to emit the branded Plan 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 plan "PLANNING PHASE {X}"
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- pp-core ► PLANNING PHASE {X}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+Then announce the spawn:
+```
 ◆ Spawning planner... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 

package/pp-core/workflows/pr-branch.md

@@ -31,12 +31,13 @@ if [ "$AHEAD" = "0" ]; then
 fi
 ```
 
-Display:
+Run this Bash command to emit the branded Deploy 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 deploy "PR BRANCH"
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- pp-core ► PR BRANCH
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+Then display the branch summary:
+```
 Branch: {CURRENT_BRANCH}
 Target: {TARGET}
 Commits: {AHEAD} ahead