@gobing-ai/spur 0.3.40 → 0.3.42

package/plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts

@@ -0,0 +1,363 @@
+/**
+ * detect-pipeline-driving — @1.2 pipeline-driving testee detector (task 0277, W7).
+ *
+ * Pure function over the raw testee string → boolean. Used by the dogfood driver
+ * (Phase 1.0 refuse-ambiguous gate) and by unit tests so the matcher contract is
+ * machine-checked rather than agent-interpreted.
+ *
+ * Also ships a **CLI gate** (import.meta.main) so Phase 1.0 is a live shell call,
+ * not agent-only prose interpretation:
+ *
+ *   bun plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts \
+ *     --testee "/sp:dev-run 0125 --auto --next" [--max-retry-present] \
+ *     [--steps "step1||step2"] [--json]
+ *
+ * Exit codes:
+ *   0 — proceed (may print implement-heavy advisory on stderr)
+ *   2 — refuse: pipeline-driving without explicit --max-retry
+ *   1 — usage / argument error
+ *
+ * Contract (0274 §3 dogfood-pipeline-detect, 0277 R1):
+ *   - Word-boundary matchers with `-` treated as a word char (NOT a boundary).
+ *     A token counts only when it is a distinct hyphen-word, not when it is a
+ *     substring of a longer alphanumeric or hyphen run. This removes the
+ *     leading-space dependency of the @1.1 prose detector.
+ *   - Two token shapes, both with strict `[^\w-]` boundaries:
+ *       (a) complete tokens — `--next`, `dev-run`, `dev-runall`, `dev-wrap`,
+ *           `dev-wrapall`, `dev-idea` — matched as whole hyphen-words so the
+ *           slash form `/sp:dev-run` matches on its `dev-run` tail whether or
+ *           not it is preceded by a space, but `--next` does NOT match inside
+ *           `--next-gen` (the trailing `-gen` breaks the boundary).
+ *       (b) bare nouns — `run`, `runall`, `wrap`, `wrapall`, `idea` — matched
+ *           only as standalone words, so `run` matches in
+ *           `bun ... task run 0042` but NOT inside `runaway`/`prerun`, and
+ *           `idea` does NOT match inside `idealist`/`ideal`.
+ *   - Listing both shapes is what makes the detector leading-space invariant
+ *     (the slash form is caught by its `dev-*` tail; the bare noun is caught
+ *     when it appears as its own word) without letting `run` leak into every
+ *     `-run-` identifier.
+ *
+ * Non-goals of detectPipelineDriving: decides ambiguity only. It does NOT decide
+ * observe vs fix — any explicit `--max-retry` value proceeds regardless.
+ * Implement-heavy advisory is a separate helper (detectImplementHeavy).
+ */
+
+/**
+ * Tokens whose presence makes a testee pipeline-driving. Ordered for stable
+ * diagnostics. Two shapes per the contract above: complete `dev-*` / `--next`
+ * tokens first, then bare nouns.
+ */
+const PIPELINE_TOKENS = [
+    '--next',
+    'dev-runall',
+    'dev-wrapall',
+    'dev-run',
+    'dev-wrap',
+    'dev-idea',
+    'runall',
+    'wrapall',
+    'run',
+    'wrap',
+    'idea',
+] as const;
+
+/** Refuse message when pipeline-driving and `--max-retry` was not passed (exact string). */
+export const PIPELINE_DRIVING_REFUSE_MESSAGE =
+    '⚠ pipeline-driving testee detected; pass --max-retry 0 (observe-only) or --max-retry N (fix mode, tree mutation acknowledged)';
+
+/**
+ * Refuse message when the testee carries a mutating `--fix` mode (`--fix all` /
+ * `--fix blockers-first`) and `--max-retry` was not passed. A mutating fix mode
+ * mutates the working tree independent of pipeline-driving (task 0293 R1/R2):
+ * `--max-retry 0` bounds the **driver** only — the testee's own `--fix` pass
+ * still mutates the tree — so the message must not imply otherwise.
+ */
+export const MUTATING_FIX_REFUSE_MESSAGE =
+    '⚠ mutating --fix mode detected (--fix all | --fix blockers-first); pass --max-retry 0 (observe-only for the driver; the testee still mutates the tree) or --max-retry N (fix mode, driver + testee both mutate)';
+
+/** Advisory when pipeline-driving + implement-heavy derived steps (exact string). */
+export const IMPLEMENT_HEAVY_ADVISORY_MESSAGE =
+    '⚠ implement-heavy pipeline dogfood: prefer --max-retry 0 (observe-only) or step-split; operator --max-retry N overrides';
+
+/**
+ * Tokens that mark a derived step as implement-heavy (mutates product/code or
+ * drives a mutating pipeline leg). Deliberately excludes verify/review/unit-only
+ * surfaces even when they carry `--next`.
+ */
+const IMPLEMENT_HEAVY_TOKENS = [
+    'dev-runall',
+    'dev-wrapall',
+    'dev-run',
+    'dev-wrap',
+    'dev-idea',
+    'runall',
+    'wrapall',
+    // bare `run` / `wrap` / `idea` — only when not clearly a non-mutating surface
+    'run',
+    'wrap',
+    'idea',
+    'implement',
+] as const;
+
+/**
+ * A verify/review surface stops being non-mutating the moment it carries a
+ * repair mode: `--fix all` / `--fix blockers-first` applies Edit/Write repairs
+ * to the working tree (0280 dogfood, finding P2). `--fix none` stays
+ * observational. Boundary-guarded so `--prefix all` / `--focus all` never match.
+ * Exported so the Phase 1.0 gate and tests share one matcher (task 0293 R1/R4).
+ */
+export function hasMutatingFixMode(step: string): boolean {
+    return /(?<![\w-])--fix[=\s]+(all|blockers-first)(?![\w-])/i.test(step);
+}
+
+/**
+ * Match a token at a word boundary. A "word boundary" here is the position
+ * between a non-`[\w-]` char (or string start) and the token, and between the
+ * token and a non-`[\w-]` char (or string end). Treating `-` as a word char
+ * is what makes `--next` reject `--next-gen` and `dev-run` reject `dev-runner`.
+ */
+function tokenMatches(testee: string, token: string): boolean {
+    const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // (?<![\w-]) — not preceded by a word char or hyphen.
+    // (?![\w-])  — not followed by a word char or hyphen.
+    const re = new RegExp(`(?<![\\w-])${escaped}(?![\\w-])`, 'i');
+    return re.test(testee);
+}
+
+/**
+ * Returns whether the testee string is pipeline-driving (contains any of the
+ * pipeline-driving tokens as a distinct hyphen-word). Machine-checked
+ * counterpart of the prose list in SKILL.md §Pipeline-driving detection and
+ * dev-dogfood.md.
+ */
+export function detectPipelineDriving(testee: string): boolean {
+    if (typeof testee !== 'string' || testee.length === 0) {
+        return false;
+    }
+    return PIPELINE_TOKENS.some((token) => tokenMatches(testee, token));
+}
+
+/**
+ * True when a single step label (or the whole testee) is implement-heavy —
+ * it chains into real implementation / wrap / idea work, not verify-only.
+ *
+ * Non-mutating surfaces (`dev-verify`, `dev-review`, `dev-unit`, plain
+ * `dev-refine` without a further run) are never implement-heavy even if
+ * pipeline-driving via `--next` — UNLESS they carry a mutating repair mode
+ * (`--fix all` / `--fix blockers-first`), which turns the verify/review leg
+ * into a tree-mutating fix pass (0280 dogfood, finding P2).
+ */
+export function isImplementHeavyStep(step: string): boolean {
+    if (typeof step !== 'string' || step.length === 0) return false;
+    // Explicit non-mutating surfaces win unless a mutating token co-occurs.
+    const nonMutatingOnly =
+        tokenMatches(step, 'dev-verify') || tokenMatches(step, 'dev-review') || tokenMatches(step, 'dev-unit');
+    const hasMutating = IMPLEMENT_HEAVY_TOKENS.some((token) => tokenMatches(step, token)) || hasMutatingFixMode(step);
+    if (nonMutatingOnly && !hasMutating) return false;
+    // refine alone is planning, not implement-heavy; refine+run/--next chain is.
+    if (tokenMatches(step, 'dev-refine') && !hasMutating && !tokenMatches(step, '--next')) {
+        return false;
+    }
+    if (tokenMatches(step, 'dev-refine') && tokenMatches(step, '--next')) {
+        // refine --next chains into run → implement-heavy
+        return true;
+    }
+    return hasMutating;
+}
+
+/**
+ * True when the testee is implement-heavy: it carries a pipeline-driving token,
+ * a mutating `--fix` mode, OR at least one derived step (or the testee itself
+ * when no steps given) is implement-heavy. Used for the W8 Phase 1 advisory
+ * after step derivation.
+ *
+ * Task 0293 R3: a mutating `--fix` mode alone is implement-heavy even with no
+ * pipeline token — the verify/review leg itself becomes a tree-mutating fix
+ * pass.
+ */
+export function detectImplementHeavy(testee: string, derivedSteps: string[] = []): boolean {
+    if (isImplementHeavyStep(testee)) return true;
+    if (!detectPipelineDriving(testee)) return false;
+    return derivedSteps.some((step) => isImplementHeavyStep(step));
+}
+
+export interface GateResult {
+    pipelineDriving: boolean;
+    mutatingFix: boolean;
+    maxRetryPresent: boolean;
+    implementHeavy: boolean;
+    refuse: boolean;
+    advisory: boolean;
+    message: string | null;
+    exitCode: 0 | 1 | 2;
+}
+
+/**
+ * Phase 1.0 + W8 gate decision. Pure — no I/O. The CLI wrapper prints and exits.
+ *
+ * Refuse condition (task 0293 R1) is the union of two **independent** mutation
+ * sources, each gated on `!maxRetryPresent`:
+ *
+ *   1. pipeline-driving testee (`--next`, `dev-run`, …) — refuses because the
+ *      testee chains lifecycle legs whose cumulative blast radius the driver
+ *      cannot pre-attribute.
+ *   2. mutating `--fix` mode (`--fix all` / `--fix blockers-first`) — refuses
+ *      because the testee itself applies Edit/Write repairs even with no
+ *      pipeline token. `--max-retry 0` bounds the **driver** only; the testee
+ *      still mutates (honesty note in MUTATING_FIX_REFUSE_MESSAGE).
+ *
+ * Pipeline-driving is reported first when both co-occur (its refuse message is
+ * the superset — chain + tree mutation).
+ */
+export function evaluateDogfoodGate(
+    testee: string,
+    options: { maxRetryPresent?: boolean; steps?: string[] } = {},
+): GateResult {
+    const maxRetryPresent = options.maxRetryPresent === true;
+    const steps = options.steps ?? [];
+    const pipelineDriving = detectPipelineDriving(testee);
+    const mutatingFix = hasMutatingFixMode(testee);
+    const implementHeavy = detectImplementHeavy(testee, steps);
+
+    if (pipelineDriving && !maxRetryPresent) {
+        return {
+            pipelineDriving,
+            mutatingFix,
+            maxRetryPresent,
+            implementHeavy,
+            refuse: true,
+            advisory: false,
+            message: PIPELINE_DRIVING_REFUSE_MESSAGE,
+            exitCode: 2,
+        };
+    }
+
+    if (mutatingFix && !maxRetryPresent) {
+        return {
+            pipelineDriving,
+            mutatingFix,
+            maxRetryPresent,
+            implementHeavy,
+            refuse: true,
+            advisory: false,
+            message: MUTATING_FIX_REFUSE_MESSAGE,
+            exitCode: 2,
+        };
+    }
+
+    if (implementHeavy) {
+        return {
+            pipelineDriving,
+            mutatingFix,
+            maxRetryPresent,
+            implementHeavy,
+            refuse: false,
+            advisory: true,
+            message: IMPLEMENT_HEAVY_ADVISORY_MESSAGE,
+            exitCode: 0,
+        };
+    }
+
+    return {
+        pipelineDriving,
+        mutatingFix,
+        maxRetryPresent,
+        implementHeavy,
+        refuse: false,
+        advisory: false,
+        message: null,
+        exitCode: 0,
+    };
+}
+
+export { PIPELINE_TOKENS };
+
+// ── CLI entry (live Phase 1.0 gate) ──────────────────────────────────────────
+
+export interface CliArgs {
+    testee: string | null;
+    maxRetryPresent: boolean;
+    steps: string[];
+    json: boolean;
+    help: boolean;
+}
+
+/** Parse CLI argv (everything after the script name). Exported for unit tests. */
+export function parseCliArgs(argv: string[]): CliArgs {
+    let testee: string | null = null;
+    let maxRetryPresent = false;
+    let steps: string[] = [];
+    let json = false;
+    let help = false;
+
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--help' || a === '-h') {
+            help = true;
+        } else if (a === '--json') {
+            json = true;
+        } else if (a === '--max-retry-present') {
+            maxRetryPresent = true;
+        } else if (a === '--testee') {
+            testee = argv[++i] ?? null;
+        } else if (a === '--steps') {
+            const raw = argv[++i] ?? '';
+            steps =
+                raw.length === 0
+                    ? []
+                    : raw
+                          .split('||')
+                          .map((s) => s.trim())
+                          .filter(Boolean);
+        } else if (a === '--') {
+            testee = argv.slice(i + 1).join(' ');
+            break;
+        } else if (!a.startsWith('-') && testee === null) {
+            testee = a;
+        }
+    }
+
+    return { testee, maxRetryPresent, steps, json, help };
+}
+
+export const CLI_USAGE = `Usage:
+  bun plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts \\
+    --testee "<testee string>" [--max-retry-present] [--steps "s1||s2"] [--json]
+
+Exit codes:
+  0  proceed (stdout may carry implement-heavy advisory)
+  2  refuse — pipeline-driving OR mutating --fix mode without --max-retry
+  1  usage error
+
+Phase 1.0: run BEFORE deriving steps (omit --steps).
+Phase 1 W8: re-run AFTER step derivation with --steps "label1||label2".`;
+
+/**
+ * Pure CLI runner for tests: returns { exitCode, stdout, stderr } without
+ * process.exit / console I/O side effects.
+ */
+export function runCli(argv: string[]): { exitCode: number; stdout: string; stderr: string } {
+    const { testee, maxRetryPresent, steps, json, help } = parseCliArgs(argv);
+    if (help) {
+        return { exitCode: 0, stdout: '', stderr: CLI_USAGE };
+    }
+    if (testee === null || testee.length === 0) {
+        return { exitCode: 1, stdout: '', stderr: CLI_USAGE };
+    }
+
+    const result = evaluateDogfoodGate(testee, { maxRetryPresent, steps });
+    if (json) {
+        return { exitCode: result.exitCode, stdout: `${JSON.stringify(result, null, 2)}\n`, stderr: '' };
+    }
+    if (result.message) {
+        return { exitCode: result.exitCode, stdout: `${result.message}\n`, stderr: '' };
+    }
+    return { exitCode: result.exitCode, stdout: '', stderr: '' };
+}
+
+if (import.meta.main) {
+    const { exitCode, stdout, stderr } = runCli(Bun.argv.slice(2));
+    if (stdout) process.stdout.write(stdout);
+    if (stderr) process.stderr.write(`${stderr}\n`);
+    process.exit(exitCode);
+}

