peaks-loop 4.1.1 → 4.1.3

package/dist/cli/commands/scan-project-commands.js

@@ -0,0 +1,65 @@
+// `peaks scan archetype` and `peaks scan existing-system` — the two
+// filesystem-only project scans. Each `.action()` body lives here as a
+// module-level named runner; registerScanProjectCommands keeps the command
+// declarations (names, options, help text) in their original order.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { scanArchetype } from '../../services/scan/archetype-service.js';
+import { scanExistingSystem } from '../../services/scan/existing-system-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { parsePositiveInt } from './scan-command-shared.js';
+const DEFAULT_MAX_TOKENS = 40;
+const DEFAULT_MAX_SAMPLES = 5;
+const ARCHETYPE_DESCRIPTION = 'Detect project archetype, integration mode (three scenarios), frontend-only mode, and supporting signals from the filesystem (read-only)';
+const EXISTING_SYSTEM_DESCRIPTION = 'Extract visual tokens (colors/spacing/typography/radii) and code conventions from a legacy project (read-only)';
+async function runScanArchetype(options, io) {
+    try {
+        const report = await scanArchetype({ projectRoot: options.project });
+        const nextActions = [];
+        if (report.archetype === 'unknown') {
+            nextActions.push('Archetype could not be determined; surface to user before proceeding.');
+        }
+        else if (report.archetype === 'legacy-frontend' ||
+            report.archetype === 'legacy-fullstack' ||
+            report.archetype === 'frontend-monorepo') {
+            nextActions.push('Run `peaks scan existing-system --project <path>` to extract visual tokens and conventions.');
+        }
+        printResult(io, ok('scan.archetype', report, [], nextActions), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('scan.archetype', 'SCAN_ARCHETYPE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is readable']), options.json);
+        process.exitCode = 1;
+    }
+}
+async function runScanExistingSystem(options, io) {
+    try {
+        const report = await scanExistingSystem({
+            projectRoot: options.project,
+            maxTokens: parsePositiveInt(options.maxTokens, DEFAULT_MAX_TOKENS),
+            maxSamplesPerKind: parsePositiveInt(options.maxSamples, DEFAULT_MAX_SAMPLES)
+        });
+        const nextActions = [];
+        if (!report.scanned) {
+            nextActions.push(report.scanSkippedReason ?? 'Extraction skipped.');
+        }
+        else if (report.inconsistencies.length > 0) {
+            nextActions.push('Surface inconsistencies in the TXT handoff before proceeding.');
+        }
+        printResult(io, ok('scan.existing-system', report, [], nextActions), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('scan.existing-system', 'SCAN_EXISTING_SYSTEM_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is readable']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerScanProjectCommands(scan, io) {
+    addJsonOption(scan
+        .command('archetype')
+        .description(ARCHETYPE_DESCRIPTION)
+        .requiredOption('--project <path>', 'target project root')).action((options) => runScanArchetype(options, io));
+    addJsonOption(scan
+        .command('existing-system')
+        .description(EXISTING_SYSTEM_DESCRIPTION)
+        .requiredOption('--project <path>', 'target project root')
+        .option('--max-tokens <n>', 'maximum tokens to return per category (default 40)')
+        .option('--max-samples <n>', 'maximum convention samples per kind (default 5)')).action((options) => runScanExistingSystem(options, io));
+}

package/dist/cli/commands/scan-scope-commands.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerScanScopeCommands(scan: Command, io: ProgramIO): void;

package/dist/cli/commands/scan-scope-commands.js

@@ -0,0 +1,149 @@
+// The four scope-check subcommands: `scan request-type-sanity`,
+// `scan acceptance-coverage`, `scan diff-vs-scope` and `scan file-size`. Each
+// `.action()` body is a module-level named runner here; the next-action
+// builders and lookup-failure envelopes they use live in scan-scope-helpers.ts.
+import { InvalidArgumentError } from 'commander';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { getAcceptanceCoverage, isAcceptanceCoverageError } from '../../services/scan/acceptance-coverage-service.js';
+import { checkTypeSanity } from '../../services/scan/type-sanity-service.js';
+import { getDiffVsScope, isDiffScopeError } from '../../services/scan/diff-scope-service.js';
+import { scanFileSize } from '../../services/scan/file-size-scan.js';
+import { FILE_SIZE_CAP_DEFAULT, FILE_SIZE_CAP_TESTS } from '../../services/scan/file-size-policy.js';
+import { VALID_REQUEST_TYPES } from '../../services/artifacts/artifact-prerequisites.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { parseOptionalNonNegativeInt, parseRequestType } from './scan-command-shared.js';
+import { acceptanceCoverageNextActions, diffVsScopeNextActions, printAcceptanceCoverageLookupFailure, printDiffVsScopeLookupFailure } from './scan-scope-helpers.js';
+const REQUEST_TYPE_SANITY_DESCRIPTION = 'Cross-verify a declared --type against the actual git diff file mix (catches "feature mis-declared as docs" workflow violations)';
+const ACCEPTANCE_COVERAGE_DESCRIPTION = 'Verify every PRD "Acceptance criteria" item has at least one linked QA test case (via `- **Acceptance:** A1, A2` field in qa/test-cases/<rid>.md)';
+const DIFF_VS_SCOPE_DESCRIPTION = 'Verify every file in the git diff matches the RD artifact "Red-line scope" patterns; flags out-of-scope writes and unclassified files';
+const FILE_SIZE_DESCRIPTION = 'Check git diff for files exceeding a line count threshold (karpathy-skills "Simplicity First"; tool output, lockfiles and append-only records such as CHANGELOG.md excluded)';
+function runScanRequestTypeSanity(options, io) {
+    try {
+        const serviceOptions = {
+            projectRoot: options.project,
+            declaredType: options.type
+        };
+        if (options.baseRef !== undefined) {
+            serviceOptions.baseRef = options.baseRef;
+        }
+        const report = checkTypeSanity(serviceOptions);
+        const nextActions = [];
+        if (!report.consistent) {
+            nextActions.push(`Re-classify the request — likely correct type: ${report.suggestedTypes.join(' | ')}`);
+            nextActions.push('Or, if the declared type is correct, surface the mismatch reason to the user in the TXT handoff.');
+        }
+        if (!report.gitAvailable) {
+            nextActions.push('git not available; manual cross-check required.');
+        }
+        printResult(io, ok('scan.request-type-sanity', report, [], nextActions), options.json);
+        if (!report.consistent) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        if (error instanceof InvalidArgumentError)
+            throw error;
+        printResult(io, fail('scan.request-type-sanity', 'REQUEST_TYPE_SANITY_FAILED', getErrorMessage(error), { projectRoot: options.project, type: options.type }, ['Verify the project path is a git repository or omit the check']), options.json);
+        process.exitCode = 1;
+    }
+}
+async function runScanAcceptanceCoverage(options, io) {
+    try {
+        const coverageOptions = {
+            projectRoot: options.project,
+            requestId: options.rid
+        };
+        if (options.sessionId !== undefined) {
+            coverageOptions.sessionId = options.sessionId;
+        }
+        const result = await getAcceptanceCoverage(coverageOptions);
+        if (isAcceptanceCoverageError(result)) {
+            printAcceptanceCoverageLookupFailure(io, options, result);
+            return;
+        }
+        const nextActions = acceptanceCoverageNextActions(result);
+        printResult(io, ok('scan.acceptance-coverage', result, [], nextActions), options.json);
+        if (!result.ok) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        printResult(io, fail('scan.acceptance-coverage', 'ACCEPTANCE_COVERAGE_FAILED', getErrorMessage(error), { requestId: options.rid }, ['Verify the project path and artifacts before retrying']), options.json);
+        process.exitCode = 1;
+    }
+}
+async function runScanDiffVsScope(options, io) {
+    try {
+        const scopeOptions = {
+            projectRoot: options.project,
+            requestId: options.rid
+        };
+        if (options.sessionId !== undefined)
+            scopeOptions.sessionId = options.sessionId;
+        if (options.baseRef !== undefined)
+            scopeOptions.baseRef = options.baseRef;
+        const result = await getDiffVsScope(scopeOptions);
+        if (isDiffScopeError(result)) {
+            printDiffVsScopeLookupFailure(io, options);
+            return;
+        }
+        const nextActions = diffVsScopeNextActions(result);
+        printResult(io, ok('scan.diff-vs-scope', result, [], nextActions), options.json);
+        if (!result.ok) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        printResult(io, fail('scan.diff-vs-scope', 'DIFF_VS_SCOPE_FAILED', getErrorMessage(error), { requestId: options.rid }, ['Verify the project path is a git repository and the RD artifact exists']), options.json);
+        process.exitCode = 1;
+    }
+}
+function runScanFileSize(options, io) {
+    try {
+        const threshold = parseOptionalNonNegativeInt(options.threshold);
+        const result = scanFileSize({
+            projectRoot: options.project,
+            ...(options.baseRef !== undefined ? { baseRef: options.baseRef } : {}),
+            ...(threshold !== undefined ? { threshold } : {})
+        });
+        const nextActions = [];
+        if (!result.ok) {
+            nextActions.push(`${result.violations.length} file(s) exceed their file-size cap. Split into smaller modules.`);
+        }
+        printResult(io, ok('scan.file-size', result, [], nextActions), options.json);
+        if (!result.ok) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        printResult(io, fail('scan.file-size', 'FILE_SIZE_SCAN_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path is a git repository']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerScanScopeCommands(scan, io) {
+    addJsonOption(scan
+        .command('request-type-sanity')
+        .description(REQUEST_TYPE_SANITY_DESCRIPTION)
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--type <type>', `declared request type (${VALID_REQUEST_TYPES.join(' | ')})`, parseRequestType)
+        .option('--base-ref <ref>', 'compare working tree against this git ref (default: HEAD)')).action((options) => runScanRequestTypeSanity(options, io));
+    addJsonOption(scan
+        .command('acceptance-coverage')
+        .description(ACCEPTANCE_COVERAGE_DESCRIPTION)
+        .requiredOption('--rid <request-id>', 'request id')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <session>', 'restrict to a specific session id')).action((options) => runScanAcceptanceCoverage(options, io));
+    addJsonOption(scan
+        .command('diff-vs-scope')
+        .description(DIFF_VS_SCOPE_DESCRIPTION)
+        .requiredOption('--rid <request-id>', 'request id')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <session>', 'restrict to a specific session id')
+        .option('--base-ref <ref>', 'compare working tree against this git ref (default: HEAD)')).action((options) => runScanDiffVsScope(options, io));
+    addJsonOption(scan
+        .command('file-size')
+        .description(FILE_SIZE_DESCRIPTION)
+        .requiredOption('--project <path>', 'target project root')
+        .option('--base-ref <ref>', 'compare working tree against this git ref (default: HEAD)')
+        .option('--threshold <n>', `line count applied to EVERY file (default: the file-size policy's per-directory cap — ${FILE_SIZE_CAP_DEFAULT} raw lines, ${FILE_SIZE_CAP_TESTS} under root tests/)`)).action((options) => runScanFileSize(options, io));
+}

package/dist/cli/commands/scan-scope-helpers.d.ts

@@ -0,0 +1,8 @@
+import type { AcceptanceCoverageError, AcceptanceCoverageReport } from '../../services/scan/acceptance-coverage-service.js';
+import type { DiffScopeReport } from '../../services/scan/diff-scope-service.js';
+import { type ProgramIO } from '../cli-helpers.js';
+import type { AcceptanceCoverageOptions, DiffVsScopeOptions } from './scan-command-shared.js';
+export declare function acceptanceCoverageNextActions(result: AcceptanceCoverageReport): string[];
+export declare function printAcceptanceCoverageLookupFailure(io: ProgramIO, options: AcceptanceCoverageOptions, result: AcceptanceCoverageError): void;
+export declare function diffVsScopeNextActions(result: DiffScopeReport): string[];
+export declare function printDiffVsScopeLookupFailure(io: ProgramIO, options: DiffVsScopeOptions): void;

package/dist/cli/commands/scan-scope-helpers.js

@@ -0,0 +1,54 @@
+// Next-action builders and "artifact not found" envelopes for the scope-check
+// subcommands (`scan acceptance-coverage`, `scan diff-vs-scope`). They live in
+// their own module so the command/runners file stays a declaration + runner
+// file: every message here is a pure function of the report it is handed.
+import { fail } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+export function acceptanceCoverageNextActions(result) {
+    const nextActions = [];
+    if (result.acceptanceItems.length === 0) {
+        nextActions.push('PRD has no "## Acceptance criteria" bullets. Fill them in before running the coverage check.');
+    }
+    if (result.uncovered.length > 0) {
+        nextActions.push(`${result.uncovered.length} acceptance item(s) have no linked test case. Add a "- **Acceptance:** ${result.uncovered.map((u) => u.id).join(', ')}" field to the relevant test cases.`);
+    }
+    if (result.invalidReferences.length > 0) {
+        nextActions.push(`${result.invalidReferences.length} test case(s) reference an acceptance id that does not exist in the PRD. Fix or remove these references.`);
+    }
+    if (result.unlinkedTestCases.length > 0) {
+        nextActions.push(`${result.unlinkedTestCases.length} test case(s) have no Acceptance: field. Link them to acceptance items, or document why they exist (e.g. defense-in-depth regressions).`);
+    }
+    return nextActions;
+}
+export function printAcceptanceCoverageLookupFailure(io, options, result) {
+    const code = result.kind === 'prd-not-found' ? 'PRD_NOT_FOUND' : 'TEST_CASES_NOT_FOUND';
+    const message = result.kind === 'prd-not-found'
+        ? `PRD artifact for requestId=${options.rid} not found`
+        : `QA test-cases file not found at ${result.expectedPath}`;
+    printResult(io, fail('scan.acceptance-coverage', code, message, { requestId: options.rid }, [
+        result.kind === 'prd-not-found'
+            ? 'Run `peaks request init --role prd --id <rid> --apply --type <type>` first.'
+            : 'Generate qa/test-cases/<rid>.md before running this check.'
+    ]), options.json);
+    process.exitCode = 1;
+}
+export function diffVsScopeNextActions(result) {
+    const nextActions = [];
+    if (!result.gitAvailable) {
+        nextActions.push('git not available; scope check skipped. Cross-check the diff manually.');
+    }
+    if (!result.patternsDeclared) {
+        nextActions.push('RD artifact has no in-scope or out-of-scope patterns under "## Red-line scope". Add concrete path/glob patterns (e.g. `src/services/login/**`) before re-running.');
+    }
+    if (result.violations.length > 0) {
+        nextActions.push(`${result.violations.length} file(s) match an explicit out-of-scope pattern. Revert these or expand the RD red-line scope with PRD approval.`);
+    }
+    if (result.unclassified.length > 0) {
+        nextActions.push(`${result.unclassified.length} changed file(s) do not match any declared scope pattern. Either add them to the in-scope list (if intentional) or revert them.`);
+    }
+    return nextActions;
+}
+export function printDiffVsScopeLookupFailure(io, options) {
+    printResult(io, fail('scan.diff-vs-scope', 'RD_NOT_FOUND', `RD artifact for requestId=${options.rid} not found`, { requestId: options.rid }, ['Run `peaks request init --role rd --id <rid> --apply --type <type>` first.']), options.json);
+    process.exitCode = 1;
+}

package/dist/cli/commands/scan-structural-commands.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerScanStructuralCommands(scan: Command, io: ProgramIO): void;

package/dist/cli/commands/scan-structural-commands.js

@@ -0,0 +1,113 @@
+// `peaks scan orphan` and `peaks scan karpathy` — the structural scans that
+// report orphan kinds and Karpathy-guideline coverage. Both `.action()` bodies
+// are module-level named runners; the format/json/markdown output tail is the
+// shared emitScanReport.
+import { InvalidArgumentError } from 'commander';
+import { fail } from 'peaks-loop-shared/result';
+import { scanOrphans, formatOrphanMarkdown } from '../../services/scan/orphan-service.js';
+import { scanKarpathy, formatKarpathyMarkdown } from '../../services/scan/karpathy-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { emitScanReport, parseKarpathyScope, parseOrphanScope, parseScanOutputFormat } from './scan-command-shared.js';
+const ORPHAN_DESCRIPTION = 'Detect 4 kinds of orphans (export / import / CLI subcommand / doc endpoint) — karpathy §3 Surgical Changes';
+const KARPATHY_DESCRIPTION = 'Surface-level scan of rd/karpathy-review.md for the 4 Karpathy guidelines (Think / Simplicity / Surgical / Goal) — karpathy §1 + §3';
+function orphanNextActions(report) {
+    const nextActions = [];
+    const totalOrphans = report.counts.export +
+        report.counts.import +
+        report.counts.cliSubcommand +
+        report.counts.docEndpoint;
+    if (totalOrphans === 0) {
+        nextActions.push('No orphans detected in the requested scope. RD may proceed to commit.');
+    }
+    else {
+        nextActions.push(`Found ${totalOrphans} orphan(s): export=${report.counts.export} import=${report.counts.import} cliSubcommand=${report.counts.cliSubcommand} docEndpoint=${report.counts.docEndpoint}.`);
+        nextActions.push('Clean up before commit (karpathy §3 — remove what your changes made unused).');
+        nextActions.push('Re-run `peaks scan orphan --project <path>` after cleanup to confirm zero.');
+    }
+    return nextActions;
+}
+function karpathyNextActions(report) {
+    const nextActions = [];
+    if (report.gateAction === 'block') {
+        nextActions.push('Karpathy review file missing under scope=all. Per karpathy §1 Think Before Coding, the rd:qa-handoff gate wants rd/karpathy-review-<rid>.md; this scanner has no rid and reads only the back-compat name rd/karpathy-review.md, so it cannot go green on the rid-scoped name alone. `peaks request transition --state qa-handoff` is the authoritative gate.');
+    }
+    else if (report.gateAction === 'warn') {
+        nextActions.push(`Karpathy review emitted ${report.totalViolations} violation(s). Review the warnings and re-run after cleanup (karpathy §3 Surgical Changes).`);
+    }
+    else {
+        nextActions.push('Karpathy-Gate passes. All 4 guideline sections present and no anti-patterns detected.');
+    }
+    return nextActions;
+}
+async function runScanOrphan(options, io) {
+    try {
+        const report = await scanOrphans({
+            projectRoot: options.project,
+            ...(options.scope !== undefined ? { scope: options.scope } : {}),
+            ...(options.strict !== undefined ? { strict: options.strict } : {})
+        });
+        emitScanReport(io, {
+            command: 'scan.orphan',
+            format: options.format,
+            json: options.json,
+            report,
+            nextActions: orphanNextActions(report),
+            renderMarkdown: () => formatOrphanMarkdown(report, {})
+        });
+    }
+    catch (error) {
+        if (error instanceof InvalidArgumentError)
+            throw error;
+        printResult(io, fail('scan.orphan', 'SCAN_ORPHAN_FAILED', getErrorMessage(error), { projectRoot: options.project }, [
+            'Verify the project path exists and is readable',
+            'Verify the project is a git repository (working-tree scope)'
+        ]), options.json);
+        process.exitCode = 1;
+    }
+}
+async function runScanKarpathy(options, io) {
+    try {
+        const report = await scanKarpathy({
+            projectRoot: options.project,
+            ...(options.scope !== undefined ? { scope: options.scope } : {})
+        });
+        emitScanReport(io, {
+            command: 'scan.karpathy',
+            format: options.format,
+            json: options.json,
+            report,
+            nextActions: karpathyNextActions(report),
+            renderMarkdown: () => formatKarpathyMarkdown(report, {})
+        });
+    }
+    catch (error) {
+        if (error instanceof InvalidArgumentError)
+            throw error;
+        printResult(io, fail('scan.karpathy', 'SCAN_KARPATHY_FAILED', getErrorMessage(error), { projectRoot: options.project }, [
+            'Verify the project path exists and is readable',
+            'Verify the project is a readable directory'
+        ]), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerScanStructuralCommands(scan, io) {
+    // Slice 4/6 — karpathy-enforcement orphan-scan-cli
+    // Detects 4 kinds of orphans: export / import / CLI subcommand / doc
+    // endpoint. Read-only; never writes. karpathy §3 Surgical Changes.
+    addJsonOption(scan
+        .command('orphan')
+        .description(ORPHAN_DESCRIPTION)
+        .requiredOption('--project <path>', 'target project root')
+        .option('--format <fmt>', 'output format: md (default) | json', parseScanOutputFormat)
+        .option('--scope <scope>', 'scope: working-tree (default) | git-diff | all', parseOrphanScope)
+        .option('--strict', 'strict mode: report exportOrphans even outside working tree', false)).action((options) => runScanOrphan(options, io));
+    // Karpathy structural scan (Slice 5/6 — karpathy-enforcement 5-way fanout +
+    // hard Karpathy-Gate). Detects violation counts and section coverage for
+    // the 4 Karpathy-guidelines. Read-only; never writes. karpathy §3.
+    addJsonOption(scan
+        .command('karpathy')
+        .description(KARPATHY_DESCRIPTION)
+        .requiredOption('--project <path>', 'target project root')
+        .option('--format <fmt>', 'output format: md (default) | json', parseScanOutputFormat)
+        .option('--scope <scope>', 'scope: working-tree (default) | all', parseKarpathyScope)).action((options) => runScanKarpathy(options, io));
+}

package/dist/cli/commands/session-24h-mode.d.ts

@@ -1,7 +1,6 @@
 /**
  * `peaks session 24h-mode` — state-only CLI for the 24h mode backbone.
  *
- * Rid-020a (state-only slice). Exposes four sub-actions so the LLM
  * orchestrator can introspect, transition, audit retry attempts, and
  * reset the 24h state machine without touching the JSON file
  * directly. The LLM is the decision-maker; the CLI is the muscle

package/dist/cli/commands/session-24h-mode.js

@@ -1,7 +1,6 @@
 /**
  * `peaks session 24h-mode` — state-only CLI for the 24h mode backbone.
  *
- * Rid-020a (state-only slice). Exposes four sub-actions so the LLM
  * orchestrator can introspect, transition, audit retry attempts, and
  * reset the 24h state machine without touching the JSON file
  * directly. The LLM is the decision-maker; the CLI is the muscle
@@ -136,7 +135,6 @@ export function registerSession24hModeCommand(session, io) {
                 exitCondition: target === 'HANDOFF' ? (merged.exitCondition ?? null) : current.exitCondition
             };
             const result = write24hState(projectRoot, sid, next);
-            // Slice 2026-09-09-mode-consolidation (Slice B): entering 24H_ACTIVE
             // is an auto-engage of the `24h` mode. Stamp it onto the presence
             // lease; every other target state leaves the mode untouched (the
             // guard in `applyAutoEngagePresenceMode` refuses non-24h modes).

package/dist/cli/commands/session-checkpoint-command.d.ts

@@ -1,5 +1,4 @@
 /**
- * `peaks session checkpoint` — slice 011.
  *
  * Writes a JSON snapshot of the current session's state to
  * `_runtime/<sessionId>/checkpoints/<iso>.json`. Designed for skill

package/dist/cli/commands/session-checkpoint-command.js

@@ -1,5 +1,4 @@
 /**
- * `peaks session checkpoint` — slice 011.
  *
  * Writes a JSON snapshot of the current session's state to
  * `_runtime/<sessionId>/checkpoints/<iso>.json`. Designed for skill

package/dist/cli/commands/session-resume-command.d.ts

@@ -1,5 +1,4 @@
 /**
- * `peaks session resume` — slice 011.
  *
  * Reads a checkpoint JSON (written by `peaks session checkpoint`) and
  * emits a structured markdown "resume context" block the skill can

package/dist/cli/commands/session-resume-command.js

@@ -1,5 +1,4 @@
 /**
- * `peaks session resume` — slice 011.
  *
  * Reads a checkpoint JSON (written by `peaks session checkpoint`) and
  * emits a structured markdown "resume context" block the skill can

package/dist/cli/commands/shadcn-commands.js

@@ -1,10 +1,8 @@
 /**
  * `peaks shadcn init` — dynamic wrapper around the upstream `shadcn` CLI.
  *
- * Slice B2 of 2026-09-09-ecc-dynamic-and-cleanup: `skills/bee/peaks-rd/SKILL.md`
  * and `references/frontend-project-generation.md` already tell RD to scaffold
  * a frontend with `peaks shadcn init --preset [CODE] --template vite`, but the
- * command did not exist and `shadcn` was not a dependency. Rather than add a
  * hard dependency, this mirrors `src/services/lint/detect-ocr-18.ts` +
  * `npx-resolver.ts`: the tool is obtained on demand via
  * `npx --package shadcn@<pin> -- shadcn ...`, so the skill reference is true

package/dist/cli/commands/share-commands.d.ts

@@ -1,85 +1,26 @@
 /**
- * `peaks sub-agent share | shared-read | await` — G8.4 + 2.7.0 await barrier.
+ * `peaks sub-agent share | shared-read | await | finalize` — the registrar layer.
  *
- * Pulled out of `sub-agent-commands.ts` (slice 2026-06-23-audit-p0-split)
- * to honor the 800-line file cap. These three commands share the G8.4
- * dispatcher-mediated cross-sub-agent signal channel:
+ * These commands share the G8.4 dispatcher-mediated cross-sub-agent signal
+ * channel:
  *   - `share` writes a `<role>.<event>` entry (≤ 1KB soft warn, ≥ 64KB reject).
  *   - `shared-read` returns sibling entries (filtered by `--since` / `--key` glob).
  *   - `await` joins a batch barrier (slice 2.7.0 MVP, claude-code only).
+ *   - `finalize` (D21) signals that a dispatched sub-agent has finished.
  *
  * Not peer-to-peer — pseudo-swarm property 3 preserved.
+ *
+ * The action bodies, error-code hints, record-path scans and the finalize
+ * selection contract live in the sibling `share-*.ts` / `finalize-*.ts` modules;
+ * this file keeps the command shape (names, descriptions, options) and the one
+ * lazily-resolved IDE registry consumer below.
  */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
-/**
- * A `dispatch-*.json` candidate for `finalize --request-id`, as read off disk.
- * The record's own `createdAt` is carried as the recency key — NOT the file's
- * mtime, which any heartbeat or finalize rewrites, so a `done` record can look
- * newer than the `queued` one that superseded it. Keeping the key on the
- * candidate makes the selection rule a pure function of the records and
- * testable without a filesystem.
- */
-export interface FinalizeCandidate {
-    readonly recordPath: string;
-    readonly requestId: string;
-    readonly status: string;
-    readonly createdAt: string;
-}
-/**
- * What `--request-id` actually did, reported in the envelope. N3: the branch
- * used to resolve silently and could not say WHY a record was or was not the
- * one finalized.
- */
-export interface FinalizeSelection {
-    readonly requestId: string;
-    readonly rule: string;
-    readonly matched: number;
-    readonly chosen: string | null;
-    readonly rejected: readonly {
-        readonly recordPath: string;
-        readonly status: string;
-        readonly reason: string;
-    }[];
-}
-/** The one selection rule `--request-id` and `--batch` now share. */
-export declare const FINALIZE_SELECTION_RULE: string;
-/**
- * N3 — pick the record `finalize --request-id` should act on.
- *
- * The branch this replaces `break`ed on the FIRST file whose record carried
- * the requestId and never looked at `status`. With a re-dispatched request
- * (this session holds six records for `2026-09-12-defect-remediation`) it
- * always resolved to the OLDEST one — the already-`done` RD record — so
- * finalizing reported success while the newer `queued` QA record stayed
- * queued forever. `--batch` never had that bug: it filters on `queued`.
- *
- * Both branches are now the same rule. Return `null` when nothing is queued:
- * a record that already left `queued` is precisely the one that must NOT be
- * re-finalized, so the caller reports the survivors instead of touching one.
- */
-export declare function selectFinalizeTarget(candidates: readonly FinalizeCandidate[]): FinalizeCandidate | null;
-/** Why a candidate was not the chosen one — reported, never guessed at. */
-export declare function describeFinalizeRejection(candidate: FinalizeCandidate, chosen: FinalizeCandidate | null): string;
+export { FINALIZE_SELECTION_RULE, describeFinalizeRejection, selectFinalizeTarget, type FinalizeCandidate, type FinalizeSelection } from './finalize-selection.js';
+export type { FinalizeOptions } from './finalize-selection.js';
 export declare function registerShareCommand(parent: Command, io: ProgramIO): void;
 export declare function registerSharedReadCommand(parent: Command, io: ProgramIO): void;
 export declare function registerAwaitCommand(parent: Command, io: ProgramIO): void;
-/**
- * Slice 2026-07-17-D21: peaks sub-agent finalize — LLM-side completion
- * signal. Without this, dispatch records stay queued forever.
- *
- * Contract:
- *   - LLM MUST call once per dispatched Task, in post-completion branch.
- *   - --all-stale bulk-marks every queued record for this session (crash recovery).
- */
-export interface FinalizeOptions {
-    batch?: string;
-    requestId?: string;
-    outcome?: string;
-    error?: string;
-    allStale?: boolean;
-    project?: string;
-    sessionId?: string;
-    json?: boolean;
-}
+/** Contract: LLM MUST call once per dispatched Task, in post-completion branch. */
 export declare function registerFinalizeCommand(parent: Command, io: ProgramIO): void;