@pareto4/pp-core 1.5.4 → 1.6.0

package/.claude-plugin/plugin.json

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

package/commands/pp-init.md

@@ -0,0 +1,36 @@
+---
+name: pp:init
+description: Initialize a project — git init, remote wiring, minimal metadata, then hand off
+argument-hint: "[--text]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+requires: [config]
+---
+<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>
+Universal project entry point. Takes any directory — empty or with existing code — from zero
+to: git-initialized, minimal identity captured, remote wired, and handed off to the next
+workflow.
+
+Works for every project regardless of provider. The gated GitLab provisioning path
+(Pareto satellite repos with `.platform-bindings.json`) is added in Plan 02 and slots
+into the structural anchor already present in the workflow.
+
+**After this command:** You will be asked whether to continue with `/pp-discovery`
+(client/Pareto projects) or `/pp-new-project` (greenfield planning).
+</objective>
+
+<execution_context>
+@~/.claude/pp-core/workflows/init.md
+</execution_context>
+
+<process>
+Execute end-to-end.
+Preserve all workflow gates: confirmation, commits, routing.
+</process>

package/commands/pp-ns-project.md

@@ -5,7 +5,7 @@ argument-hint: ""
 allowed-tools:
   - Read
   - Skill
-requires: [new-project, new-milestone, complete-milestone, audit-milestone, milestone-summary, import, ingest-docs, profile-user, review-backlog]
+requires: [init, new-project, new-milestone, complete-milestone, audit-milestone, milestone-summary, import, ingest-docs, profile-user, review-backlog]
 ---
 
 Route to the appropriate project / milestone skill based on the user's intent.
@@ -14,6 +14,7 @@ inline as part of `pp-audit-milestone`'s output.
 
 | User wants | Invoke |
 |---|---|
+| Initialize a project (canonical front door) | pp-init |
 | Start a new project | pp-new-project |
 | Create a new milestone | pp-new-milestone |
 | Complete the current milestone | pp-complete-milestone |

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "pp-core",
-  "version": "1.5.4",
+  "version": "1.6.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.5.4",
+  "version": "1.6.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",

package/pp-core/bin/lib/capability-registry.cjs

@@ -1307,6 +1307,77 @@ const capabilities = {
       "extendedHookEvents": []
     }
   },
