@pareto4/pp-core 1.5.3 → 1.6.0

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

@@ -0,0 +1,336 @@
+"use strict";
+/**
+ * Platform Bindings — reader + hand-rolled validator for .platform-bindings.json
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/platform-bindings.cjs`; do NOT
+ * hand-edit the compiled output. Behaviour is LOCKED by
+ * `tests/platform-bindings.test.cjs` (the reader behaviour matrix + the
+ * schema↔validator coupling assertion).
+ *
+ * BIND-02 (D-08 single-file schema check, D-03 lenient validation):
+ *   - `cmdPlatformBindings` reads `.platform-bindings.json` at the repo root
+ *     (NOT under .planning/). An absent file is INERT — it emits
+ *     {present:false} on exit 0 and NEVER calls error(). This makes the
+ *     binding contract opt-in: every downstream Pareto behaviour can read it
+ *     unconditionally and branch on `present`.
+ *   - Malformed JSON is the ONLY hard-error path: it calls error() with
+ *     ERROR_REASON.PLATFORM_BINDINGS_PARSE_FAILED (exit 1).
+ *   - `--validate` returns the validation RESULT as data ({valid, errors}) on
+ *     exit 0 — a validation verdict is never a process error.
+ *   - `validateBindings` is hand-rolled (no ajv, zero new deps). It hard-checks
+ *     ONLY the load-bearing core (schemaVersion, platform.repo, platform.tag)
+ *     per D-03; provisional namespaces are validated leniently — an unknown or
+ *     missing namespace never makes the object invalid.
+ *
+ * The core regexes below MUST mirror the `pattern` strings in
+ * `schemas/platform-bindings.schema.json`; the schema↔validator coupling test
+ * machine-enforces this so neither side can drift silently.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateBindings = validateBindings;
+exports.cmdPlatformBindings = cmdPlatformBindings;
+exports.cmdValidateBindings = cmdValidateBindings;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, error, ERROR_REASON } = io;
+const project_root_cjs_1 = require("./project-root.cjs");
+const semver_compare_cjs_1 = require("./semver-compare.cjs");
+// Core load-bearing patterns (D-01). These MUST mirror the `pattern` fields in
+// schemas/platform-bindings.schema.json — the coupling test fails if they drift.
+const SCHEMA_VERSION_RE = /^\d+\.\d+\.\d+$/;
+const PLATFORM_REPO_RE = /^[\w.-]+\/[\w.-]+$/;
+const PLATFORM_TAG_RE = /^v\d+\.\d+\.\d+/;
+// Provisional namespace pattern (lenient): only enforced if client.slug is present.
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Hand-rolled validator (no ajv). Hard-checks ONLY the frozen core per D-03;
+ * provisional namespaces are validated leniently. Returns the verdict as data.
+ *
+ * @param o - The parsed binding object (untrusted shape).
+ * @returns `{ valid, errors }` — `errors` names each failing core field.
+ */
+function validateBindings(o) {
+    const errors = [];
+    if (!isObject(o)) {
+        return { valid: false, errors: ['root: expected a JSON object'] };
+    }
+    // schemaVersion — required, semver triplet.
+    if (typeof o.schemaVersion !== 'string' || !SCHEMA_VERSION_RE.test(o.schemaVersion)) {
+        errors.push('schemaVersion: missing or not a semver triplet (e.g. "1.0.0")');
+    }
+    // platform — required object with repo + tag.
+    if (!isObject(o.platform)) {
+        errors.push('platform: missing or not an object');
+    }
+    else {
+        const platform = o.platform;
+        if (typeof platform.repo !== 'string' || !PLATFORM_REPO_RE.test(platform.repo)) {
+            errors.push('platform.repo: missing or not a "group/project" path');
+        }
+        if (typeof platform.tag !== 'string' || !PLATFORM_TAG_RE.test(platform.tag)) {
+            errors.push('platform.tag: missing or not a "v<semver>" tag');
+        }
+    }
+    // Provisional namespaces — lenient. A missing/unknown namespace is fine; only
+    // a PRESENT slug field that is malformed is flagged (it never gates on absence).
+    if (isObject(o.client) && o.client.slug !== undefined) {
+        if (typeof o.client.slug !== 'string' || !SLUG_RE.test(o.client.slug)) {
+            errors.push('client.slug: present but not a url-safe lowercase slug');
+        }
+    }
+    // IN-03: project.slug — symmetric lenient check matching client.slug behaviour.
+    // The schema defines the same ^[a-z0-9][a-z0-9-]*$ pattern for both fields.
+    if (isObject(o.project) && o.project.slug !== undefined) {
+        if (typeof o.project.slug !== 'string' || !SLUG_RE.test(o.project.slug)) {
+            errors.push('project.slug: present but not a url-safe lowercase slug');
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Reader handler for `pp-tools query platform-bindings`.
+ *
+ * Behaviour matrix (locked by tests/platform-bindings.test.cjs):
+ *   absent file                  → output({present:false})            exit 0 (inert)
+ *   present + valid JSON          → output({present:true, ...bindings}) exit 0
+ *   present + --validate          → output(validateBindings(obj))      exit 0
+ *   malformed JSON                → error(..., PARSE_FAILED)           exit 1
+ *
+ * @param cwd  - Working directory; resolved to repo root via findProjectRoot.
+ * @param args - Handler-local args (already sliced past the subcommand name).
+ * @param raw  - Raw output mode (passed through to output()).
+ */
+function cmdPlatformBindings(cwd, args, raw) {
+    let root;
+    try {
+        root = (0, project_root_cjs_1.findProjectRoot)(cwd) || cwd;
+    }
+    catch {
+        root = cwd;
+    }
+    const bindingsPath = node_path_1.default.join(root, '.platform-bindings.json');
+    // Absent → inert. NEVER error() here; this is the opt-in default path.
+    if (!node_fs_1.default.existsSync(bindingsPath)) {
+        output({ present: false }, raw);
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(node_fs_1.default.readFileSync(bindingsPath, 'utf-8'));
+    }
+    catch (err) {
+        // IN-02: TOCTOU guard — if the file was deleted between existsSync and readFileSync,
+        // route to the inert absent path rather than emitting a misleading parse-failure error.
+        if (err.code === 'ENOENT') {
+            output({ present: false }, raw);
+            return;
+        }
+        error('Failed to parse .platform-bindings.json: ' + err.message, ERROR_REASON.PLATFORM_BINDINGS_PARSE_FAILED);
+        return; // unreachable — error() exits; kept for type-narrowing clarity.
+    }
+    if (args.includes('--validate')) {
+        output(validateBindings(parsed), raw);
+        return;
+    }
+    // present + valid → echo the bindings under a present flag.
+    output(Object.assign({ present: true }, parsed), raw);
+}
+// Anchored regex for `?ref=` values in module source lines (T-07-04: untrusted text,
+// no YAML dependency, no shell-eval).
+const GITLAB_CI_MODULE_REF_RE = /\?ref=([^\s'"&)\]]+)/g;
+/**
+ * Extracts `ref:` values that belong to the top-level `include:` block in a
+ * .gitlab-ci.yml file, using a stateful line-scan.
+ *
+ * APPROXIMATION: Parses YAML structure via indentation tracking — handles the
+ * common block-sequence form (`include: [- project: ... ref: ...]`). It does NOT
+ * capture `ref:` values from `trigger:`, `needs:`, or other non-include stanzas,
+ * because those appear under job-level keys (indent = 0) which close the include
+ * context. May mis-classify exotic YAML (flow mappings, anchors, multi-document
+ * files). Uses no YAML parser to avoid runtime dependencies (T-07-04).
+ *
+ * @param content - Raw string content of the .gitlab-ci.yml file.
+ * @returns Array of `ref:` values found inside the `include:` block.
+ */
+function extractGitlabCiIncludeRefs(content) {
+    const refs = [];
+    const lines = content.split('\n');
+    let inIncludeBlock = false;
+    const REF_LINE_RE = /^ref:\s+['"]?([^\s'"#,\]]+)['"]?/;
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        // Skip blank lines and comment lines — they do not change YAML context.
+        if (trimmed.length === 0 || trimmed.startsWith('#'))
+            continue;
+        const indent = line.length - trimmed.length;
+        // A new top-level key (indent = 0) either enters or exits the include block.
+        if (indent === 0) {
+            inIncludeBlock = trimmed === 'include:' || trimmed.startsWith('include:');
+            continue;
+        }
+        // Within the include block, capture any `ref: <value>` line.
+        if (inIncludeBlock) {
+            const m = trimmed.match(REF_LINE_RE);
+            if (m) {
+                refs.push(m[1].trim());
+            }
+        }
+    }
+    return refs;
+}
+/**
+ * Pin-site consistency check for `pp-tools query validate-bindings` (BIND-03).
+ *
+ * Reads the REAL on-disk `.gitlab-ci.yml` include `ref:` and module `?ref=` values (D-06),
+ * cross-checks them against `platform.tag` in `.platform-bindings.json`.
+ *
+ * Behaviour matrix (locked by tests/platform-bindings.test.cjs):
+ *   absent .platform-bindings.json    → output({present:false})                  exit 0 (inert, D-07)
+ *   internal mismatch (>1 distinct)   → output({..., status:'block'})            exit 0 (D-04)
+ *   all-agree, behind --latest-tag    → output({..., status:'warn'})             exit 0 (D-05)
+ *   all-agree, at/ahead of latest     → output({..., status:'pass'})             exit 0
+ *
+ * Threat mitigations:
+ *   T-07-04  Anchored regex on `ref:`/`?ref=`; file content is untrusted text — never shell-eval.
+ *   T-07-05  Unresolved/offline remote is a soft note, never a hard block; caller passes
+ *            `--latest-tag <tag>` when a network lookup succeeded; absent = skip drift check.
+ *   T-07-06  `compareSemverCore === 0` normalises v-prefix differences; literal diff surfaced in `sites`.
+ *
+ * @param cwd  - Working directory; resolved to repo root via findProjectRoot.
+ * @param args - Handler-local args (already sliced past the subcommand name).
+ *               Accepts optional `--latest-tag <tag>` for D-05 drift classification.
+ * @param raw  - Raw output mode (passed through to output()).
+ */
+function cmdValidateBindings(cwd, args, raw) {
+    let root;
+    try {
+        root = (0, project_root_cjs_1.findProjectRoot)(cwd) || cwd;
+    }
+    catch {
+        root = cwd;
+    }
+    const bindingsPath = node_path_1.default.join(root, '.platform-bindings.json');
+    // D-07: absent → inert. NEVER error() here; this is the opt-in default path.
+    if (!node_fs_1.default.existsSync(bindingsPath)) {
+        output({ present: false }, raw);
+        return;
+    }
+    // Parse the bindings file (malformed → hard error, same rule as the reader).
+    let parsed;
+    try {
+        parsed = JSON.parse(node_fs_1.default.readFileSync(bindingsPath, 'utf-8'));
+    }
+    catch (err) {
+        // IN-02: TOCTOU guard — if the file was deleted between existsSync and readFileSync,
+        // route to the inert absent path rather than emitting a misleading parse-failure error.
+        if (err.code === 'ENOENT') {
+            output({ present: false }, raw);
+            return;
+        }
+        error('Failed to parse .platform-bindings.json: ' + err.message, ERROR_REASON.PLATFORM_BINDINGS_PARSE_FAILED);
+        return; // unreachable — error() exits; kept for type-narrowing clarity.
+    }
+    // Extract canonical platform.tag (T) as the first pin-site value.
+    const bindingsObj = parsed;
+    const platform = isObject(bindingsObj.platform) ? bindingsObj.platform : null;
+    const bindingsTag = typeof platform?.tag === 'string' ? platform.tag.trim() : '';
+    // WR-01: guard on a missing/empty canonical tag — without it, the function
+    // would fall through to emit status:'pass' with zero pin-sites, misleadingly
+    // signalling a correct pin on a binding that validateBindings would reject.
+    const sites = {};
+    if (!bindingsTag) {
+        output({
+            present: true,
+            consistent: false,
+            status: 'block',
+            message: 'platform.tag is missing or empty in .platform-bindings.json — run --validate to diagnose',
+            sites,
+        }, raw);
+        return;
+    }
+    sites['platform.tag'] = bindingsTag;
+    // D-06: read the REAL on-disk .gitlab-ci.yml and extract ref values.
+    const gitlabCiPath = node_path_1.default.join(root, '.gitlab-ci.yml');
+    if (node_fs_1.default.existsSync(gitlabCiPath)) {
+        const ciContent = node_fs_1.default.readFileSync(gitlabCiPath, 'utf-8');
+        // Extract `ref:` values from include blocks using a stateful line-scan (WR-02).
+        // Avoids false positives from `trigger:`, `needs:`, and other non-include stanzas.
+        const includeRefs = extractGitlabCiIncludeRefs(ciContent);
+        for (let refIdx = 0; refIdx < includeRefs.length; refIdx++) {
+            const key = refIdx === 0
+                ? '.gitlab-ci.yml include ref'
+                : `.gitlab-ci.yml include ref[${refIdx + 1}]`;
+            sites[key] = includeRefs[refIdx];
+        }
+        // Extract `?ref=` values from module source lines.
+        const moduleRefRe = new RegExp(GITLAB_CI_MODULE_REF_RE.source, GITLAB_CI_MODULE_REF_RE.flags);
+        let m;
+        let modIdx = 0;
+        while ((m = moduleRefRe.exec(ciContent)) !== null) {
+            modIdx++;
+            const key = modIdx === 1
+                ? '.gitlab-ci.yml module ?ref'
+                : `.gitlab-ci.yml module ?ref[${modIdx}]`;
+            sites[key] = m[1].trim();
+        }
+    }
+    // Build distinct semver set across all pin-sites.
+    // `compareSemverCore === 0` normalises v-prefix differences (T-07-06).
+    const tagValues = Object.values(sites).filter(Boolean);
+    const distinctTags = [];
+    for (const tag of tagValues) {
+        const isDuplicate = distinctTags.some((existing) => (0, semver_compare_cjs_1.compareSemverCore)(tag, existing) === 0);
+        if (!isDuplicate) {
+            distinctTags.push(tag);
+        }
+    }
+    // D-04: hard BLOCK when >1 semver-distinct element across the pin-sites.
+    if (distinctTags.length > 1) {
+        const siteDiff = Object.entries(sites)
+            .map(([k, v]) => `${k}=${v}`)
+            .join(', ');
+        output({
+            present: true,
+            consistent: false,
+            status: 'block',
+            message: `Pin-site tags disagree: ${siteDiff}`,
+            sites,
+        }, raw);
+        return;
+    }
+    // D-05: soft WARN when all sites agree but are behind the latest stable tag.
+    // The caller passes `--latest-tag <tag>` when a network ls-remote succeeded.
+    // Absent or unresolved remote → skip drift check (T-07-05: never hard-block).
+    const latestTagArgIdx = args.indexOf('--latest-tag');
+    const latestTag = latestTagArgIdx >= 0 ? args[latestTagArgIdx + 1] : undefined;
+    if (latestTag && (0, semver_compare_cjs_1.isStableTripletSemver)(latestTag) && bindingsTag) {
+        const drift = (0, semver_compare_cjs_1.compareSemverCore)(bindingsTag, latestTag);
+        if (drift < 0) {
+            // Strictly behind latest stable.
+            output({
+                present: true,
+                consistent: true,
+                status: 'warn',
+                message: `All pin-sites agree on ${bindingsTag}, but latest stable is ${latestTag}`,
+                sites,
+            }, raw);
+            return;
+        }
+    }
+    // All sites agree, not strictly behind latest → pass.
+    output({
+        present: true,
+        consistent: true,
+        status: 'pass',
+        sites,
+    }, raw);
+}

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

@@ -200,14 +200,14 @@ function buildClaudeMdFallbacks(runtime) {
 const SKILL_SEARCH_DIRS = ['.claude/skills', '.agents/skills', '.cursor/skills', '.github/skills', '.codex/skills'];
 function buildClaudeMdWorkflowEnforcement(runtime) {
     return [
-        'Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.',
+        'Before using Edit, Write, or other file-changing tools, start work through a pp-core command so planning artifacts and execution context stay in sync.',
         '',
         'Use these entry points:',
         `- \`${String((0, runtime_slash_cjs_1.formatGsdSlash)('quick', runtime))}\` for small fixes, doc updates, and ad-hoc tasks`,
         `- \`${String((0, runtime_slash_cjs_1.formatGsdSlash)('debug', runtime))}\` for investigation and bug fixing`,
         `- \`${String((0, runtime_slash_cjs_1.formatGsdSlash)('execute-phase', runtime))}\` for planned phase work`,
         '',
-        'Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.',
+        'Do not make direct repo edits outside a pp-core workflow unless the user explicitly asks to bypass it.',
     ].join('\n');
 }
 function buildClaudeMdProfilePlaceholder(runtime) {
@@ -414,7 +414,7 @@ function generateArchitectureSection(cwd) {
 function generateWorkflowSection(cwd) {
     return {
         content: buildClaudeMdWorkflowEnforcement((0, runtime_slash_cjs_1.resolveRuntime)(cwd)),
-        source: 'GSD defaults',
+        source: 'pp-core defaults',
         linkPath: null,
         hasFallback: false,
     };
@@ -988,7 +988,7 @@ function cmdGenerateClaudeMd(cwd, options, raw) {
         conventions: '## Conventions',
         architecture: '## Architecture',
         skills: '## Project Skills',
-        workflow: '## GSD Workflow Enforcement',
+        workflow: '## pp-core Workflow Enforcement',
     };
     const generated = {};
     const sectionsGenerated = [];
@@ -1061,13 +1061,14 @@ function cmdGenerateClaudeMd(cwd, options, raw) {
         (0, shell_command_projection_cjs_1.platformEnsureDir)(node_path_1.default.dirname(outputPath));
         (0, shell_command_projection_cjs_1.platformWriteSync)(outputPath, existingContent);
     }
-    else if (!/<!-- PP:[a-z]+-start/.test(existingContent) && !options.force) {
+    else if (!/<!-- PP:[a-z][a-z-]*-start/.test(existingContent) && !options.force) {
         // #1098: the target instruction file already exists and contains NO GSD
         // section markers — it is a hand-crafted CLAUDE.md/AGENTS.md, not a
         // GSD-managed one. Do NOT clobber it with generated project documentation
         // (broad project detail belongs in PROJECT.md / REQUIREMENTS.md, which GSD
         // already owns). Leave the file untouched and report a skip; `--force`
         // overwrites intentionally.
+        // Note: [a-z][a-z-]* matches section names with hyphens (e.g. client-context)
         output({
             claude_md_path: outputPath,
             action: 'skipped',
@@ -1153,12 +1154,226 @@ function cmdGenerateClaudeMd(cwd, options, raw) {
     };
     output(result, raw, undefined);
 }
+// ─── Client Context Block ─────────────────────────────────────────────────────
+/**
+ * Sanitize a field value so pasted content cannot break the managed block.
+ * T-09-01: Neutralizes:
+ *   - any `<!-- PP:` marker sequence (any section name — start or end fragment)
+ *   - any line starting with `### ` (would forge a field subheading)
+ *
+ * WR-01: Broadened from `PP:client-context` to `PP:[a-z][a-z-]*` so that a
+ * pasted value containing e.g. `<!-- PP:project-end -->` cannot corrupt another
+ * section's `updateSection` / `generate-claude-md` call later.
+ *
+ * Neutralization strategy for `<!-- PP:` sequences: a zero-width space (U+200B)
+ * is inserted INSIDE the comment opener (`<` + ZWS + `!--`) rather than prepended
+ * before it. This breaks the literal substring `<!--` so that `String.indexOf` and
+ * `String.includes` can no longer find `<!-- PP:...` in the neutralized value —
+ * which is required because `extractSectionContent` / `updateSection` use
+ * `fileContent.indexOf(endMarker)` to locate section boundaries. A ZWS *prefix*
+ * before `<!--` (approach used by earlier code) still left `<!-- PP:...` as a
+ * findable substring, allowing the injection to truncate block reads.
+ *
+ * The inserted ZWS is invisible in rendered text and does not match the replacement
+ * pattern on a subsequent sanitization pass, so round-trip re-writes are idempotent.
+ *
+ * Neutralization for `### ` uses a ZWS *prefix* (before `### `), which is the
+ * correct approach because `parseClientContextFields` checks for lines that EQUAL
+ * the heading string exactly — `​### Client` !== `### Client`.
+ */
+function sanitizeClientContextField(value) {
+    // Neutralize any PP managed-block marker: break `<!--` by inserting ZWS inside it
+    // so the literal substring `<!-- PP:...` no longer appears in the neutralized value.
+    let result = value.replace(/(<!--)(\s*PP:[a-z][a-z-]*)/gi, '<​!--$2');
+    // Neutralize lines beginning with `### ` (subheading injection)
+    result = result.replace(/^(### )/gm, '​$1');
+    return result;
+}
+/**
+ * Parse the five field values from an extracted client-context block body.
+ * Uses `### ` anchor scan on the block content (T-09-03: never whole-file).
+ * Returns an object with the five field keys, or null if the block is empty.
+ *
+ * CR-01: The `### Client` section is stored under `client_name_slug` for the
+ * combined block, but `client_name` and `client_slug` are also extracted as
+ * separate keys from the `**Name:**` / `**Slug:**` lines within that section
+ * so that `init.md` edit-on-re-run can read them via `o.client_name` /
+ * `o.client_slug` without breakage.
+ */
+function parseClientContextFields(blockContent) {
+    const SUBHEADINGS = [
+        { key: 'client_name_slug', heading: '### Client' },
+        { key: 'coding_standards', heading: '### Coding Standards' },
+        { key: 'architecture_patterns', heading: '### Architecture Patterns' },
+        { key: 'ui_brand_conventions', heading: '### UI / Brand Conventions' },
+        { key: 'definition_of_done', heading: '### Definition of Done' },
+    ];
+    const result = {};
+    // WR-03: strip trailing \r so CRLF files don't break exact-equality heading matches
+    const lines = blockContent.split('\n').map(l => l.replace(/\r$/, ''));
+    for (let i = 0; i < SUBHEADINGS.length; i++) {
+        const { key, heading } = SUBHEADINGS[i];
+        const nextHeading = i + 1 < SUBHEADINGS.length ? SUBHEADINGS[i + 1].heading : null;
+        const startIdx = lines.findIndex(l => l === heading);
+        if (startIdx === -1) {
+            result[key] = '';
+            continue;
+        }
+        const sectionLines = [];
+        for (let j = startIdx + 1; j < lines.length; j++) {
+            if (nextHeading && lines[j] === nextHeading)
+                break;
+            if (!nextHeading && /^<!-- PP:client-context-end/.test(lines[j]))
+                break;
+            sectionLines.push(lines[j]);
+        }
+        result[key] = sectionLines.join('\n').trim();
+        // CR-01: for the ### Client section, also extract client_name and client_slug
+        // as separate keys by parsing the **Name:** / **Slug:** lines within it.
+        if (key === 'client_name_slug') {
+            const nameLine = sectionLines.find(l => l.startsWith('**Name:**'));
+            result['client_name'] = nameLine ? nameLine.replace(/^\*\*Name:\*\*\s*/, '').trim() : '';
+            const slugLine = sectionLines.find(l => l.startsWith('**Slug:**'));
+            result['client_slug'] = slugLine ? slugLine.replace(/^\*\*Slug:\*\*\s*/, '').trim() : '';
+        }
+    }
+    // WR-02: return null when no recognized subheadings were found so the caller's
+    // `if (!fields)` guard correctly emits { present: false } for empty/hand-edited blocks
+    const hasAnyField = Object.values(result).some(v => v !== '');
+    return hasAnyField ? result : null;
+}
+function cmdGenerateClientContext(cwd, options, raw) {
+    // Resolve target path using same config-driven logic as cmdGenerateClaudeMd
+    let configClaudeMdPath = './.claude/CLAUDE.md';
+    let config = {};
+    try {
+        config = loadConfig(cwd);
+        if (config['claude_md_path'])
+            configClaudeMdPath = config['claude_md_path'];
+        // Runtime-awareness: Codex projects write to AGENTS.md, not CLAUDE.md
+        const effectiveRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME'], config['runtime']);
+        if (!options.output && effectiveRuntime === 'codex') {
+            configClaudeMdPath = './AGENTS.md';
+        }
+    }
+    catch { /* use default */ }
+    let targetPath;
+    if (options.output) {
+        targetPath = node_path_1.default.isAbsolute(options.output) ? options.output : node_path_1.default.join(cwd, options.output);
+    }
+    else {
+        targetPath = node_path_1.default.isAbsolute(configClaudeMdPath) ? configClaudeMdPath : node_path_1.default.join(cwd, configClaudeMdPath);
+    }
+    // ── --read mode: parse existing block and return field values ───────────────
+    if (options.read) {
+        const fileContent = (0, shell_command_projection_cjs_1.platformReadSync)(targetPath);
+        if (!fileContent) {
+            output({ present: false }, raw, undefined);
+            return;
+        }
+        const blockContent = extractSectionContent(fileContent, 'client-context');
+        if (!blockContent) {
+            output({ present: false }, raw, undefined);
+            return;
+        }
+        const fields = parseClientContextFields(blockContent);
+        if (!fields) {
+            output({ present: false }, raw, undefined);
+            return;
+        }
+        output({ present: true, ...fields }, raw, undefined);
+        return;
+    }
+    // ── --from-json mode: render block and write ────────────────────────────────
+    if (!options.fromJson) {
+        error('--from-json <path> is required (or use --read to read existing block)');
+    }
+    let jsonPath = options.fromJson;
+    if (!node_path_1.default.isAbsolute(jsonPath))
+        jsonPath = node_path_1.default.join(cwd, jsonPath);
+    if (!node_fs_1.default.existsSync(jsonPath))
+        error(`JSON input file not found: ${jsonPath}`);
+    let clientData;
+    const jsonRaw = (0, shell_command_projection_cjs_1.platformReadSync)(jsonPath);
+    try {
+        if (jsonRaw === null)
+            throw new Error(`JSON file not found: ${jsonPath}`);
+        clientData = JSON.parse(jsonRaw);
+    }
+    catch (err) {
+        error(`Failed to parse JSON input: ${err.message}`);
+    }
+    const clientName = sanitizeClientContextField(clientData.client_name || '');
+    const clientSlug = sanitizeClientContextField(clientData.client_slug || '');
+    const codingStandards = sanitizeClientContextField(clientData.coding_standards || '');
+    const archPatterns = sanitizeClientContextField(clientData.architecture_patterns || '');
+    const uiBrand = sanitizeClientContextField(clientData.ui_brand_conventions || '');
+    const dod = sanitizeClientContextField(clientData.definition_of_done || '');
+    const sectionLines = [
+        '<!-- PP:client-context-start -->',
+        '## Client Context & Patterns',
+        '',
+        'When building or validating this project, apply these client patterns:',
+        '',
+        '### Client',
+        '',
+        `**Name:** ${clientName}`,
+        `**Slug:** ${clientSlug}`,
+        '',
+        '### Coding Standards',
+        '',
+        codingStandards,
+        '',
+        '### Architecture Patterns',
+        '',
+        archPatterns,
+        '',
+        '### UI / Brand Conventions',
+        '',
+        uiBrand,
+        '',
+        '### Definition of Done',
+        '',
+        dod,
+        '<!-- PP:client-context-end -->',
+    ];
+    const sectionContent = sectionLines.join('\n');
+    const existingContent = (0, shell_command_projection_cjs_1.platformReadSync)(targetPath);
+    let action;
+    if (existingContent === null) {
+        // File does not exist: create it with the block
+        (0, shell_command_projection_cjs_1.platformEnsureDir)(node_path_1.default.dirname(targetPath));
+        (0, shell_command_projection_cjs_1.platformWriteSync)(targetPath, sectionContent + '\n');
+        action = 'created';
+    }
+    else if (!/<!-- PP:[a-z][a-z-]*-start/.test(existingContent) && !options.force) {
+        // Hand-crafted guard (T-09-02): existing file has no PP markers → skip
+        // Note: [a-z][a-z-]* matches section names with hyphens (e.g. client-context)
+        output({
+            action: 'skipped',
+            claude_md_path: targetPath,
+            reason: 'existing instruction file has no GSD markers (hand-crafted); not overwriting. Pass --force to overwrite.',
+        }, raw, undefined);
+        return;
+    }
+    else {
+        // Replace-or-append idempotently via updateSection
+        const updated = updateSection(existingContent, 'client-context', sectionContent);
+        (0, shell_command_projection_cjs_1.platformWriteSync)(targetPath, updated.content);
+        action = updated.action;
+    }
+    output({ action, claude_md_path: targetPath }, raw, undefined);
+}
 module.exports = {
     cmdWriteProfile,
     cmdProfileQuestionnaire,
     cmdGenerateDevPreferences,
     cmdGenerateClaudeProfile,
     cmdGenerateClaudeMd,
+    cmdGenerateClientContext,
+    updateSection,
+    extractSectionContent,
+    extractMarkdownSection,
     PROFILING_QUESTIONS,
     CLAUDE_INSTRUCTIONS,
 };