peaks-loop 4.1.2 → 4.1.4

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/sediment-argv-flags.d.ts

@@ -0,0 +1,54 @@
+/** Typed accessor over the flag map produced by `parseFlags`.
+ *
+ * `parseFlags` internally stores every flag with at least one value as a
+ * `string[]`. A flag with no following non-flag token (e.g. `--apply`,
+ * `--dry-run`) is recorded as `true`. This helper exposes three typed
+ * accessors so call-sites don't have to re-narrow `unknown` or
+ * `string | boolean | string[]` on every read:
+ *
+ *   - `flags.list(name)`     → `string[]` (always an array; a single
+ *                              occurrence is wrapped to a 1-element
+ *                              array at parse time)
+ *   - `flags.bool(name)`     → `boolean` (presence-of flag; missing
+ *                              flag is `false`)
+ *   - `flags.maybeString(name)` → `string | undefined` (first value,
+ *                              or `undefined` if the flag was given
+ *                              as a bare boolean with no value)
+ *
+ * The dispatch layer (runSediment) was previously peppered with
+ * `typeof flags.x === "string"` / `Array.isArray(flags.x)` narrowing.
+ * With this helper the call-sites collapse to one-line reads and the
+ * raw flag map stops leaking across the runSediment boundary.
+ */
+export declare class ParsedFlags {
+    private readonly raw;
+    constructor(raw: Record<string, string[] | true>);
+    /** Always returns an array. Missing flag → []. Single-occurrence
+     *  flag → a 1-element array (parseFlags normalizes this). */
+    list(name: string): string[];
+    /** Presence-of a bare boolean flag. Missing → false. */
+    bool(name: string): boolean;
+    /** First value of a flag, or `undefined` if the flag is absent or
+     *  was given as a bare boolean. */
+    maybeString(name: string): string | undefined;
+}
+/** Parse an argv tail into positional args + flag map.
+ *
+ * Supports:
+ *   --flag value    → flags[flag] = [value, ...] (advance i by 1)
+ *   --flag          → flags[flag] = true        (when next token starts with `--` or is undefined)
+ *   --flag v1 --flag v2   → repeated `--flag` values are accumulated
+ *
+ * Internally stores all values as `string[]` (or `true` for a bare
+ * boolean flag). Use the `ParsedFlags` helper to read typed accessors.
+ *
+ * Repeatable flag handling (Task 15b): when the same `--key` appears
+ * consecutively (e.g. `--segment a --segment b --segment c`), values
+ * are accumulated into a single `string[]`. A single occurrence is
+ * normalized to a 1-element array so callers can use `.list(name)`
+ * uniformly without shape-narrowing on the call-site.
+ */
+export declare function parseFlags(argv: string[]): {
+    positional: string[];
+    flags: ParsedFlags;
+};

package/dist/cli/commands/sediment-argv-flags.js