+  "pareto-stack": {
+    "id": "pareto-stack",
+    "role": "feature",
+    "title": "Pareto Stack drift gate",
+    "description": "Ship-time platform drift detection for Pareto-managed stacks. Inert unless pareto.enabled is true and .platform-bindings.json is present. Classifies version gaps by severity: any major-version gap classifies as major; breaking is reserved and aliased to major for now. A blocking gate halts on block status; a non-blocking gate carries below-threshold warn advisories. Syncs board state via pareto-sync-board at ship:post.",
+    "tier": "full",
+    "requires": [],
+    "runtimeCompat": {
+      "supported": [
+        "*"
+      ],
+      "unsupported": []
+    },
+    "skills": [
+      "pareto-sync-board"
+    ],
+    "agents": [],
+    "activationKey": "pareto.enabled",
+    "config": {
+      "pareto.enabled": {
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the Pareto stack capability. When false, all gates and steps are inert."
+      },
+      "pareto.drift_block_on": {
+        "type": "enum",
+        "values": [
+          "breaking",
+          "major",
+          "minor",
+          "none"
+        ],
+        "default": "major",
+        "description": "Minimum drift severity that blocks the ship gate. breaking is reserved and aliased to major."
+      }
+    },
+    "hooks": [],
+    "steps": [
+      {
+        "point": "ship:post",
+        "ref": {
+          "skill": "pareto-sync-board"
+        },
+        "produces": [],
+        "consumes": [],
+        "when": "pareto.enabled",
+        "onError": "skip"
+      }
+    ],
+    "contributions": [],
+    "gates": [
+      {
+        "point": "ship:pre",
+        "check": {
+          "query": "ship.platform-drift"
+        },
+        "when": "pareto.enabled",
+        "blocking": true,
+        "onError": "skip"
+      },
+      {
+        "point": "ship:pre",
+        "check": {
+          "query": "ship.platform-drift"
+        },
+        "when": "pareto.enabled",
+        "blocking": false,
+        "onError": "skip"
+      }
+    ]
+  },
   "pattern-mapper": {
     "id": "pattern-mapper",
     "role": "feature",
@@ -1561,7 +1632,7 @@ const capabilities = {
         "into": "planner",
         "fragment": {
           "path": "fragments/plan-pre.md",
-          "inline": "# Schema Push Detection Gate\n\n> Detects schema-relevant files in the phase scope and injects a mandatory `[BLOCKING]` schema push task into the plan. Prevents false-positive verification where build/types pass because TypeScript types come from config, not the live database.\n\nCheck if any files in the phase scope match schema patterns:\n\n```bash\nPHASE_SECTION=$(gsd_run query roadmap.get-phase \"${PHASE}\" --pick section 2>/dev/null)\n```\n\nScan `PHASE_SECTION`, `CONTEXT.md` (if loaded), and `RESEARCH.md` (if exists) for file paths matching these ORM patterns:\n\n| ORM | File Patterns |\n|-----|--------------|\n| Payload CMS | `src/collections/**/*.ts`, `src/globals/**/*.ts` |\n| Prisma | `prisma/schema.prisma`, `prisma/schema/*.prisma` |\n| Drizzle | `drizzle/schema.ts`, `src/db/schema.ts`, `drizzle/*.ts` |\n| Supabase | `supabase/migrations/*.sql` |\n| TypeORM | `src/entities/**/*.ts`, `src/migrations/**/*.ts` |\n\nAlso check if any existing PLAN.md files for this phase already reference these file patterns in `files_modified`.\n\n**If schema-relevant files detected:**\n\nSet `SCHEMA_PUSH_REQUIRED=true` and `SCHEMA_ORM={detected_orm}`.\n\nDetermine the push command for the detected ORM:\n\n| ORM | Push Command | Non-TTY Workaround |\n|-----|-------------|-------------------|\n| Payload CMS | `npx payload migrate` | `CI=true PAYLOAD_MIGRATING=true npx payload migrate` |\n| Prisma | `npx prisma db push` | `npx prisma db push --accept-data-loss` (if destructive) |\n| Drizzle | `npx drizzle-kit push` | `npx drizzle-kit push` |\n| Supabase | `supabase db push` | Set `SUPABASE_ACCESS_TOKEN` env var |\n| TypeORM | `npx typeorm migration:run` | `npx typeorm migration:run -d src/data-source.ts` |\n\nInject the following into the planner prompt (step 8) as an additional constraint:\n\n```markdown\n<schema_push_requirement>\n**[BLOCKING] Schema Push Required**\n\nThis phase modifies schema-relevant files ({detected_files}). The planner MUST include\na `[BLOCKING]` task that runs the database schema push command AFTER all schema file\nmodifications are complete but BEFORE verification.\n\n- ORM detected: {SCHEMA_ORM}\n- Push command: {push_command}\n- Non-TTY workaround: {env_hint}\n- If push requires interactive prompts that cannot be suppressed, flag the task for\n  manual intervention with `autonomous: false`\n\nThis task is mandatory — the phase CANNOT pass verification without it. Build and\ntype checks will pass without the push (types come from config, not the live database),\ncreating a false-positive verification state.\n</schema_push_requirement>\n```\n\nDisplay: `Schema files detected ({SCHEMA_ORM}) — [BLOCKING] push task will be injected into plans`\n\n**If no schema-relevant files detected:** Skip silently.\n"
+          "inline": "# Schema Push Detection Gate\n\n> Detects schema-relevant files in the phase scope and injects a mandatory `[BLOCKING]` schema push task into the plan. Prevents false-positive verification where build/types pass because TypeScript types come from config, not the live database.\n\nCheck if any files in the phase scope match schema patterns:\n\n```bash\nPHASE_SECTION=$(pp_run query roadmap.get-phase \"${PHASE}\" --pick section 2>/dev/null)\n```\n\nScan `PHASE_SECTION`, `CONTEXT.md` (if loaded), and `RESEARCH.md` (if exists) for file paths matching these ORM patterns:\n\n| ORM | File Patterns |\n|-----|--------------|\n| Payload CMS | `src/collections/**/*.ts`, `src/globals/**/*.ts` |\n| Prisma | `prisma/schema.prisma`, `prisma/schema/*.prisma` |\n| Drizzle | `drizzle/schema.ts`, `src/db/schema.ts`, `drizzle/*.ts` |\n| Supabase | `supabase/migrations/*.sql` |\n| TypeORM | `src/entities/**/*.ts`, `src/migrations/**/*.ts` |\n\nAlso check if any existing PLAN.md files for this phase already reference these file patterns in `files_modified`.\n\n**If schema-relevant files detected:**\n\nSet `SCHEMA_PUSH_REQUIRED=true` and `SCHEMA_ORM={detected_orm}`.\n\nDetermine the push command for the detected ORM:\n\n| ORM | Push Command | Non-TTY Workaround |\n|-----|-------------|-------------------|\n| Payload CMS | `npx payload migrate` | `CI=true PAYLOAD_MIGRATING=true npx payload migrate` |\n| Prisma | `npx prisma db push` | `npx prisma db push --accept-data-loss` (if destructive) |\n| Drizzle | `npx drizzle-kit push` | `npx drizzle-kit push` |\n| Supabase | `supabase db push` | Set `SUPABASE_ACCESS_TOKEN` env var |\n| TypeORM | `npx typeorm migration:run` | `npx typeorm migration:run -d src/data-source.ts` |\n\nInject the following into the planner prompt (step 8) as an additional constraint:\n\n```markdown\n<schema_push_requirement>\n**[BLOCKING] Schema Push Required**\n\nThis phase modifies schema-relevant files ({detected_files}). The planner MUST include\na `[BLOCKING]` task that runs the database schema push command AFTER all schema file\nmodifications are complete but BEFORE verification.\n\n- ORM detected: {SCHEMA_ORM}\n- Push command: {push_command}\n- Non-TTY workaround: {env_hint}\n- If push requires interactive prompts that cannot be suppressed, flag the task for\n  manual intervention with `autonomous: false`\n\nThis task is mandatory — the phase CANNOT pass verification without it. Build and\ntype checks will pass without the push (types come from config, not the live database),\ncreating a false-positive verification state.\n</schema_push_requirement>\n```\n\nDisplay: `Schema files detected ({SCHEMA_ORM}) — [BLOCKING] push task will be injected into plans`\n\n**If no schema-relevant files detected:** Skip silently.\n"
         },
         "produces": [],
         "consumes": [
@@ -1915,6 +1986,7 @@ const bySkill = {
   "mempalace-recall": "mempalace",
   "mempalace-capture": "mempalace",
   "validate-phase": "nyquist",
+  "pareto-sync-board": "pareto-stack",
   "profile-user": "profile-pipeline",
   "secure-phase": "security",
   "ui-phase": "ui",
@@ -2083,7 +2155,7 @@ const byLoopPoint = {
         "into": "planner",
         "fragment": {
           "path": "fragments/plan-pre.md",
-          "inline": "# Schema Push Detection Gate\n\n> Detects schema-relevant files in the phase scope and injects a mandatory `[BLOCKING]` schema push task into the plan. Prevents false-positive verification where build/types pass because TypeScript types come from config, not the live database.\n\nCheck if any files in the phase scope match schema patterns:\n\n```bash\nPHASE_SECTION=$(gsd_run query roadmap.get-phase \"${PHASE}\" --pick section 2>/dev/null)\n```\n\nScan `PHASE_SECTION`, `CONTEXT.md` (if loaded), and `RESEARCH.md` (if exists) for file paths matching these ORM patterns:\n\n| ORM | File Patterns |\n|-----|--------------|\n| Payload CMS | `src/collections/**/*.ts`, `src/globals/**/*.ts` |\n| Prisma | `prisma/schema.prisma`, `prisma/schema/*.prisma` |\n| Drizzle | `drizzle/schema.ts`, `src/db/schema.ts`, `drizzle/*.ts` |\n| Supabase | `supabase/migrations/*.sql` |\n| TypeORM | `src/entities/**/*.ts`, `src/migrations/**/*.ts` |\n\nAlso check if any existing PLAN.md files for this phase already reference these file patterns in `files_modified`.\n\n**If schema-relevant files detected:**\n\nSet `SCHEMA_PUSH_REQUIRED=true` and `SCHEMA_ORM={detected_orm}`.\n\nDetermine the push command for the detected ORM:\n\n| ORM | Push Command | Non-TTY Workaround |\n|-----|-------------|-------------------|\n| Payload CMS | `npx payload migrate` | `CI=true PAYLOAD_MIGRATING=true npx payload migrate` |\n| Prisma | `npx prisma db push` | `npx prisma db push --accept-data-loss` (if destructive) |\n| Drizzle | `npx drizzle-kit push` | `npx drizzle-kit push` |\n| Supabase | `supabase db push` | Set `SUPABASE_ACCESS_TOKEN` env var |\n| TypeORM | `npx typeorm migration:run` | `npx typeorm migration:run -d src/data-source.ts` |\n\nInject the following into the planner prompt (step 8) as an additional constraint:\n\n```markdown\n<schema_push_requirement>\n**[BLOCKING] Schema Push Required**\n\nThis phase modifies schema-relevant files ({detected_files}). The planner MUST include\na `[BLOCKING]` task that runs the database schema push command AFTER all schema file\nmodifications are complete but BEFORE verification.\n\n- ORM detected: {SCHEMA_ORM}\n- Push command: {push_command}\n- Non-TTY workaround: {env_hint}\n- If push requires interactive prompts that cannot be suppressed, flag the task for\n  manual intervention with `autonomous: false`\n\nThis task is mandatory — the phase CANNOT pass verification without it. Build and\ntype checks will pass without the push (types come from config, not the live database),\ncreating a false-positive verification state.\n</schema_push_requirement>\n```\n\nDisplay: `Schema files detected ({SCHEMA_ORM}) — [BLOCKING] push task will be injected into plans`\n\n**If no schema-relevant files detected:** Skip silently.\n"
+          "inline": "# Schema Push Detection Gate\n\n> Detects schema-relevant files in the phase scope and injects a mandatory `[BLOCKING]` schema push task into the plan. Prevents false-positive verification where build/types pass because TypeScript types come from config, not the live database.\n\nCheck if any files in the phase scope match schema patterns:\n\n```bash\nPHASE_SECTION=$(pp_run query roadmap.get-phase \"${PHASE}\" --pick section 2>/dev/null)\n```\n\nScan `PHASE_SECTION`, `CONTEXT.md` (if loaded), and `RESEARCH.md` (if exists) for file paths matching these ORM patterns:\n\n| ORM | File Patterns |\n|-----|--------------|\n| Payload CMS | `src/collections/**/*.ts`, `src/globals/**/*.ts` |\n| Prisma | `prisma/schema.prisma`, `prisma/schema/*.prisma` |\n| Drizzle | `drizzle/schema.ts`, `src/db/schema.ts`, `drizzle/*.ts` |\n| Supabase | `supabase/migrations/*.sql` |\n| TypeORM | `src/entities/**/*.ts`, `src/migrations/**/*.ts` |\n\nAlso check if any existing PLAN.md files for this phase already reference these file patterns in `files_modified`.\n\n**If schema-relevant files detected:**\n\nSet `SCHEMA_PUSH_REQUIRED=true` and `SCHEMA_ORM={detected_orm}`.\n\nDetermine the push command for the detected ORM:\n\n| ORM | Push Command | Non-TTY Workaround |\n|-----|-------------|-------------------|\n| Payload CMS | `npx payload migrate` | `CI=true PAYLOAD_MIGRATING=true npx payload migrate` |\n| Prisma | `npx prisma db push` | `npx prisma db push --accept-data-loss` (if destructive) |\n| Drizzle | `npx drizzle-kit push` | `npx drizzle-kit push` |\n| Supabase | `supabase db push` | Set `SUPABASE_ACCESS_TOKEN` env var |\n| TypeORM | `npx typeorm migration:run` | `npx typeorm migration:run -d src/data-source.ts` |\n\nInject the following into the planner prompt (step 8) as an additional constraint:\n\n```markdown\n<schema_push_requirement>\n**[BLOCKING] Schema Push Required**\n\nThis phase modifies schema-relevant files ({detected_files}). The planner MUST include\na `[BLOCKING]` task that runs the database schema push command AFTER all schema file\nmodifications are complete but BEFORE verification.\n\n- ORM detected: {SCHEMA_ORM}\n- Push command: {push_command}\n- Non-TTY workaround: {env_hint}\n- If push requires interactive prompts that cannot be suppressed, flag the task for\n  manual intervention with `autonomous: false`\n\nThis task is mandatory — the phase CANNOT pass verification without it. Build and\ntype checks will pass without the push (types come from config, not the live database),\ncreating a false-positive verification state.\n</schema_push_requirement>\n```\n\nDisplay: `Schema files detected ({SCHEMA_ORM}) — [BLOCKING] push task will be injected into plans`\n\n**If no schema-relevant files detected:** Skip silently.\n"
         },
         "produces": [],
         "consumes": [
@@ -2330,6 +2402,26 @@ const byLoopPoint = {
     "steps": [],
     "contributions": [],
     "gates": [
+      {
+        "capId": "pareto-stack",
+        "point": "ship:pre",
+        "check": {
+          "query": "ship.platform-drift"
+        },
+        "when": "pareto.enabled",
+        "blocking": true,
+        "onError": "skip"
+      },
+      {
+        "capId": "pareto-stack",
+        "point": "ship:pre",
+        "check": {
+          "query": "ship.platform-drift"
+        },
+        "when": "pareto.enabled",
+        "blocking": false,
+        "onError": "skip"
+      },
       {
         "capId": "security",
         "point": "ship:pre",
@@ -2361,6 +2453,17 @@ const byLoopPoint = {
         ],
         "when": "mempalace.enabled",
         "onError": "skip"
+      },
+      {
+        "capId": "pareto-stack",
+        "point": "ship:post",
+        "ref": {
+          "skill": "pareto-sync-board"
+        },
+        "produces": [],
+        "consumes": [],
+        "when": "pareto.enabled",
+        "onError": "skip"
       }
     ],
     "contributions": [],
@@ -2389,6 +2492,8 @@ const configKeys = {
   "mempalace.diary_journal": "mempalace",
   "mempalace.auto_capture_hooks": "mempalace",
   "workflow.nyquist_validation": "nyquist",
+  "pareto.enabled": "pareto-stack",
+  "pareto.drift_block_on": "pareto-stack",
   "workflow.pattern_mapper": "pattern-mapper",
   "profile-pipeline.enabled": "profile-pipeline",
   "workflow.research": "research",
@@ -2537,6 +2642,24 @@ const configSchema = {
     "default": true,
     "description": "Enable Nyquist validation coverage auditing."
   },
+  "pareto.enabled": {
+    "owner": "pareto-stack",
+    "type": "boolean",
+    "default": false,
+    "description": "Enable the Pareto stack capability. When false, all gates and steps are inert."
+  },
+  "pareto.drift_block_on": {
+    "owner": "pareto-stack",
+    "type": "enum",
+    "default": "major",
+    "description": "Minimum drift severity that blocks the ship gate. breaking is reserved and aliased to major.",
+    "values": [
+      "breaking",
+      "major",
+      "minor",
+      "none"
+    ]
+  },
   "workflow.pattern_mapper": {
     "owner": "pattern-mapper",
     "type": "boolean",
@@ -3588,6 +3711,9 @@ const capabilityClusters = {
   "nyquist": [
     "validate-phase"
   ],
+  "pareto-stack": [
+    "pareto-sync-board"
+  ],
   "profile-pipeline": [
     "profile-user"
   ],
@@ -3637,6 +3763,12 @@ const profileMembership = {
       "full"
     ]
   },
+  "pareto-stack": {
+    "tier": "full",
+    "profiles": [
+      "full"
+    ]
+  },
   "profile-pipeline": {
     "tier": "full",
     "profiles": [
@@ -3681,6 +3813,7 @@ const _requiresGraph = {
   "mempalace": [],
   "nyquist": [],
   "opencode": [],
+  "pareto-stack": [],
   "pattern-mapper": [
     "research"
   ],

package/pp-core/bin/lib/check-command-router.cjs

@@ -23,6 +23,10 @@ const phaseLocatorMod = require("./phase-locator.cjs");
 const { findPhaseInternal } = phaseLocatorMod;
 const decisions_cjs_1 = require("./decisions.cjs");
 const ui_safety_gate_cjs_1 = require("./ui-safety-gate.cjs");
+const semver_compare_cjs_1 = require("./semver-compare.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const projectRootMod = require("./project-root.cjs");
+const { findProjectRoot } = projectRootMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verifyModule = require("./verify.cjs");
 const { cmdVerifySchemaDrift, cmdVerifyCodebaseDrift } = verifyModule;
@@ -727,6 +731,176 @@ function cmdGapAnalysisPlanPost(projectDir, args, raw) {
         message: result.table || result.summary || '',
     }, raw, undefined);
 }
+const DRIFT_SEVERITY_ORDINAL = {
+    none: 0,
+    minor: 1,
+    major: 2,
+    breaking: 3,
+};
+/**
+ * Classify drift severity from pinned vs latest semver tuples.
+ *
+ * Pre-condition: compareSemverCore(pinned, latest) < 0 (pinned is strictly behind).
+ * Severity mapping (A3):
+ *   differing major → 'major'  (breaking aliased to major; semver can't distinguish)
+ *   equal major, differing minor → 'minor'
+ *   equal major+minor, differing patch → 'none'  (below minor; always warn, not block)
+ */
+function classifyDriftSeverity(pinned, latest) {
+    const [pMaj, pMin] = (0, semver_compare_cjs_1.toNumericTuple)(pinned);
+    const [lMaj, lMin] = (0, semver_compare_cjs_1.toNumericTuple)(latest);
+    if (lMaj > pMaj)
+        return 'major';
+    if (lMin > pMin)
+        return 'minor';
+    return 'none'; // patch-level difference
+}
+/**
+ * Read pareto.drift_block_on from .planning/config.json.
+ * Returns 'major' (default) when config is absent, malformed, or the key is unset.
+ */
+function readParetoConfig(projectDir) {
+    const configPath = node_path_1.default.join(projectDir, '.planning', 'config.json');
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf-8'));
+        const pareto = parsed['pareto'] ?? {};
+        const raw = pareto['drift_block_on'];
+        if (typeof raw === 'string' && raw in DRIFT_SEVERITY_ORDINAL) {
+            return { drift_block_on: raw };
+        }
+    }
+    catch { /* config absent or malformed → use default */ }
+    return { drift_block_on: 'major' };
+}
+/**
+ * Resolve the latest stable tag for a platform repo via git ls-remote.
+ *
+ * T-10-04: every candidate tag is filtered through isStableTripletSemver — never shell-eval.
+ * Returns '' when offline or the remote is unreachable (callers treat this as "unknown latest").
+ */
+function resolveLatestTagViaGitRemote(repoShortPath) {
+    // Construct GitLab URL from "group/project" format (e.g. "pareto4/pareto-platform-gcp").
+    const remoteUrl = `https://gitlab.com/${repoShortPath}`;
+    try {
+        const lsOutput = (0, node_child_process_1.execFileSync)('git', ['ls-remote', '--tags', '--refs', '--sort=-v:refname', remoteUrl], { encoding: 'utf-8', timeout: 10_000, maxBuffer: 512 * 1024, windowsHide: true });
+        // Sort is descending by version (--sort=-v:refname) so the first isStableTripletSemver match
+        // is the latest stable tag. T-10-04: never use an unfiltered tag string.
+        const tag = lsOutput
+            .split('\n')
+            .map((line) => {
+            const m = line.match(/\brefs\/tags\/([^\s^]+)$/);
+            return m ? m[1].trim() : '';
+        })
+            .find((t) => t && (0, semver_compare_cjs_1.isStableTripletSemver)(t));
+        return tag ?? '';
+    }
+    catch {
+        return ''; // offline or unreachable → signals "unknown latest" (Pitfall 4)
+    }
+}
+/**
+ * ship.platform-drift query handler (HOOK-02).
+ *
+ * Derives a graded severity verdict from the pinned-vs-latest platform tag diff,
+ * maps it to the pareto.drift_block_on threshold, and degrades safely:
+ *   - Inert when .platform-bindings.json is absent (HOOK-04 runtime file layer).
+ *   - Non-blocking warn when latest is unresolved or offline (T-10-06, Pitfall 4).
+ *
+ * Verdict shape: { status: 'inert'|'pass'|'warn'|'block', block, severity, pinned, latest, present }
+ *   block (boolean) mirrors status === 'block' — the uniform gate contract field the host
+ *   loop reads regardless of which capability owns the gate.
+ *
+ * Invocable as: pp_run check ship.platform-drift [--latest-tag <tag>] [--raw]
+ * The dot → hyphen normalization in routeCheckCommand maps "ship.platform-drift"
+ * to the "ship-platform-drift" branch.
+ *
+ * Reuse:
+ *   - Phase 7 reader contract: reads .platform-bindings.json directly at repo root
+ *     (same find/parse/TOCTOU pattern as cmdValidateBindings in platform-bindings.cts).
+ *   - semver-compare.cjs: toNumericTuple, compareSemverCore, isStableTripletSemver
+ *     (no reimplemented semver; no shell-eval of tag strings).
+ */
+function cmdShipPlatformDrift(cwd, args, raw) {
+    // Step 1: Resolve project root (same approach as cmdValidateBindings in platform-bindings.cts).
+    let root;
+    try {
+        root = findProjectRoot(cwd) || cwd;
+    }
+    catch {
+        root = cwd;
+    }
+    // Step 1b: HOOK-04 runtime file layer — absent → inert (never error(), opt-in default).
+    const bindingsPath = node_path_1.default.join(root, '.platform-bindings.json');
+    if (!node_fs_1.default.existsSync(bindingsPath)) {
+        output({ status: 'inert', block: false, present: false }, raw, undefined);
+        return;
+    }
+    // Step 2: Parse .platform-bindings.json (malformed structure → graceful warn, not block).
+    let bindingsObj;
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(bindingsPath, 'utf-8'));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            output({
+                status: 'warn', block: false, severity: 'none',
+                pinned: null, latest: null, present: true,
+                message: 'Malformed .platform-bindings.json structure — drift check skipped',
+            }, raw, undefined);
+            return;
+        }
+        bindingsObj = parsed;
+    }
+    catch {
+        // TOCTOU guard — file vanished between existsSync and readFileSync → inert path.
+        output({ status: 'inert', block: false, present: false }, raw, undefined);
+        return;
+    }
+    // Extract platform.tag (PINNED) and platform.repo for remote tag resolution.
+    const platformField = (typeof bindingsObj['platform'] === 'object' &&
+        bindingsObj['platform'] !== null &&
+        !Array.isArray(bindingsObj['platform'])) ? bindingsObj['platform'] : null;
+    const pinned = typeof platformField?.['tag'] === 'string' ? platformField['tag'].trim() : '';
+    const platformRepo = typeof platformField?.['repo'] === 'string' ? platformField['repo'].trim() : '';
+    // Guard: missing or invalid pinned tag → advisory warn, do not block.
+    if (!pinned || !(0, semver_compare_cjs_1.isStableTripletSemver)(pinned)) {
+        output({
+            status: 'warn', block: false, severity: 'none',
+            pinned: pinned || null, latest: null, present: true,
+            message: 'platform.tag is missing or not a valid semver in .platform-bindings.json — drift check advisory only',
+        }, raw, undefined);
+        return;
+    }
+    // Step 3: Resolve LATEST via --latest-tag arg (deterministic) or git ls-remote (live).
+    const latestTagArgIdx = args.indexOf('--latest-tag');
+    let latest = latestTagArgIdx >= 0 ? (args[latestTagArgIdx + 1] ?? '') : '';
+    if (!latest && platformRepo) {
+        // T-10-04: resolveLatestTagViaGitRemote filters all tags through isStableTripletSemver.
+        latest = resolveLatestTagViaGitRemote(platformRepo);
+    }
+    // Step 4: Offline / unresolved latest → non-blocking warn (T-10-06, Pitfall 4).
+    // A disconnected dev or CI run must never be blocked by an unresolvable remote.
+    if (!latest || !(0, semver_compare_cjs_1.isStableTripletSemver)(latest)) {
+        output({
+            status: 'warn', block: false, severity: 'none',
+            pinned, latest: latest || null, present: true,
+            message: 'Latest platform tag could not be resolved (offline or unreachable remote) — drift check advisory only',
+        }, raw, undefined);
+        return;
+    }
+    // Step 4b: Pinned is current or ahead of latest → pass.
+    if ((0, semver_compare_cjs_1.compareSemverCore)(pinned, latest) >= 0) {
+        output({ status: 'pass', block: false, severity: 'none', pinned, latest, present: true }, raw, undefined);
+        return;
+    }
+    // Step 5: Classify drift severity from tuple diff (A3; breaking aliased to major for now).
+    const severity = classifyDriftSeverity(pinned, latest);
+    // Step 6: Read pareto.drift_block_on threshold (default 'major').
+    const { drift_block_on: threshold } = readParetoConfig(cwd);
+    const thresholdOrd = DRIFT_SEVERITY_ORDINAL[threshold] ?? DRIFT_SEVERITY_ORDINAL['major'];
+    const severityOrd = DRIFT_SEVERITY_ORDINAL[severity];
+    // Step 7: Emit verdict — block when severity ≥ threshold, warn otherwise.
+    const status = severityOrd >= thresholdOrd ? 'block' : 'warn';
+    output({ status, block: status === 'block', severity, pinned, latest, present: true }, raw, undefined);
+}
 function routeCheckCommand({ args, cwd, raw }) {
     // Normalize dots to hyphens in the subcommand so both forms are accepted.
     // This makes `check.query = "ui.plan-gate"` (dotted form in capability.json gates)
@@ -764,6 +938,13 @@ function routeCheckCommand({ args, cwd, raw }) {
         cmdUiSafetyGate(cwd, args, raw);
         return;
     }
+    if (subcommand === 'ship-platform-drift') {
+        // ship.platform-drift — graded platform-tag drift check (HOOK-02).
+        // Dot-to-hyphen normalization means query "ship.platform-drift" routes here.
+        // Reuses Phase 7 reader contract + semver-compare; inert when bindings absent (HOOK-04).
+        cmdShipPlatformDrift(cwd, args, raw);
+        return;
+    }
     if (subcommand === 'verify-schema-drift') {
         // Delegates to verify.schema-drift — drift capability gate at execute:wave:post (blocking).
         // Dot-to-hyphen normalization means query "verify.schema-drift" routes here.
@@ -787,7 +968,7 @@ function routeCheckCommand({ args, cwd, raw }) {
         (0, prohibition_enforcement_cjs_1.routeProhibitionEnforcement)(args, raw);
         return;
     }
-    error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify, gap-analysis-plan-post, prohibition-enforcement, tdd-review-checkpoint, ui-plan-gate, ui-safety-gate, verify-schema-drift, verify-codebase-drift', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify, gap-analysis-plan-post, prohibition-enforcement, ship-platform-drift, tdd-review-checkpoint, ui-plan-gate, ui-safety-gate, verify-schema-drift, verify-codebase-drift', ERROR_REASON.SDK_UNKNOWN_COMMAND);
 }
 module.exports = {
     routeCheckCommand,
@@ -797,4 +978,5 @@ module.exports = {
     computeUiSafetyGate,
     cmdGapAnalysisPlanPost,
     cmdTddReviewCheckpoint,
+    cmdShipPlatformDrift,
 };

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

@@ -20,6 +20,7 @@ exports.CLUSTERS = void 0;
 exports.allClusteredSkills = allClusteredSkills;
 exports.CLUSTERS = Object.freeze({
     core_loop: Object.freeze([
+        'init',
         'new-project',
         'discovery',
         'discuss-phase',

package/pp-core/bin/lib/command-aliases.cjs

@@ -583,6 +583,13 @@ exports.NON_FAMILY_COMMAND_ALIASES = [
         ],
         "mutation": false
     },
+    {
+        "canonical": "check.ship-platform-drift",
+        "aliases": [
+            "check ship-platform-drift"
+        ],
+        "mutation": false
+    },
     {
         "canonical": "commit",
         "aliases": [],

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

@@ -175,6 +175,8 @@ const ERROR_REASON = Object.freeze({
     HOOKS_OPT_OUT: 'hooks_opt_out',
     // security-scan
     SECURITY_SCAN_FAILED: 'security_scan_failed',
+    // platform-bindings
+    PLATFORM_BINDINGS_PARSE_FAILED: 'platform_bindings_parse_failed',
     // generic
     USAGE: 'usage',
     UNKNOWN: 'unknown',