package/plugins/sp/scripts/dogfood-testing/validate-report.ts

@@ -0,0 +1,168 @@
+/**
+ * validate-report — @1.2 dogfood report contract checker (task 0276, W6).
+ *
+ * Pure function over a report markdown string → { ok, errors[] } with stable error
+ * codes, callable from tests and by agents finalizing a run. It validates the
+ * *complete-report* shape: the six unique section headings, Issues subheads, the
+ * mandatory summary footer with both delivery paths, frontmatter protocol string,
+ * and ledger↔declared-steps cardinality. Aborted/partial reports are out of scope —
+ * they legitimately lack the footer and Steps line.
+ *
+ * CLI (task 0278 R6): `bun …/validate-report.ts --file <report.md> [--json]`
+ */
+
+import { readFileSync } from 'node:fs';
+
+export interface ReportValidation {
+    ok: boolean;
+    errors: string[];
+}
+
+const REQUIRED_SECTIONS = [1, 2, 3, 4, 5, 6] as const;
+const CANONICAL_PROTOCOL = 'sp:dogfood-testing@1.2';
+
+function countSectionHeadings(markdown: string, section: number): number {
+    const re = new RegExp(`^### ${section}\\.`, 'gm');
+    return (markdown.match(re) ?? []).length;
+}
+
+function countLedgerDataRows(markdown: string): number | null {
+    const heading = markdown.match(/^### 3\. Monitor Ledger\s*$/m);
+    if (!heading || heading.index === undefined) return null;
+    const after = markdown.slice(heading.index + heading[0].length);
+    const nextHeading = after.search(/^### /m);
+    const body = nextHeading === -1 ? after : after.slice(0, nextHeading);
+    const rows = body
+        .split('\n')
+        .filter((line) => line.trim().startsWith('|'))
+        .filter((line) => !/^\|[\s:|-]+\|?\s*$/.test(line.trim()))
+        // drift:external rows are documentary (task 0296) — included in the table but
+        // subtracted from the executed-step count, per the @1.2 cardinality contract.
+        .filter((line) => !/^\|\s*drift:/.test(line.trim()));
+    // Minus the header row; what remains are data rows.
+    return Math.max(rows.length - 1, 0);
+}
+
+function declaredExecutedSteps(markdown: string): number | null {
+    const match = markdown.match(/\*\*Steps:\*\*\s*\d+\s+derived,\s*(\d+)\s+executed/);
+    return match ? Number.parseInt(match[1], 10) : null;
+}
+
+export function validateReport(markdown: string): ReportValidation {
+    const errors: string[] = [];
+
+    // Footer (W2/D1) — the mirrored footer block at the report end.
+    if (!markdown.includes('── Dogfood Summary ──')) errors.push('missing_footer');
+    if (!markdown.includes('[Live:')) errors.push('missing_live_path');
+    if (!markdown.includes('[Report:')) errors.push('missing_report_path');
+
+    // Six unique section headings (W2/D3).
+    for (const section of REQUIRED_SECTIONS) {
+        const count = countSectionHeadings(markdown, section);
+        if (count === 0) errors.push(`missing_section:${section}`);
+        if (count > 1) errors.push(`duplicate_section:${section}`);
+    }
+
+    // Issues subheads (W2/D3).
+    if (!markdown.includes('#### Fixed') || !markdown.includes('#### Unresolved')) {
+        errors.push('missing_issues_subheads');
+    }
+
+    // Protocol string (W1/D5) — colon form, exact version.
+    const protocolMatch = markdown.match(/^protocol:\s*(\S+)\s*$/m);
+    if (!protocolMatch || protocolMatch[1] !== CANONICAL_PROTOCOL) {
+        errors.push('protocol_string');
+    }
+
+    // Ledger cardinality (W3/D4) — data rows == declared executed steps.
+    const executed = declaredExecutedSteps(markdown);
+    if (executed === null) {
+        errors.push('missing_steps_declared');
+    } else {
+        const rows = countLedgerDataRows(markdown);
+        if (rows === null || rows !== executed) {
+            errors.push('ledger_cardinality');
+        }
+    }
+
+    return { ok: errors.length === 0, errors };
+}
+
+// ── CLI entry (Phase 4 self-validate — task 0278 R6) ─────────────────────────
+
+export interface ValidateCliArgs {
+    file: string | null;
+    json: boolean;
+    help: boolean;
+}
+
+export function parseValidateCliArgs(argv: string[]): ValidateCliArgs {
+    let file: string | null = null;
+    let json = false;
+    let help = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--help' || a === '-h') help = true;
+        else if (a === '--json') json = true;
+        else if (a === '--file') file = argv[++i] ?? null;
+        else if (!a.startsWith('-') && file === null) file = a;
+    }
+    return { file, json, help };
+}
+
+export const VALIDATE_CLI_USAGE = `Usage:
+  bun plugins/sp/scripts/dogfood-testing/validate-report.ts --file <report.md> [--json]
+
+Exit codes:
+  0  report validates clean (complete-report shape)
+  2  validation failed (errors on stdout / --json)
+  1  usage error
+
+Phase 4 finalize MUST run this before status: complete (task 0278 R6).
+On exit 2: set status: aborted and list error codes under #### Unresolved.`;
+
+export function runValidateCli(
+    argv: string[],
+    readFile: (path: string) => string,
+): { exitCode: number; stdout: string; stderr: string } {
+    const { file, json, help } = parseValidateCliArgs(argv);
+    if (help) return { exitCode: 0, stdout: '', stderr: VALIDATE_CLI_USAGE };
+    if (file === null || file.length === 0) {
+        return { exitCode: 1, stdout: '', stderr: VALIDATE_CLI_USAGE };
+    }
+    let markdown: string;
+    try {
+        markdown = readFile(file);
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { exitCode: 1, stdout: '', stderr: `Failed to read ${file}: ${msg}` };
+    }
+    const result = validateReport(markdown);
+    if (json) {
+        return {
+            exitCode: result.ok ? 0 : 2,
+            stdout: `${JSON.stringify(result, null, 2)}\n`,
+            stderr: '',
+        };
+    }
+    if (result.ok) {
+        return { exitCode: 0, stdout: 'ok\n', stderr: '' };
+    }
+    return {
+        exitCode: 2,
+        stdout: `${result.errors.join('\n')}\n`,
+        stderr: '',
+    };
+}
+
+/** CLI entry for Phase 4 self-validate (import.meta.main). */
+export function mainCli(argv: string[] = Bun.argv.slice(2)): number {
+    const { exitCode, stdout, stderr } = runValidateCli(argv, (p) => readFileSync(p, 'utf8'));
+    if (stdout) process.stdout.write(stdout);
+    if (stderr) process.stderr.write(`${stderr}\n`);
+    return exitCode;
+}
+
+if (import.meta.main) {
+    process.exit(mainCli());
+}