@@ -0,0 +1,116 @@
+// src/cli/commands/sediment-argv-flags.ts
+//
+// The argv tail parser `peaks skill sediment` drives every verb with: the raw
+// flag map and the typed accessors over it. Split out of
+// `sediment-commands.ts`, which re-exports both symbols so its public surface
+// is unchanged.
+/** Typed accessor over the flag map produced by `parseFlags`.
+ *
+ * `parseFlags` internally stores every flag with at least one value as a
+ * `string[]`. A flag with no following non-flag token (e.g. `--apply`,
+ * `--dry-run`) is recorded as `true`. This helper exposes three typed
+ * accessors so call-sites don't have to re-narrow `unknown` or
+ * `string | boolean | string[]` on every read:
+ *
+ *   - `flags.list(name)`     → `string[]` (always an array; a single
+ *                              occurrence is wrapped to a 1-element
+ *                              array at parse time)
+ *   - `flags.bool(name)`     → `boolean` (presence-of flag; missing
+ *                              flag is `false`)
+ *   - `flags.maybeString(name)` → `string | undefined` (first value,
+ *                              or `undefined` if the flag was given
+ *                              as a bare boolean with no value)
+ *
+ * The dispatch layer (runSediment) was previously peppered with
+ * `typeof flags.x === "string"` / `Array.isArray(flags.x)` narrowing.
+ * With this helper the call-sites collapse to one-line reads and the
+ * raw flag map stops leaking across the runSediment boundary.
+ */
+export class ParsedFlags {
+    raw;
+    constructor(raw) {
+        this.raw = raw;
+    }
+    /** Always returns an array. Missing flag → []. Single-occurrence
+     *  flag → a 1-element array (parseFlags normalizes this). */
+    list(name) {
+        const v = this.raw[name];
+        if (v === undefined)
+            return [];
+        if (v === true)
+            return [];
+        return v;
+    }
+    /** Presence-of a bare boolean flag. Missing → false. */
+    bool(name) {
+        const v = this.raw[name];
+        if (v === undefined)
+            return false;
+        // A flag given as `--name <value>` is also "present" (it just happens
+        // to carry values too). Existing call-sites that want `--dry-run`
+        // semantics care about presence, not whether values are attached.
+        return true;
+    }
+    /** First value of a flag, or `undefined` if the flag is absent or
+     *  was given as a bare boolean. */
+    maybeString(name) {
+        const v = this.raw[name];
+        if (v === undefined)
+            return undefined;
+        if (v === true)
+            return undefined;
+        return v[0];
+    }
+}
+/** Parse an argv tail into positional args + flag map.
+ *
+ * Supports:
+ *   --flag value    → flags[flag] = [value, ...] (advance i by 1)
+ *   --flag          → flags[flag] = true        (when next token starts with `--` or is undefined)
+ *   --flag v1 --flag v2   → repeated `--flag` values are accumulated
+ *
+ * Internally stores all values as `string[]` (or `true` for a bare
+ * boolean flag). Use the `ParsedFlags` helper to read typed accessors.
+ *
+ * Repeatable flag handling (Task 15b): when the same `--key` appears
+ * consecutively (e.g. `--segment a --segment b --segment c`), values
+ * are accumulated into a single `string[]`. A single occurrence is
+ * normalized to a 1-element array so callers can use `.list(name)`
+ * uniformly without shape-narrowing on the call-site.
+ */
+export function parseFlags(argv) {
+    const positional = [];
+    const rawFlags = {};
+    for (let i = 0; i < argv.length; i++) {
+        // `as string`, not `!`: the loop bound is `argv.length`, so these reads are
+        // in range — the toolchain just cannot see that through the index signature.
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const k = a.slice(2);
+            const v = argv[i + 1];
+            if (v === undefined || v.startsWith('--')) {
+                rawFlags[k] = true;
+            }
+            else {
+                // Capture first value, then look ahead for `--k <value>` repeats.
+                const values = [v];
+                i += 2;
+                while (i < argv.length &&
+                    argv[i] === `--${k}` &&
+                    i + 1 < argv.length &&
+                    !argv[i + 1].startsWith('--')) {
+                    values.push(argv[i + 1]);
+                    i += 2;
+                }
+                // Back up one — the outer for-loop will i++ past the flag, so the
+                // next iteration sees the next real token.
+                i--;
+                rawFlags[k] = values;
+            }
+        }
+        else {
+            positional.push(a);
+        }
+    }
+    return { positional, flags: new ParsedFlags(rawFlags) };
+}

package/dist/cli/commands/sediment-command-shared.d.ts

@@ -0,0 +1,15 @@
+import type { ParsedFlags } from './sediment-argv-flags.js';
+/** The `{ ok, error?, data? }` envelope every sediment verb returns. */
+export interface CliResult {
+    ok: boolean;
+    error?: string;
+    data?: unknown;
+}
+/** One parsed argv tail: the pool home, the positionals and the flag accessors. */
+export type SedimentContext = {
+    readonly home: string;
+    readonly positional: string[];
+    readonly flags: ParsedFlags;
+};
+/** A verb implementation. `runSediment` owns the error envelope around it. */
+export type SedimentVerb = (ctx: SedimentContext) => CliResult | Promise<CliResult>;

package/dist/cli/commands/sediment-command-shared.js

@@ -0,0 +1,5 @@
+// src/cli/commands/sediment-command-shared.ts
+//
+// The envelope and dispatch shapes every `peaks skill sediment` verb handler
+// shares. Split out of `sediment-commands.ts`.
+export {};