@pareto4/pp-core 1.11.1 → 1.12.0

package/pp-core/bin/lib/plan-graph.cjs

@@ -0,0 +1,368 @@
+"use strict";
+/**
+ * Plan graph — the single owner of how a phase's plans are ordered.
+ *
+ * Computes, from each PLAN.md's frontmatter (`depends_on`, `files_modified`,
+ * `serial_group`, `chain_reason`, task shapes):
+ *
+ *   - the wave of every plan;
+ *   - the serial groups (plans that share a wave but must run one after
+ *     another because they touch the same non-source file);
+ *   - the chain metrics (plan count, wave count, longest chain, and how many
+ *     links of that chain exist only because two plans touch the same
+ *     non-source file);
+ *   - the chain check the plan checker enforces (a longest chain longer than
+ *     half the plan count FAILS unless every link of it carries a recorded
+ *     `chain_reason`);
+ *   - same-shape merge candidates for the planner.
+ *
+ * Callers: `phase-plan-index` (src/phase.cts) adds this to the plan inventory.
+ * The planner and plan-checker agents read that output; they never compute a
+ * wave or a chain themselves.
+ *
+ * ## The wave rule
+ *
+ * A plan's wave is its longest-path level over two kinds of edges:
+ *   1. declared `depends_on` edges;
+ *   2. implicit edges between two plans that share a SOURCE file (see
+ *      `classifyPlanFile`) and are not already ordered by (1). The implicit
+ *      edge runs from the earlier plan (file order) to the later one.
+ * Two plans that share only NON-source files (a test file, a size baseline, a
+ * changeset, a doc, a planning file) get no edge: they stay in the same wave
+ * and are put in one serial group instead.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLAN_TASK_CAP = exports.PLAN_TITLE_MAX = void 0;
+exports.classifyPlanFile = classifyPlanFile;
+exports.isInstructionFile = isInstructionFile;
+exports.isSourceFile = isSourceFile;
+exports.planTitleProblem = planTitleProblem;
+exports.readPlanTitle = readPlanTitle;
+exports.computePlanGraph = computePlanGraph;
+const SOURCE_DIRS = ['src/', 'bin/', 'pp-core/bin/', 'hooks/', 'scripts/'];
+const DOC_EXTENSIONS = /\.(md|mdx|markdown|rst|txt|adoc)$/i;
+const DOC_BASENAMES = /^(LICENSE|NOTICE|CHANGELOG|AUTHORS)(\.[a-z]+)?$/i;
+function normalizePath(file) {
+    return String(file).trim().replace(/\\/g, '/').replace(/^\.\//, '');
+}
+/**
+ * Classify one `files_modified` entry. This is THE source/non-source predicate
+ * for plan ordering; nothing else decides it.
+ *
+ * Checked in this order (first match wins):
+ *   planning  — under `.planning/`
+ *   changeset — under `.changeset/` or `.changesets/`
+ *   baseline  — a `*baseline*.json`/`*.baseline.*` file, `__snapshots__/`, `*.snap`
+ *   test      — under a `test/`, `tests/` or `__tests__/` directory or a
+ *               `*.Tests/` project; or named `*.test.*`, `*.spec.*`,
+ *               `*_test.go|py`, `test_*.py`
+ *   source    — under `src/`, `bin/`, `pp-core/bin/`, `hooks/` or `scripts/`
+ *               (pp-core ships executable code from these)
+ *   doc       — a `.md/.mdx/.markdown/.rst/.txt/.adoc` file, anything under
+ *               `docs/` or `doc/`, or LICENSE/NOTICE/CHANGELOG/AUTHORS. In
+ *               pp-core this includes workflow, agent, reference and template
+ *               markdown.
+ *   source    — anything else. An unrecognised file is treated as source, so
+ *               it keeps the strict "shared file = later wave" rule.
+ */
+function classifyPlanFile(file) {
+    const p = normalizePath(file);
+    const base = p.split('/').pop() ?? p;
+    if (p.startsWith('.planning/'))
+        return 'planning';
+    if (/^\.changesets?\//.test(p))
+        return 'changeset';
+    if (/baseline[^/]*\.json$/i.test(base) || /\.baseline\./i.test(base) || /(^|\/)__snapshots__\//.test(p) || /\.snap$/i.test(base)) {
+        return 'baseline';
+    }
+    if (/(^|\/)(tests?|__tests__)\//.test(p) ||
+        /(^|\/)[^/]+\.Tests?\//.test(p) ||
+        /\.(test|spec)\.[^/]+$/i.test(base) ||
+        /_test\.(go|py)$/i.test(base) ||
+        /^test_[^/]*\.py$/i.test(base)) {
+        return 'test';
+    }
+    if (SOURCE_DIRS.some((dir) => p.startsWith(dir)))
+        return 'source';
+    if (DOC_EXTENSIONS.test(base) || /^docs?\//.test(p) || DOC_BASENAMES.test(base))
+        return 'doc';
+    return 'source';
+}
+/** A workflow or agent markdown file (the unit same-shape plans are made of). */
+function isInstructionFile(file) {
+    const p = normalizePath(file);
+    return /\.md$/i.test(p) && (/(^|\/)workflows\//.test(p) || /(^|\/)agents\//.test(p));
+}
+/** True when `file` is a source file for plan ordering (see `classifyPlanFile`). */
+function isSourceFile(file) {
+    return classifyPlanFile(file) === 'source';
+}
+/** Longest a plan title may be before it is reported (still valid). */
+exports.PLAN_TITLE_MAX = 100;
+/**
+ * Problem with a plan's `title:` frontmatter value, or null when it is a valid
+ * one-line title. `undefined` means the key is absent.
+ */
+function planTitleProblem(value) {
+    if (value === undefined)
+        return 'Missing required frontmatter field: title';
+    if (typeof value !== 'string' || value.trim() === '') {
+        return 'Frontmatter field title must be a non-empty one-line string';
+    }
+    if (/[\r\n]/.test(value))
+        return 'Frontmatter field title must be one line';
+    return null;
+}
+/** Normalised title, or null when absent/invalid. */
+function readPlanTitle(value) {
+    return planTitleProblem(value) === null ? value.trim() : null;
+}
+/** Default task cap per plan (agents/pp-planner.md: "Each plan: 2-3 tasks maximum."). */
+exports.PLAN_TASK_CAP = 3;
+function slug(text) {
+    return text.toLowerCase().replace(/\.[a-z0-9]+$/i, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'group';
+}
+function intersect(a, b) {
+    return [...new Set(a.filter((f) => b.has(f)))].sort();
+}
+/**
+ * Compute the plan graph. `nodes` must be in plan file order (that order
+ * breaks ties and orients implicit edges).
+ */
+function computePlanGraph(nodes, opts = {}) {
+    const taskCap = opts.taskCap ?? exports.PLAN_TASK_CAP;
+    const ids = nodes.map((n) => n.id);
+    const index = new Map(ids.map((id, i) => [id, i]));
+    const files = nodes.map((n) => n.filesModified.map(normalizePath).filter((f) => f !== ''));
+    const fileSets = files.map((f) => new Set(f));
+    const warnings = [];
+    // Adjacency over indices: edges[i] = successors of i.
+    const succ = nodes.map(() => new Set());
+    nodes.forEach((n, j) => {
+        for (const dep of n.dependsOn) {
+            const i = index.get(dep);
+            if (i === undefined || i === j)
+                continue;
+            succ[i].add(j);
+        }
+    });
+    const levelsOf = () => {
+        const inDeg = nodes.map(() => 0);
+        succ.forEach((s) => s.forEach((j) => { inDeg[j]++; }));
+        const level = nodes.map(() => 0);
+        const queue = [];
+        inDeg.forEach((d, i) => { if (d === 0)
+            queue.push(i); });
+        let head = 0;
+        while (head < queue.length) {
+            const cur = queue[head++];
+            for (const nxt of [...succ[cur]].sort((a, b) => a - b)) {
+                level[nxt] = Math.max(level[nxt], level[cur] + 1);
+                if (--inDeg[nxt] === 0)
+                    queue.push(nxt);
+            }
+        }
+        return { level, done: new Set(queue) };
+    };
+    // A declared cycle has no waves; nodes Kahn never dequeued are on or behind it.
+    const declaredLevels = levelsOf();
+    if (declaredLevels.done.size < nodes.length) {
+        return emptyGraph(nodes, ids.filter((_, i) => !declaredLevels.done.has(i)));
+    }
+    const reaches = (from, to) => {
+        const stack = [from];
+        const seen = new Set([from]);
+        while (stack.length > 0) {
+            const cur = stack.pop();
+            if (cur === to)
+                return true;
+            for (const nxt of succ[cur]) {
+                if (!seen.has(nxt)) {
+                    seen.add(nxt);
+                    stack.push(nxt);
+                }
+            }
+        }
+        return false;
+    };
+    // Implicit edges: a shared SOURCE file orders two otherwise-unordered plans.
+    const implicitEdges = [];
+    for (let i = 0; i < nodes.length; i++) {
+        for (let j = i + 1; j < nodes.length; j++) {
+            const sharedSource = intersect(files[j], fileSets[i]).filter(isSourceFile);
+            if (sharedSource.length === 0)
+                continue;
+            if (reaches(i, j) || reaches(j, i))
+                continue;
+            succ[i].add(j);
+            implicitEdges.push({ from: ids[i], to: ids[j], shared_source_files: sharedSource });
+        }
+    }
+    const { level } = levelsOf();
+    // Same-shape merge candidates: no source file, exactly one workflow/agent file
+    // (any other files are tests, baselines, changesets or planning), same task shape.
+    const shapeGroups = new Map();
+    nodes.forEach((n, i) => {
+        if (n.taskTypes.length === 0)
+            return;
+        const kinds = files[i].map(classifyPlanFile);
+        if (kinds.includes('source'))
+            return;
+        if (files[i].filter(isInstructionFile).length !== 1 || kinds.filter((k) => k === 'doc').length !== 1)
+            return;
+        const shape = n.taskTypes.join('+');
+        if (!shapeGroups.has(shape))
+            shapeGroups.set(shape, []);
+        shapeGroups.get(shape).push(i);
+    });
+    const mergeCandidates = [];
+    for (const [shape, members] of shapeGroups) {
+        if (members.length < 2)
+            continue;
+        const totalTasks = members.reduce((sum, i) => sum + nodes[i].taskTypes.length, 0);
+        mergeCandidates.push({
+            shape,
+            plans: members.map((i) => ids[i]),
+            total_tasks: totalTasks,
+            task_cap: taskCap,
+            action: totalTasks <= taskCap ? 'merge' : 'serial_group',
+        });
+    }
+    // Serial groups: union-find within each level.
+    const parent = nodes.map((_, i) => i);
+    const find = (x) => (parent[x] === x ? x : (parent[x] = find(parent[x])));
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent[Math.max(ra, rb)] = Math.min(ra, rb);
+    };
+    for (let i = 0; i < nodes.length; i++) {
+        for (let j = i + 1; j < nodes.length; j++) {
+            if (level[i] !== level[j])
+                continue;
+            const shared = intersect(files[j], fileSets[i]);
+            const sameDeclared = nodes[i].serialGroup !== null && nodes[i].serialGroup === nodes[j].serialGroup;
+            if (shared.length > 0 || sameDeclared)
+                union(i, j);
+        }
+    }
+    for (const cand of mergeCandidates) {
+        if (cand.action !== 'serial_group')
+            continue;
+        const members = cand.plans.map((id) => index.get(id));
+        for (const a of members)
+            for (const b of members)
+                if (a < b && level[a] === level[b])
+                    union(a, b);
+    }
+    const groupsByRoot = new Map();
+    nodes.forEach((_, i) => {
+        const r = find(i);
+        if (!groupsByRoot.has(r))
+            groupsByRoot.set(r, []);
+        groupsByRoot.get(r).push(i);
+    });
+    const serialGroupOf = Object.fromEntries(ids.map((id) => [id, null]));
+    const serialGroups = [];
+    const usedNames = new Set();
+    const roots = [...groupsByRoot.keys()].sort((a, b) => a - b);
+    for (const root of roots) {
+        const members = groupsByRoot.get(root).sort((a, b) => a - b);
+        if (members.length < 2)
+            continue;
+        const sharedFiles = new Set();
+        for (const a of members)
+            for (const b of members)
+                if (a < b)
+                    intersect(files[b], fileSets[a]).forEach((f) => sharedFiles.add(f));
+        const shared = [...sharedFiles].sort();
+        const declaredName = members.map((i) => nodes[i].serialGroup).find((g) => !!g);
+        let name = declaredName ?? `w${level[root] + 1}-${shared.length > 0 ? slug(shared[0].split('/').pop()) : 'same-shape'}`;
+        if (usedNames.has(name)) {
+            let k = 2;
+            while (usedNames.has(`${name}-${k}`))
+                k++;
+            name = `${name}-${k}`;
+        }
+        usedNames.add(name);
+        for (const i of members)
+            serialGroupOf[ids[i]] = name;
+        serialGroups.push({ name, level: level[root], plans: members.map((i) => ids[i]), shared_files: shared });
+    }
+    nodes.forEach((n, i) => {
+        if (n.serialGroup && serialGroupOf[ids[i]] !== n.serialGroup) {
+            warnings.push(`Plan ${ids[i]}: declares serial_group: ${n.serialGroup} but the plan graph puts it in ` +
+                `${serialGroupOf[ids[i]] ?? 'no serial group'} (a serial group only holds plans of one wave).`);
+        }
+    });
+    // Longest chain (by plan count) over the full DAG.
+    const order = ids.map((_, i) => i).sort((a, b) => level[a] - level[b] || a - b);
+    const best = nodes.map(() => 1);
+    const prev = nodes.map(() => null);
+    const preds = nodes.map(() => []);
+    succ.forEach((s, i) => s.forEach((j) => preds[j].push(i)));
+    for (const j of order) {
+        for (const i of preds[j].sort((a, b) => a - b)) {
+            if (best[i] + 1 > best[j]) {
+                best[j] = best[i] + 1;
+                prev[j] = i;
+            }
+        }
+    }
+    let end = -1;
+    nodes.forEach((_, i) => { if (end === -1 || best[i] > best[end])
+        end = i; });
+    const chain = [];
+    for (let cur = end; cur !== null && cur !== -1; cur = prev[cur])
+        chain.unshift(cur);
+    const links = [];
+    for (let k = 1; k < chain.length; k++) {
+        const a = chain[k - 1];
+        const b = chain[k];
+        const shared = intersect(files[b], fileSets[a]);
+        const kind = shared.some(isSourceFile) ? 'source-file' : shared.length > 0 ? 'non-source-file' : 'declared';
+        links.push({ from: ids[a], to: ids[b], kind, shared_files: shared, reason: nodes[b].chainReason });
+    }
+    const nonSourceLinks = links.filter((l) => l.kind === 'non-source-file').length;
+    const limit = nodes.length / 2;
+    const unreasoned = links.filter((l) => !l.reason).map((l) => ({ from: l.from, to: l.to, kind: l.kind }));
+    const passed = chain.length <= limit || unreasoned.length === 0;
+    const waveCount = nodes.length === 0 ? 0 : Math.max(...level) + 1;
+    const message = passed
+        ? `longest chain ${chain.length} of ${nodes.length} plans (limit ${limit})` +
+            (chain.length > limit ? ' — every link has a chain_reason' : '')
+        : `longest chain is ${chain.length} plans, over half the plan count (${nodes.length} plans, limit ${limit}), ` +
+            `and ${unreasoned.length} link(s) have no chain_reason: ${unreasoned.map((l) => `${l.from}->${l.to} (${l.kind})`).join(', ')}. ` +
+            `Drop depends_on edges that exist only because two plans touch the same non-source file ` +
+            `(they share a wave in a serial group instead), merge same-shape plans, or record a ` +
+            `chain_reason on each later plan saying why it must wait.`;
+    return {
+        cycle: null,
+        level: Object.fromEntries(ids.map((id, i) => [id, level[i]])),
+        serialGroupOf,
+        serialGroups,
+        implicitEdges,
+        plan_count: nodes.length,
+        wave_count: waveCount,
+        longest_chain: { length: chain.length, plans: chain.map((i) => ids[i]), links, non_source_links: nonSourceLinks },
+        chain_check: { passed, limit, unreasoned_links: passed ? [] : unreasoned, message },
+        merge_candidates: mergeCandidates,
+        warnings,
+    };
+}
+function emptyGraph(nodes, cycle) {
+    return {
+        cycle,
+        level: {},
+        serialGroupOf: Object.fromEntries(nodes.map((n) => [n.id, null])),
+        serialGroups: [],
+        implicitEdges: [],
+        plan_count: nodes.length,
+        wave_count: 0,
+        longest_chain: { length: 0, plans: [], links: [], non_source_links: 0 },
+        chain_check: { passed: false, limit: nodes.length / 2, unreasoned_links: [], message: `depends_on cycle: ${cycle.join(', ')}` },
+        merge_candidates: [],
+        warnings: [],
+    };
+}

package/pp-core/bin/lib/planning-workspace.cjs

@@ -72,6 +72,28 @@ function planningDir(cwd, ws, project) {
 function planningRoot(cwd) {
     return node_path_1.default.join(cwd, '.planning');
 }
+/**
+ * THE owner of "where the milestone record lives", given an already-resolved
+ * planning base (`planningDir(cwd)` / `planningPaths(cwd).planning`).
+ *
+ * Phase 12 CARRY-04 moved the milestone-record WRITER into the workstream (a
+ * milestone record belongs beside the ROADMAP it closes) but left the readers
+ * joining their own copy of the location, some of them at the repo root — so a
+ * workstream-archived milestone was invisible to `init.new-milestone`,
+ * `history-digest`, `phases list --include-archived` and every verb that
+ * resolves a phase through `findPhaseInternal`. Callers that hold a cwd should
+ * read `planningPaths(cwd).milestones` / `.milestonesArchive`; callers that
+ * already hold a planning base (verify.cjs, phase.cjs) call this directly.
+ * Nobody re-derives the two names (phase 12, CARRY-05).
+ *
+ * @param planningBase - absolute path to the .planning workspace root
+ */
+function milestonePathsFor(planningBase) {
+    return {
+        milestones: node_path_1.default.join(planningBase, 'MILESTONES.md'),
+        milestonesArchive: node_path_1.default.join(planningBase, 'milestones'),
+    };
+}
 function planningPaths(cwd, ws) {
     const base = planningDir(cwd, ws);
     return {
@@ -82,8 +104,37 @@ function planningPaths(cwd, ws) {
         config: node_path_1.default.join(base, 'config.json'),
         phases: node_path_1.default.join(base, 'phases'),
         requirements: node_path_1.default.join(base, 'REQUIREMENTS.md'),
+        ...milestonePathsFor(base),
     };
 }
+/**
+ * THE owner of "which PROJECT.md answers for this cwd" — for READS and
+ * existence checks (quick 261007-jkl, D1; todo "init project_exists is root
+ * hardcoded").
+ *
+ * PROJECT.md is a SHARED file by design: migrateToWorkstreams (workstream.cts)
+ * leaves it at the project level when it moves ROADMAP/STATE/phases into
+ * .planning/workstreams/<name>/. So under a workstream the answer is the
+ * workstream's OWN PROJECT.md when one exists, else the SHARED one:
+ *   own    = planningPaths(cwd).project — honours GSD_WORKSTREAM and GSD_PROJECT
+ *   shared = planningDir(cwd, null)/PROJECT.md — workstream segment absent,
+ *            GSD_PROJECT still honoured
+ * When neither exists the shared path is named, which is where /pp-new-project
+ * creates it. In flat mode own === shared. Both candidates come from
+ * planningDir, so a traversing GSD_WORKSTREAM / GSD_PROJECT throws before any
+ * path is named.
+ *
+ * planningPaths().project is deliberately left as it is: it is the write
+ * target for callers that create or rewrite the workstream's own file.
+ */
+function resolveProjectFile(cwd) {
+    const own = planningPaths(cwd).project;
+    const shared = node_path_1.default.join(planningDir(cwd, null), 'PROJECT.md');
+    if (own !== shared && node_fs_1.default.existsSync(own)) {
+        return { path: own, exists: true, scope: 'workstream' };
+    }
+    return { path: shared, exists: node_fs_1.default.existsSync(shared), scope: 'shared' };
+}
 /**
  * @param cwd
  * @param fn - callback to run while holding the lock
@@ -238,6 +289,8 @@ module.exports = {
     planningDir,
     planningRoot,
     planningPaths,
+    resolveProjectFile,
+    milestonePathsFor,
     withPlanningLock,
     getActiveWorkstream,
     setActiveWorkstream,

package/pp-core/bin/lib/platform-bindings.cjs

@@ -34,8 +34,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MACHINE_SPECIFIC_CLONE_TARGET_PATTERNS = exports.VAULT_REPO_PATTERN_SOURCE = exports.PLATFORM_REPO_PATTERN_SOURCE = exports.CONTRACT_SCHEMA_VERSION = void 0;
+exports.BINDINGS_COORDINATE_FIELDS = exports.MACHINE_SPECIFIC_CLONE_TARGET_PATTERNS = exports.VAULT_REPO_PATTERN_SOURCE = exports.PLATFORM_REPO_PATTERN_SOURCE = exports.CONTRACT_SCHEMA_VERSION = void 0;
 exports.validateBindings = validateBindings;
+exports.redactBindingsForEmission = redactBindingsForEmission;
 exports.cmdPlatformBindings = cmdPlatformBindings;
 exports.cmdValidateBindings = cmdValidateBindings;
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -208,6 +209,33 @@ function validateBindings(o) {
     }
     return { valid: errors.length === 0, errors, warnings };
 }
+/**
+ * Pack 6 D-07: the `.platform-bindings.json` fields that carry a remote repo
+ * coordinate (and so the fields a credential can ride in). Hosts are not
+ * listed: a host is a bare host by contract and is read for real use.
+ */
+exports.BINDINGS_COORDINATE_FIELDS = Object.freeze(['platform.repo', 'client.vaultRepo']);
+/**
+ * Emission-only: a copy of a bindings-shaped object with every coordinate field
+ * routed through the one owner (`redactCloneTarget`, src/vault.cts — lazily
+ * required so this module's load graph is unchanged). Never use the result for
+ * a write, a comparison, or a clone.
+ */
+function redactBindingsForEmission(obj) {
+    if (!isObject(obj))
+        return obj;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { redactCloneTarget } = require('./vault.cjs');
+    const copy = JSON.parse(JSON.stringify(obj));
+    for (const field of exports.BINDINGS_COORDINATE_FIELDS) {
+        const [ns, key] = field.split('.');
+        const parent = copy[ns];
+        if (isObject(parent) && typeof parent[key] === 'string') {
+            parent[key] = redactCloneTarget(parent[key]);
+        }
+    }
+    return copy;
+}
 /**
  * Reader handler for `pp-tools query platform-bindings`.
  *
@@ -254,7 +282,9 @@ function cmdPlatformBindings(cwd, args, raw) {
         return;
     }
     // present + valid → echo the bindings under a present flag.
-    output(Object.assign({ present: true }, parsed), raw);
+    // Pack 6 D-07: the remote coordinate fields are emitted display-safe; every
+    // other field is verbatim. The file on disk keeps the raw value.
+    output(Object.assign({ present: true }, redactBindingsForEmission(parsed)), raw);
 }
 // Anchored regex for `?ref=` values in module source lines (T-07-04: untrusted text,
 // no YAML dependency, no shell-eval).

package/pp-core/bin/lib/profile-output.cjs

@@ -28,7 +28,12 @@ const { loadConfig } = configLoader;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const runtime_homes_cjs_1 = require("./runtime-homes.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+// The start-command fallback uses the pp-named alias (same function).
+const runtime_slash_cjs_2 = require("./runtime-slash.cjs");
 const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
+const planningWorkspace = require("./planning-workspace.cjs");
+const { resolveProjectFile } = planningWorkspace;
 // ─── Constants ────────────────────────────────────────────────────────────────
 const DIMENSION_KEYS = [
     'communication_style', 'decision_speed', 'explanation_depth',
@@ -189,7 +194,7 @@ const CLAUDE_INSTRUCTIONS = {
 // depends on the runtime resolved from the project's config/env.
 function buildClaudeMdFallbacks(runtime) {
     return {
-        project: `Project not yet initialized. Run ${String((0, runtime_slash_cjs_1.formatGsdSlash)('new-project', runtime))} to set up.`,
+        project: `Project not yet initialized. Run ${String((0, runtime_slash_cjs_2.formatPpSlash)('init', runtime))} to set up.`,
         stack: 'Technology stack not yet documented. Will populate after codebase mapping or first phase.',
         conventions: 'Conventions not yet established. Will populate as patterns emerge during development.',
         architecture: 'Architecture not yet mapped. Follow existing patterns found in the codebase.',
@@ -300,7 +305,9 @@ function extractMarkdownSection(content, sectionName) {
 // ─── CLAUDE.md Section Generators ─────────────────────────────────────────────
 function generateProjectSection(cwd) {
     const fallbacks = buildClaudeMdFallbacks((0, runtime_slash_cjs_1.resolveRuntime)(cwd));
-    const projectPath = node_path_1.default.join(cwd, '.planning', 'PROJECT.md');
+    // D1 (261007-jkl): the PROJECT.md that answers for this cwd (workstream's own, else
+    // the shared one; GSD_PROJECT honoured) — this used to be a fixed repo-root join.
+    const projectPath = resolveProjectFile(cwd).path;
     const content = (0, shell_command_projection_cjs_1.platformReadSync)(projectPath);
     if (!content) {
         return { content: fallbacks['project'], source: 'PROJECT.md', linkPath: null, hasFallback: true };
@@ -330,7 +337,8 @@ function generateProjectSection(cwd) {
     if (parts.length === 0) {
         return { content: fallbacks['project'], source: 'PROJECT.md', linkPath: null, hasFallback: true };
     }
-    return { content: parts.join('\n\n'), source: 'PROJECT.md', linkPath: '.planning/PROJECT.md', hasFallback: false };
+    const linkPath = node_path_1.default.relative(cwd, projectPath).split(node_path_1.default.sep).join('/');
+    return { content: parts.join('\n\n'), source: 'PROJECT.md', linkPath, hasFallback: false };
 }
 function generateStackSection(cwd) {
     const fallbacks = buildClaudeMdFallbacks((0, runtime_slash_cjs_1.resolveRuntime)(cwd));