@pareto4/pp-core 1.7.0 → 1.8.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pp-core",
   "displayName": "PP Core",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "PP Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "pareto4",

package/bin/install.js

@@ -7387,6 +7387,120 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile) {
     const nestedGsdDirForCleanup = path.join(configDir, 'skills', 'gsd');
     _removeHermesBareStemDirs(nestedGsdDirForCleanup);
   }
+
+  // Verbatim Pareto skill payload — MUST be the LAST step (post-prune ordering
+  // is load-bearing, Pitfall 1). The skills-kind loop above runs _removeGsdEntries,
+  // which unconditionally deletes EVERY pp-* skill dir; running the verbatim copy
+  // here (delete-then-recopy) makes the payload self-healing across repeated
+  // `npx` installs. Copies are byte-for-byte with NO content-rewrite pass (D-03).
+  installVerbatimSkills(runtime, configDir, scope);
+}
+
+/**
+ * Locate the bundled `pareto-skills/` source directory.
+ *
+ * Walks up from `__dirname` (up to 6 ancestors) looking for the sentinel
+ * `pareto-skills/pp-brand/SKILL.md`, mirroring the source-root walk-up the
+ * installer already uses to anchor `commands/`. Returns the absolute path to
+ * the `pareto-skills/` directory. Throws a clear error if it cannot be found.
+ *
+ * @returns {string} absolute path to the bundled `pareto-skills/` directory
+ */
+function findParetoSkillsSrc() {
+  let dir = __dirname;
+  for (let i = 0; i < 6; i += 1) {
+    const candidate = path.join(dir, 'pareto-skills');
+    if (fs.existsSync(path.join(candidate, 'pp-brand', 'SKILL.md'))) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(`findParetoSkillsSrc: could not locate pareto-skills/ from ${__dirname}`);
+}
+
+/**
+ * Place the verbatim Pareto skill payload into a runtime's resolved skills dir.
+ *
+ * This is the "second channel" for shipping skills: unlike command-derived
+ * skills (generated from commands/pp-*.md via the converter), these three
+ * `pp-*` skill dirs — plus a peer `_shared/` — are copied byte-for-byte with
+ * NO content-rewrite pass (D-03/D-07). That keeps them out of docs/COMMANDS.md
+ * and prevents the rewrite walker from corrupting templates or the protocol
+ * file (Pitfall 3). The payload is binary-safe (Crew assets), so we use a plain
+ * recursive fs.cpSync — never applyRuntimeContentRewritesInPlace,
+ * stageSkillsForRuntimeAsSkills, or the skillsKind converter.
+ *
+ * The destination is resolved from the artifact layout's skills-kind
+ * destSubpath (never a hardcoded `skills/`), so Hermes' nested `skills/gsd/`
+ * base is honoured automatically. Runtimes with no skills kind (gemini has only
+ * a commands kind; grok has no skills-layout descriptor) are skipped gracefully
+ * with an early `return 0` — never a throw (Pitfall 5).
+ *
+ * The skill names are a FIXED, package-owned allowlist — never interpolated
+ * input (V5 / T-16-03). No manifest entry is added, so `/pp-surface` pruning
+ * leaves these non-manifest pp-* dirs untouched (Pitfall 2). `_shared/*.sh`
+ * regain their exec bit after copy, because a content-level cpSync does not
+ * reliably preserve the exec bit cross-platform.
+ *
+ * @param {string} runtime - target runtime id
+ * @param {string} configDir - resolved runtime config directory
+ * @param {string} scope - 'local' | 'global'
+ * @returns {number} number of skill dirs placed (0 if the runtime has no skills kind)
+ */
+function installVerbatimSkills(runtime, configDir, scope) {
+  // Resolve the runtime's artifact layout. Two graceful-skip cases (Pitfall 5,
+  // no throw): gemini's layout has only a commands kind (skillsKindEntry
+  // undefined below); grok is not in the layout registry at all, so
+  // resolveRuntimeArtifactLayout throws 'Unknown runtime' — treat that as
+  // "no skills surface" and skip. In the production call path
+  // installRuntimeArtifacts has already resolved the layout, but this function
+  // is exported and called standalone by test harnesses (Plan 16-03), so the
+  // guard lives here too.
+  let layout;
+  try {
+    layout = resolveRuntimeArtifactLayout(runtime, configDir, scope);
+  } catch {
+    return 0;
+  }
+  const skillsKindEntry = layout.kinds.find((k) => k.kind === 'skills');
+  // gemini (commands-only): no skills surface — skip, don't throw.
+  if (!skillsKindEntry) return 0;
+
+  const src = findParetoSkillsSrc();
+  // destSubpath already encodes Hermes' nested `skills/gsd` — never hardcode `skills/`.
+  const skillsBase = path.join(configDir, skillsKindEntry.destSubpath);
+  fs.mkdirSync(skillsBase, { recursive: true });
+
+  // FIXED, package-owned allowlist — never interpolated input (V5 / T-16-03).
+  const BUNDLED = ['pp-brand', 'pp-project-setup', 'pp-obsidian-notes'];
+  let placed = 0;
+  for (const name of BUNDLED) {
+    const skillDest = path.join(skillsBase, name);
+    // Plain recursive, binary-safe copy — NO content-rewrite pass (D-03/Pitfall 3).
+    fs.cpSync(path.join(src, name), skillDest, { recursive: true });
+    if (verifyInstalled(skillDest, `skill ${name}`)) {
+      placed += 1;
+    }
+  }
+
+  // Copy _shared/ as a PEER of the skill dirs so `../_shared/` resolves from any
+  // skill body (D-04). Verbatim copy, no rewrite pass.
+  const sharedDest = path.join(skillsBase, '_shared');
+  fs.cpSync(path.join(src, '_shared'), sharedDest, { recursive: true });
+  verifyInstalled(sharedDest, 'skill _shared');
+
+  // Restore the exec bit on bundled *.sh — cpSync content copy does not reliably
+  // preserve it cross-platform (PATTERNS "No Analog Found").
+  try {
+    for (const entry of fs.readdirSync(sharedDest)) {
+      if (entry.endsWith('.sh')) {
+        fs.chmodSync(path.join(sharedDest, entry), 0o755);
+      }
+    }
+  } catch { /* best-effort: non-fatal if _shared has no scripts */ }
+
+  console.log(`  ${green}✓${reset} Placed ${placed} verbatim Pareto skill(s) + _shared into ${skillsKindEntry.destSubpath}`);
+  return placed;
 }
 
 /**
@@ -12309,6 +12423,8 @@ module.exports = {
     readGsdCommandNames,
     installRuntimeArtifacts,
     installOpencodeFamilySkills,
+    installVerbatimSkills,
+    findParetoSkillsSrc,
     uninstallRuntimeArtifacts,
     parseConfigDirFromArgs,
     cleanupLegacyGsdCc,

package/commands/pp-build-handoff.md

@@ -0,0 +1,46 @@
+---
+name: pp:build-handoff
+description: "[DEPRECATED] Alias for /pp-discovery-to-build — transition a completed Pareto Discovery Sprint into a pp-core-ready project. Use /pp-discovery-to-build; this alias will be removed in a future major."
+argument-hint: "[--skip-validation] [--scaffold]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+requires: [new-project]
+---
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
+<deprecation_note>
+**Deprecated:** `/pp-build-handoff` was renamed to `/pp-discovery-to-build` in v1.8.0. This
+alias runs the identical workflow and is kept for back-compat with v1.7.x. Prefer
+`/pp-discovery-to-build`; this alias will be removed in a future major release.
+</deprecation_note>
+
+<objective>
+Bridge the gap between a completed Pareto Discovery Sprint and pp-core execution.
+
+Validates all 13 Discovery sessions are complete, synthesizes their outputs into a
+single structured handoff document, bootstraps the `.planning/` project state
+(PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, config.json), and wires up
+cross-references so pp-core agents can trace every decision back to the Discovery
+session that produced it.
+
+**After this command:** pp-core is initialized. Run `/pp-plan-phase 1` to start
+execution, or `/pp-autonomous` to run all phases.
+</objective>
+
+<execution_context>
+@~/.claude/pp-core/workflows/discovery-to-build.md
+</execution_context>
+
+<process>
+Execute end-to-end.
+</process>

package/commands/pp-discovery-to-build.md

@@ -0,0 +1,40 @@
+---
+name: pp:discovery-to-build
+description: Transition a completed Pareto Discovery Sprint into a pp-core-ready project — synthesize sessions into .planning/ and wire cross-references.
+argument-hint: "[--skip-validation] [--scaffold]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+requires: [new-project]
+---
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
+<objective>
+Bridge the gap between a completed Pareto Discovery Sprint and pp-core execution.
+
+Validates all 13 Discovery sessions are complete, synthesizes their outputs into a
+single structured handoff document, bootstraps the `.planning/` project state
+(PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, config.json), and wires up
+cross-references so pp-core agents can trace every decision back to the Discovery
+session that produced it.
+
+**After this command:** pp-core is initialized. Run `/pp-plan-phase 1` to start
+execution, or `/pp-autonomous` to run all phases.
+</objective>
+
+<execution_context>
+@~/.claude/pp-core/workflows/discovery-to-build.md
+</execution_context>
+
+<process>
+Execute end-to-end.
+</process>

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "pp-core",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "PP Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads pp-core's operating context into every Gemini CLI session.",
   "contextFileName": "GEMINI.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pareto4/pp-core",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Pareto pp-core — The Pareto Project's AI-assisted engineering framework: meta-prompting, context engineering, and spec-driven development for AI coding agents.",
   "bin": {
     "pp-core": "bin/install.js",
@@ -13,6 +13,7 @@
     "pp-core",
     "assets",
     "agents",
+    "pareto-skills",
     ".claude-plugin",
     "gemini-extension.json",
     "GEMINI.md",

package/pareto-skills/_shared/create-project-board.sh

@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+# create-project-board.sh
+#
+# Canonical GitHub Project v2 board creation for Pareto skills.
+# Creates (or updates) a project board for a given owner/repo with the
+# standard Pareto status columns, custom fields, and label palette.
+#
+# Used by:
+#   - pareto-project-setup (initial scaffold)
+#   - pareto-build-handoff (Discovery → pp-core handoff)
+#   - pareto-push-issues  (standalone requirements push)
+#
+# Single source of truth — edit here, not in the skills.
+#
+# Usage:
+#   source _shared/create-project-board.sh
+#   create_project_board "<owner>" "<project_title>" "<repo_slug>"
+#
+# Example:
+#   create_project_board "pareto-project" "my-app" "pareto-project/my-app"
+#
+# Environment variables honored:
+#   BOARD_OWNER_FALLBACK (default: "@me")  — used if org create fails
+#
+# Returns (via stdout, space-separated): <board_number> <owner>
+# Exits non-zero on fatal error.
+
+set -euo pipefail
+
+# -----------------------------------------------------------------------------
+# Canonical column schema
+# -----------------------------------------------------------------------------
+# Any change here propagates to every skill that sources this file.
+#
+# Status flow:
+#   Backlog → Discuss → Planned → In Progress → Verification → PR Raised → Done
+#
+# Each column maps 1:1 to a pp-core workflow step:
+#   Discuss      = /pp-discuss-phase (CONTEXT.md written)
+#   Planned      = /pp-plan-phase (PLAN.md created)
+#   In Progress  = /pp-execute-phase (branch active, executing)
+#   Verification = VERIFICATION.md written, tests passing
+#   PR Raised    = PR created from phase branch, awaiting merge
+#   Done         = PR merged, issue closed
+#
+PARETO_STATUS_OPTIONS='[
+  {name: "Backlog",       color: GRAY,   description: "Not yet started"},
+  {name: "Discuss",       color: PINK,   description: "Context gathering via /pp-discuss-phase"},
+  {name: "Planned",       color: BLUE,   description: "Plans created via /pp-plan-phase"},
+  {name: "In Progress",   color: YELLOW, description: "Executing via /pp-execute-phase"},
+  {name: "Verification",  color: ORANGE, description: "Verification passed — VERIFICATION.md written"},
+  {name: "PR Raised",     color: PURPLE, description: "PR created from phase branch, awaiting merge"},
+  {name: "Done",          color: GREEN,  description: "PR merged, issue closed"}
+]'
+
+# Label color palette for per-EPIC labels. Cycle through these in order.
+PARETO_EPIC_COLORS=(
+  "0E8A16" "1AA393" "D93F0B" "B44EFF"
+  "4A9EFF" "EF4444" "F5C842" "8B5CF6"
+)
+
+# -----------------------------------------------------------------------------
+# create_project_board <owner> <title> <owner/repo>
+# -----------------------------------------------------------------------------
+create_project_board() {
+  local OWNER="$1"
+  local TITLE="$2"
+  local REPO="$3"
+  local BOARD_NUM
+
+  # 1. Check for existing board matching title
+  BOARD_NUM=$(gh project list --owner "$OWNER" --format json 2>/dev/null \
+    | jq -r ".projects[] | select(.title==\"$TITLE\") | .number" || true)
+
+  if [ -z "$BOARD_NUM" ]; then
+    # 2. Try to create under the given owner
+    BOARD_NUM=$(gh project create --owner "$OWNER" --title "$TITLE" \
+      --format json 2>/dev/null | jq -r '.number' || true)
+
+    # 3. Fall back to personal projects if org creation failed
+    if [ -z "$BOARD_NUM" ]; then
+      OWNER="${BOARD_OWNER_FALLBACK:-@me}"
+      BOARD_NUM=$(gh project create --owner "$OWNER" --title "$TITLE" \
+        --format json | jq -r '.number')
+    fi
+
+    # 4. Link board to repo
+    gh project link "$BOARD_NUM" --owner "$OWNER" --repo "$REPO" >/dev/null
+  fi
+
+  # 5. Configure Status field with Pareto schema (idempotent — safe to re-run)
+  configure_status_field "$BOARD_NUM" "$OWNER"
+
+  # 6. Ensure custom fields exist (Priority, Sprint, Estimate, Phase)
+  ensure_custom_fields "$BOARD_NUM" "$OWNER"
+
+  echo "$BOARD_NUM $OWNER"
+}
+
+# -----------------------------------------------------------------------------
+# configure_status_field <board_num> <owner>
+# -----------------------------------------------------------------------------
+configure_status_field() {
+  local BOARD_NUM="$1"
+  local OWNER="$2"
+  local STATUS_FIELD_ID
+
+  STATUS_FIELD_ID=$(gh project field-list "$BOARD_NUM" --owner "$OWNER" --format json \
+    --jq '.fields[] | select(.name=="Status") | .id')
+
+  if [ -z "$STATUS_FIELD_ID" ]; then
+    echo "ERROR: Status field not found on board $BOARD_NUM" >&2
+    return 1
+  fi
+
+  gh api graphql -f query="
+    mutation {
+      updateProjectV2Field(input: {
+        fieldId: \"$STATUS_FIELD_ID\"
+        singleSelectOptions: $PARETO_STATUS_OPTIONS
+      }) {
+        projectV2Field { ... on ProjectV2SingleSelectField { id name } }
+      }
+    }
+  " >/dev/null
+}
+
+# -----------------------------------------------------------------------------
+# ensure_custom_fields <board_num> <owner>
+# -----------------------------------------------------------------------------
+ensure_custom_fields() {
+  local BOARD_NUM="$1"
+  local OWNER="$2"
+
+  # Priority (single-select)
+  gh project field-create "$BOARD_NUM" --owner "$OWNER" \
+    --name "Priority" --data-type "SINGLE_SELECT" \
+    --single-select-options "Must Have,Should Have,Could Have,Won't Have" \
+    2>/dev/null || true
+
+  # Sprint (iteration — created manually in UI if needed)
+  gh project field-create "$BOARD_NUM" --owner "$OWNER" \
+    --name "Sprint" --data-type "ITERATION" 2>/dev/null || true
+
+  # Estimate (number)
+  gh project field-create "$BOARD_NUM" --owner "$OWNER" \
+    --name "Estimate" --data-type "NUMBER" 2>/dev/null || true
+
+  # Phase (text — pp-core phase number reference, e.g. "3" or "3.1")
+  gh project field-create "$BOARD_NUM" --owner "$OWNER" \
+    --name "Phase" --data-type "TEXT" 2>/dev/null || true
+}
+
+# -----------------------------------------------------------------------------
+# ensure_core_labels <owner/repo>
+# -----------------------------------------------------------------------------
+# Idempotent — uses --force so existing labels get updated.
+ensure_core_labels() {
+  local REPO="$1"
+
+  gh label create "epic"         -c "3E4B9E" -d "Epic — high-level feature group"       --force -R "$REPO"
+  gh label create "user-story"   -c "1D76DB" -d "User story"                            --force -R "$REPO"
+  gh label create "must-have"    -c "B60205" -d "Must Have — MVP required"              --force -R "$REPO"
+  gh label create "should-have"  -c "FBCA04" -d "Should Have — important"               --force -R "$REPO"
+  gh label create "could-have"   -c "0E8A16" -d "Could Have — nice to have"             --force -R "$REPO"
+  gh label create "in-progress"  -c "FBCA04" -d "Phase branch actively executing"       --force -R "$REPO"
+  gh label create "verification" -c "D93F0B" -d "In pp-core verification + PR review"       --force -R "$REPO"
+}
+
+# -----------------------------------------------------------------------------
+# create_epic_label <owner/repo> <slug> <epic_id> <epic_title> <index>
+# -----------------------------------------------------------------------------
+# Color cycles through PARETO_EPIC_COLORS by index.
+create_epic_label() {
+  local REPO="$1"
+  local SLUG="$2"
+  local EPIC_ID="$3"
+  local TITLE="$4"
+  local IDX="$5"
+  local COLOR="${PARETO_EPIC_COLORS[$((IDX % ${#PARETO_EPIC_COLORS[@]}))]}"
+
+  gh label create "epic:${SLUG}" -c "$COLOR" -d "${EPIC_ID}: ${TITLE}" --force -R "$REPO"
+}
+
+# -----------------------------------------------------------------------------
+# If sourced, functions above are exported to the caller. If executed directly,
+# run create_project_board with positional args.
+# -----------------------------------------------------------------------------
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  if [ $# -lt 3 ]; then
+    echo "Usage: $0 <owner> <title> <owner/repo>" >&2
+    exit 1
+  fi
+  create_project_board "$@"
+fi