@pareto4/pp-core 1.5.0

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

@@ -0,0 +1,399 @@
+"use strict";
+/**
+ * ADR Markdown parser — parses Architecture Decision Record documents into
+ * structured objects for downstream processing (adr command, gap checker, etc.).
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/adr-parser.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const security_cjs_1 = require("./security.cjs");
+const STATUS_REJECT_SET = new Set(['superseded', 'rejected', 'deprecated']);
+const CANONICAL_HEADERS = {
+    status: ['status', 'state', 'lifecycle', 'stage'],
+    goal: [
+        'context',
+        'background',
+        'problem statement',
+        'problem',
+        'situation',
+        'forces',
+        'motivation',
+        'issue',
+        'drivers',
+        'pain points',
+        'story',
+        'setting',
+        'premise',
+        'status quo',
+        'context and problem statement',
+    ],
+    decisions: [
+        'decision',
+        'decisions',
+        'resolution',
+        'conclusion',
+        'choice',
+        'we decided',
+        'direction',
+        'approach',
+        'solution',
+        'outcome',
+        'selected option',
+        'recommendation',
+        'strategy',
+        'decision outcome',
+    ],
+    considered_options: [
+        'considered options',
+        'alternatives',
+        'options',
+        'choices',
+        'candidates',
+        'approaches considered',
+        'variants',
+        'trade-offs',
+        'pros and cons of the options',
+        'discussion',
+    ],
+    risks: [
+        'risks',
+        'trade-offs',
+        'drawbacks',
+        'cost',
+        'tensions',
+        'liabilities',
+        'negative consequences',
+        'side effects',
+    ],
+    success_criteria: [
+        'success criteria',
+        'acceptance criteria',
+        'validation',
+        "how we'll know",
+        'metrics',
+        'kpis',
+        'verification',
+        'test strategy',
+        'compliance',
+        'definition of done',
+        'exit criteria',
+        'positive consequences',
+    ],
+    plan_sequence: [
+        'implementation plan',
+        'implementation notes',
+        'steps',
+        'tasks',
+        'roadmap',
+        'sequence',
+        'migration plan',
+        'plan',
+        'action items',
+        'work breakdown',
+        'phases',
+        'milestones',
+        'stages',
+    ],
+    key_files: [
+        'affected files',
+        'files touched',
+        'surface area',
+        'modules affected',
+        'code locations',
+        'file changes',
+        'diff summary',
+        'touched code',
+    ],
+    out_of_scope: [
+        'out of scope',
+        'non-goals',
+        'excluded',
+        'not in this adr',
+        'out of bounds',
+        "won't do",
+        "won't have",
+        'beyond scope',
+        'anti-goals',
+    ],
+    deferred: [
+        'future work',
+        'deferred',
+        'future',
+        'later',
+        'follow-up',
+        'next steps',
+    ],
+    dependencies: [
+        'dependencies',
+        'depends on',
+        'prerequisites',
+        'sequencing',
+        'order',
+        'blocked by',
+        'cross-cuts',
+        'related adrs',
+        'links',
+        'references',
+        'see also',
+        'upstream',
+        'inbound',
+    ],
+    update: [
+        'update',
+        'revision',
+        'amendment',
+        'locked design',
+        'final decision',
+        'post-grilling',
+        'addendum',
+    ],
+    consequences: [
+        'consequences',
+        'implications',
+        'impact',
+        'what this means',
+        'result',
+    ],
+};
+const CONSEQUENCE_NEGATIVE_HINTS = [
+    'negative',
+    'drawback',
+    'risk',
+    'cost',
+    'liability',
+    'trade-off',
+    'tension',
+    'side effect',
+];
+const CONSEQUENCE_POSITIVE_HINTS = [
+    'positive',
+    'success',
+    'metric',
+    'kpi',
+    'verification',
+    'acceptance',
+    'benefit',
+];
+function normalizeAdrHeader(raw) {
+    const s = typeof raw === 'string' ? raw : '';
+    return s
+        .trim()
+        .toLowerCase()
+        .replace(/[\s:._-]+/g, ' ')
+        .replace(/[^\w\s]/g, '')
+        .trim();
+}
+function classifyHeader(normalizedHeader) {
+    for (const [canonical, synonyms] of Object.entries(CANONICAL_HEADERS)) {
+        for (const synonym of synonyms) {
+            if (normalizedHeader === synonym)
+                return canonical;
+            if (normalizedHeader.startsWith(`${synonym} `))
+                return canonical;
+        }
+    }
+    return null;
+}
+function splitEntries(blockText) {
+    return (typeof blockText === 'string' ? blockText : '')
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => line.replace(/^[-*+]\s+/, '').trim())
+        .filter(Boolean);
+}
+function parseSections(markdown) {
+    const lines = (typeof markdown === 'string' ? markdown : '').split(/\r?\n/);
+    const sections = [];
+    let current = { heading: null, body: [] };
+    for (const line of lines) {
+        const m = line.match(/^#{1,6}\s+(.*)$/);
+        if (m) {
+            if (current.heading || current.body.length)
+                sections.push(current);
+            current = { heading: m[1].trim(), body: [] };
+        }
+        else {
+            current.body.push(line);
+        }
+    }
+    if (current.heading || current.body.length)
+        sections.push(current);
+    return sections;
+}
+function parseStatusFromSections(sections) {
+    for (const section of sections) {
+        const canonical = classifyHeader(normalizeAdrHeader(section.heading));
+        if (canonical !== 'status')
+            continue;
+        const line = splitEntries(section.body.join('\n'))[0] || '';
+        const norm = normalizeAdrHeader(line);
+        if (!norm)
+            return '';
+        if (norm.includes('accepted'))
+            return 'accepted';
+        if (norm.includes('proposed'))
+            return 'proposed';
+        if (norm.includes('superseded'))
+            return 'superseded';
+        if (norm.includes('rejected'))
+            return 'rejected';
+        if (norm.includes('deprecated'))
+            return 'deprecated';
+        return norm;
+    }
+    return '';
+}
+function pushUnique(target, values) {
+    const seen = new Set(target);
+    for (const value of values) {
+        if (!seen.has(value)) {
+            target.push(value);
+            seen.add(value);
+        }
+    }
+}
+function parseConsequences(lines, out) {
+    for (const entry of lines) {
+        const lower = entry.toLowerCase();
+        if (CONSEQUENCE_NEGATIVE_HINTS.some((hint) => lower.includes(hint))) {
+            out.consequences_negative.push(entry);
+            continue;
+        }
+        if (CONSEQUENCE_POSITIVE_HINTS.some((hint) => lower.includes(hint))) {
+            out.consequences_positive.push(entry);
+            continue;
+        }
+        out.consequences_positive.push(entry);
+    }
+}
+function parseAdrMarkdown(markdown, { sourcePath = '', format = 'auto' } = {}) {
+    const sections = parseSections(markdown);
+    const titleLine = (typeof markdown === 'string' ? markdown : '').split(/\r?\n/).find((line) => /^#\s+/.test(line)) || '';
+    const title = titleLine.replace(/^#\s+/, '').trim();
+    const out = {
+        title,
+        status: parseStatusFromSections(sections) || 'accepted',
+        context: '',
+        decisions: [],
+        options_considered: [],
+        consequences_positive: [],
+        consequences_negative: [],
+        out_of_scope: [],
+        deferred: [],
+        dependencies: [],
+        updates: [],
+        source_path: sourcePath,
+        key_files: [],
+        plan_sequence: [],
+        format,
+        unmapped_headers: [],
+    };
+    for (const section of sections) {
+        const heading = section.heading || '';
+        if (!heading)
+            continue;
+        const canonical = classifyHeader(normalizeAdrHeader(heading));
+        const entries = splitEntries(section.body.join('\n'));
+        const prose = section.body.join('\n').trim();
+        if (!canonical) {
+            out.unmapped_headers.push(heading);
+            continue;
+        }
+        switch (canonical) {
+            case 'goal':
+                if (!out.context && prose)
+                    out.context = prose;
+                break;
+            case 'decisions':
+                pushUnique(out.decisions, entries);
+                break;
+            case 'considered_options':
+                pushUnique(out.options_considered, entries);
+                break;
+            case 'risks':
+                pushUnique(out.consequences_negative, entries);
+                break;
+            case 'success_criteria':
+                pushUnique(out.consequences_positive, entries);
+                break;
+            case 'plan_sequence':
+                pushUnique(out.plan_sequence, entries);
+                break;
+            case 'key_files':
+                pushUnique(out.key_files, entries);
+                break;
+            case 'out_of_scope':
+                pushUnique(out.out_of_scope, entries);
+                break;
+            case 'deferred':
+                pushUnique(out.deferred, entries);
+                break;
+            case 'dependencies':
+                pushUnique(out.dependencies, entries);
+                break;
+            case 'update':
+                out.updates.push({ heading, entries });
+                break;
+            case 'consequences':
+                parseConsequences(entries, out);
+                break;
+            default:
+                break;
+        }
+    }
+    return out;
+}
+function shouldRejectAdrStatus(status) {
+    return STATUS_REJECT_SET.has(normalizeAdrHeader(status));
+}
+function parseCliArgs(argv) {
+    const opts = { input: null, format: 'auto', projectDir: process.cwd() };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--input') {
+            opts.input = argv[++i] || null;
+        }
+        else if (arg === '--format') {
+            opts.format = argv[++i] || 'auto';
+        }
+        else if (arg === '--project-dir') {
+            opts.projectDir = argv[++i] || process.cwd();
+        }
+        else {
+            throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    if (!opts.input) {
+        throw new Error('Missing required --input <path>');
+    }
+    return opts;
+}
+function main(argv) {
+    const opts = parseCliArgs(argv);
+    const safePath = (0, security_cjs_1.requireSafePath)(opts.input, node_path_1.default.resolve(opts.projectDir), 'ADR input path', { allowAbsolute: true });
+    const content = node_fs_1.default.readFileSync(safePath, 'utf8');
+    const parsed = parseAdrMarkdown(content, { sourcePath: opts.input ?? undefined, format: opts.format });
+    process.stdout.write(JSON.stringify(parsed, null, 2));
+}
+if (require.main === module) {
+    try {
+        main(process.argv.slice(2));
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${error.message}\n`);
+        process.exit(1);
+    }
+}
+module.exports = {
+    CANONICAL_HEADERS,
+    normalizeAdrHeader,
+    parseAdrMarkdown,
+    shouldRejectAdrStatus,
+};

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

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Agent command router — classify-failure subcommand handler.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/agent-command-router.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, error, ERROR_REASON } = io;
+// ─── Constants ────────────────────────────────────────────────────────────────
+const QUOTA_SENTINELS = [
+    '429',
+    'usage_limit_reached',
+    'usage limit',
+    'rate limit',
+    'rate-limited',
+    'rate_limit',
+    'resource_exhausted',
+    'quota',
+    'too many requests',
+    'exceeded your',
+];
+const CLASSIFY_HANDOFF_SENTINEL = 'classifyhandoffifneeded is not defined';
+// ─── Implementation ───────────────────────────────────────────────────────────
+function parseRetryAfter(body) {
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    const match = String(body ?? '').match(/\bretry[-_ ]after[:\s]+(\d+)\b/i);
+    if (!match)
+        return undefined;
+    const seconds = Number.parseInt(match[1], 10);
+    return Number.isFinite(seconds) ? seconds : undefined;
+}
+function classifyAgentFailure(body) {
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    const normalized = String(body ?? '').toLowerCase();
+    if (normalized.trim() === '') {
+        return { class: 'unknown-failure' };
+    }
+    for (const sentinel of QUOTA_SENTINELS) {
+        if (normalized.includes(sentinel)) {
+            const retryAfterSeconds = parseRetryAfter(body);
+            return retryAfterSeconds === undefined
+                ? { class: 'quota-exceeded', sentinel }
+                : { class: 'quota-exceeded', sentinel, retryAfterSeconds };
+        }
+    }
+    if (normalized.includes(CLASSIFY_HANDOFF_SENTINEL)) {
+        return {
+            class: 'classify-handoff-bug',
+            sentinel: CLASSIFY_HANDOFF_SENTINEL,
+        };
+    }
+    return { class: 'unknown-failure' };
+}
+function routeAgentCommand({ args, raw }) {
+    const subcommand = args[1];
+    if (subcommand !== 'classify-failure') {
+        error('Unknown agent subcommand. Available: classify-failure', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    }
+    const bodyArgs = args.slice(2).filter((arg) => arg !== '--');
+    output(classifyAgentFailure(bodyArgs.join(' ')), raw, undefined);
+}
+module.exports = {
+    classifyAgentFailure,
+    routeAgentCommand,
+};

package/pp-core/bin/lib/agent-install-check.cjs

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Agent Install Check — moved from core.cts (ADR-857 T0 #1268 phase rehome-core-squatters).
+ *
+ * Owns:
+ *   - getAgentsDir(runtime?): string
+ *   - checkAgentsInstalled(runtime?): AgentsInstalledResult
+ *
+ * The core.cjs re-export spine was retired in epic #1267; callers import
+ * these symbols from agent-install-check.cjs directly.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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 modelProfiles = require("./model-profiles.cjs");
+const { MODEL_PROFILES } = modelProfiles;
+const runtime_homes_cjs_1 = require("./runtime-homes.cjs");
+/**
+ * Resolve the agents directory for the given runtime.
+ *
+ * Priority:
+ *   1. GSD_AGENTS_DIR env var (explicit override, any runtime)
+ *   2. For claude runtime: __dirname-relative path (agents/ sibling of gsd-core/)
+ *      This is correct for both repo runs and real installs (the runtime config dir's
+ *      agents/ folder) because gsd-tools.cjs lives inside gsd-core/bin/ in both cases.
+ *   3. For non-claude runtimes: getGlobalConfigDir(runtime)/agents
+ *
+ * @param runtime - the active runtime name; defaults to GSD_RUNTIME env, then 'claude'
+ */
+function getAgentsDir(runtime) {
+    if (process.env['GSD_AGENTS_DIR']) {
+        return process.env['GSD_AGENTS_DIR'];
+    }
+    const resolved = runtime ?? (process.env['GSD_RUNTIME'] || 'claude');
+    if (resolved === 'claude') {
+        return node_path_1.default.join(__dirname, '..', '..', '..', 'agents');
+    }
+    return node_path_1.default.join((0, runtime_homes_cjs_1.getGlobalConfigDir)(resolved), 'agents');
+}
+/**
+ * Check which GSD agents are installed on disk.
+ *
+ * @param runtime - the active runtime name; defaults to GSD_RUNTIME env, then 'claude'
+ */
+function checkAgentsInstalled(runtime) {
+    const resolvedRuntime = runtime ?? (process.env['GSD_RUNTIME'] || 'claude');
+    const agentsDir = getAgentsDir(resolvedRuntime);
+    const expectedAgents = Object.keys(MODEL_PROFILES);
+    const installed = [];
+    const missing = [];
+    if (!node_fs_1.default.existsSync(agentsDir)) {
+        return {
+            agents_installed: false,
+            missing_agents: expectedAgents,
+            installed_agents: [],
+            incomplete_agents: [],
+            agents_dir: agentsDir,
+            agent_runtime: resolvedRuntime,
+        };
+    }
+    for (const agent of expectedAgents) {
+        const agentFile = node_path_1.default.join(agentsDir, `${agent}.md`);
+        const agentFileCopilot = node_path_1.default.join(agentsDir, `${agent}.agent.md`);
+        const agentFileCodex = node_path_1.default.join(agentsDir, `${agent}.toml`);
+        const agentFileKimiYaml = node_path_1.default.join(agentsDir, 'subagents', `${agent}.yaml`);
+        const agentFileKimiPrompt = node_path_1.default.join(agentsDir, 'subagents', `${agent}.md`);
+        const kimiAgentInstalled = resolvedRuntime === 'kimi' &&
+            node_fs_1.default.existsSync(agentFileKimiYaml) &&
+            node_fs_1.default.existsSync(agentFileKimiPrompt);
+        if (node_fs_1.default.existsSync(agentFile) ||
+            node_fs_1.default.existsSync(agentFileCopilot) ||
+            node_fs_1.default.existsSync(agentFileCodex) ||
+            kimiAgentInstalled) {
+            installed.push(agent);
+        }
+        else {
+            missing.push(agent);
+        }
+    }
+    // ── Manifest-backed completeness check ──────────────────────────────────────
+    // If a gsd-file-manifest.json exists alongside the agents dir (parent dir),
+    // verify that every manifest-tracked file for each expected agent is present
+    // on disk. Missing manifest-tracked files indicate an incomplete install even
+    // when the plain presence check above passed (e.g. .md present, .toml absent).
+    // If no manifest is found the check is a no-op (graceful for claude/bundled).
+    const incomplete = [];
+    const manifestPath = node_path_1.default.join(node_path_1.default.dirname(agentsDir), 'pp-file-manifest.json');
+    let manifestFiles = {};
+    try {
+        const raw = node_fs_1.default.readFileSync(manifestPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            'files' in parsed &&
+            typeof parsed['files'] === 'object' &&
+            parsed['files'] !== null) {
+            manifestFiles = parsed['files'];
+        }
+    }
+    catch {
+        // No manifest or unreadable — completeness check is skipped
+    }
+    if (Object.keys(manifestFiles).length > 0) {
+        for (const agent of expectedAgents) {
+            // Find all manifest keys that belong to this agent:
+            // key must be "agents/<agentName>.<ext>" with no further path segments.
+            const agentPrefix = `agents/${agent}.`;
+            const agentManifestKeys = Object.keys(manifestFiles).filter(key => {
+                if (!key.startsWith(agentPrefix))
+                    return false;
+                const rest = key.slice(agentPrefix.length);
+                // rest must be a bare extension (no slashes, non-empty)
+                return rest.length > 0 && !rest.includes('/');
+            });
+            if (agentManifestKeys.length === 0) {
+                // Agent not tracked in manifest — skip completeness check for this agent
+                continue;
+            }
+            const allPresent = agentManifestKeys.every(key => {
+                const basename = key.slice('agents/'.length);
+                return node_fs_1.default.existsSync(node_path_1.default.join(agentsDir, basename));
+            });
+            if (!allPresent) {
+                incomplete.push(agent);
+            }
+        }
+    }
+    return {
+        agents_installed: installed.length > 0 && missing.length === 0 && incomplete.length === 0,
+        missing_agents: missing,
+        installed_agents: installed,
+        incomplete_agents: incomplete,
+        agents_dir: agentsDir,
+        agent_runtime: resolvedRuntime,
+    };
+}
+module.exports = {
+    getAgentsDir,
+    checkAgentsInstalled,
+};

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

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Canonical GSD artifact registry (ADR-457 build-at-publish: the hand-written
+ * bin/lib/artifacts.cjs collapsed to a TypeScript source of truth). Behaviour
+ * is preserved byte-for-behaviour from the prior hand-written .cjs; only types
+ * are added.
+ *
+ * Enumerates the file names that gsd workflows officially produce at the
+ * .planning/ root level. Used by gsd-health (W019) to flag unrecognized files
+ * so stale or misnamed artifacts don't silently mislead agents or reviewers.
+ *
+ * Add entries here whenever a new workflow produces a .planning/ root file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANONICAL_PATTERNS = exports.CANONICAL_EXACT = void 0;
+exports.isCanonicalPlanningFile = isCanonicalPlanningFile;
+// Exact-match canonical file names at .planning/ root
+exports.CANONICAL_EXACT = new Set([
+    'PROJECT.md',
+    'ROADMAP.md',
+    'STATE.md',
+    'REQUIREMENTS.md',
+    'MILESTONES.md',
+    'BACKLOG.md',
+    'LEARNINGS.md',
+    'THREADS.md',
+    'config.json',
+    'CLAUDE.md',
+    'RETROSPECTIVE.md',
+]);
+// Pattern-match canonical file names (regex tests on the basename)
+// Each pattern includes the name of the workflow that produces it as a comment.
+exports.CANONICAL_PATTERNS = [
+    /^v\d+\.\d+(?:\.\d+)?-MILESTONE-AUDIT\.md$/i, // gsd-complete-milestone (pre-archive)
+    /^v\d+\.\d+(?:\.\d+)?-.*\.md$/i, // other version-stamped planning docs
+];
+/**
+ * Return true if `filename` (basename only, no path) matches a canonical
+ * .planning/ root artifact — either an exact name or a known pattern.
+ *
+ * @param filename - Basename of the file (e.g. "STATE.md")
+ */
+function isCanonicalPlanningFile(filename) {
+    if (exports.CANONICAL_EXACT.has(filename))
+        return true;
+    for (const pattern of exports.CANONICAL_PATTERNS) {
+        if (pattern.test(filename))
+            return true;
+    }
+    return false;
+}