@phamvuhoang/otto-core 0.15.0 → 0.17.0

package/dist/plan-rubric.js

@@ -0,0 +1,119 @@
+/**
+ * Plan-quality rubric (issue #63 P8, slice 1 — "measure plan quality before
+ * generating plans").
+ *
+ * A pure scorer over a spec/plan markdown document: it checks the document
+ * against the structural criteria of a world-class plan (the proven
+ * `docs/superpowers` + issue-62 shape) and reports per-criterion results, a
+ * met-count / max score, a 0..1 completeness ratio, and what is missing. It is
+ * the measurement substrate every later P8 slice reads — the `plan` stage,
+ * its eval signal ("plan-completeness rubric score ↑ across fixtures"), the
+ * `--plan-report` surface, and the human checkpoint.
+ *
+ * Sibling to `eval.ts`'s `scoreTrajectory` (a pure scorer over recorded data),
+ * but scoring a *document* rather than a run trajectory. INERT on the loop —
+ * nothing here runs a stage or changes behavior; it only describes text.
+ *
+ * The detectors are deterministic header/keyword heuristics (no tokenizer, no
+ * model call): the rubric judges *structural completeness* (does the plan have
+ * the sections a good plan has), the orthogonal question to the *semantic*
+ * quality a human/model judges at the checkpoint. Heuristic and labelled as
+ * such, mirroring P7's `ceil(chars/4)` estimate discipline.
+ */
+/** Count non-overlapping matches of a global regex in the document. */
+function count(doc, re) {
+    return (doc.match(re) ?? []).length;
+}
+// Path-like inline code: a backticked token with a path separator or a known
+// source-file extension — the signal a plan names the files it will touch.
+const PATH_TOKEN_RE = /`[^`\n]*(?:\/[^`\n]*|\.(?:ts|tsx|js|jsx|mjs|cjs|md|json|py|go|rs|java|rb|sh))`/gi;
+// Task list items: markdown checkboxes or top-of-line ordered items.
+const CHECKBOX_RE = /(?:^|\n)\s*[-*]\s*\[[ xX]\]/g;
+const ORDERED_ITEM_RE = /(?:^|\n)\s*\d+\.\s+\S/g;
+/**
+ * The rubric criteria, in scorecard order. Each detector keys off the proven
+ * plan shape: a section header or the characteristic keywords/markup of that
+ * section. Order is fixed so the scorecard and the `missing` list are stable.
+ */
+export const PLAN_CRITERIA = [
+    {
+        criterion: "problem",
+        label: "Problem statement",
+        detect: (d) => /(?:^|\n)#{1,6}\s+[^\n]*\bproblem\b/i.test(d),
+    },
+    {
+        criterion: "decisions",
+        label: "Decisions / assumptions",
+        detect: (d) => /\b(?:assumptions?|decisions?|rationale)\b/i.test(d),
+    },
+    {
+        criterion: "scopeGuard",
+        label: "Scope guard / non-goals",
+        detect: (d) => /\b(?:scope guard|non-?goals?|out of scope|not in scope|won'?t (?:do|build|change|ship))\b/i.test(d),
+    },
+    {
+        criterion: "fileMap",
+        label: "File / component map",
+        detect: (d) => /(?:^|\n)#{1,6}\s+[^\n]*\b(?:file (?:map|structure)|component map|files)\b/i.test(d) || count(d, PATH_TOKEN_RE) >= 2,
+    },
+    {
+        criterion: "taskBreakdown",
+        label: "Task breakdown",
+        detect: (d) => count(d, CHECKBOX_RE) >= 2 ||
+            count(d, ORDERED_ITEM_RE) >= 2 ||
+            count(d, /(?:^|\n)#{1,6}\s+task\b/gi) >= 2,
+    },
+    {
+        criterion: "testFirst",
+        label: "Failing-test-first (TDD)",
+        detect: (d) => /\b(?:failing test|test[- ]first|tdd|red[- ]green|write (?:a |the )?(?:failing )?test|tests? (?:first|before)|pinned by)\b/i.test(d),
+    },
+    {
+        criterion: "verifyCommands",
+        label: "Explicit verify commands",
+        detect: (d) => /\bverify:/i.test(d) ||
+            (/\bverif(?:y|ied|ication)\b/i.test(d) &&
+                /\b(?:pnpm|npm run|vitest|tsc|node --test|node --|pytest|go test|cargo test|make)\b/i.test(d)),
+    },
+    {
+        criterion: "successCriteria",
+        label: "Testable success criteria",
+        detect: (d) => /\b(?:success (?:criteria|metric)|acceptance (?:criteria|checklist|test)|done when|testing notes|testable)\b/i.test(d),
+    },
+];
+/**
+ * Score a spec/plan markdown document against {@link PLAN_CRITERIA}. Pure and
+ * deterministic — pass the spec text, the plan text, or both concatenated. Each
+ * criterion contributes equally; the per-criterion breakdown lets a consumer
+ * reweight later without changing the scorer.
+ */
+export function scorePlanQuality(doc) {
+    const results = PLAN_CRITERIA.map((c) => ({
+        criterion: c.criterion,
+        label: c.label,
+        met: c.detect(doc),
+    }));
+    const metCount = results.reduce((n, r) => n + (r.met ? 1 : 0), 0);
+    const maxScore = results.length;
+    return {
+        results,
+        metCount,
+        maxScore,
+        ratio: maxScore > 0 ? metCount / maxScore : 0,
+        missing: results.filter((r) => !r.met).map((r) => r.label),
+    };
+}
+const pct = new Intl.NumberFormat("en-US", { maximumFractionDigits: 0 });
+/**
+ * Render a rubric score as a short, human-readable scorecard: a header with the
+ * met/total and percentage, a checked/unchecked line per criterion, and a
+ * one-line "missing" note when the plan is incomplete.
+ */
+export function formatPlanRubric(score) {
+    const header = `plan quality: ${score.metCount}/${score.maxScore} ` +
+        `(${pct.format(score.ratio * 100)}%)`;
+    const lines = score.results.map((r) => `  [${r.met ? "x" : " "}] ${r.label}`);
+    const tail = score.missing.length > 0 ? [`  missing: ${score.missing.join(", ")}`] : [];
+    return [header, ...lines, ...tail].join("\n");
+}
+//# sourceMappingURL=plan-rubric.js.map

package/dist/plan-rubric.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-rubric.js","sourceRoot":"","sources":["../src/plan-rubric.ts"],"names":[],"mappings":"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"}

package/dist/report-explain.d.ts

@@ -0,0 +1,33 @@
+import { type RunManifest } from "./run-report.js";
+/**
+ * Injectable host surface for {@link runExplain} so the reader stays
+ * unit-testable without touching the real cwd/env or process stdio. Mirrors
+ * {@link import("./inspect.js").InspectDeps}.
+ */
+export type ExplainDeps = {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    out: (msg: string) => void;
+    err: (msg: string) => void;
+};
+/**
+ * Render one run for a non-engineer (P9 #64): the plain-language report the run
+ * emitted, then a compact "run facts" footer (source, iterations, cost) from the
+ * manifest. Pure — takes the already-read manifest and the persisted report text
+ * (or `null` when the run emitted none), returns the report string.
+ *
+ * The persisted report already leads with the layperson prose (What changed /
+ * Why / How to verify / What to watch) and keeps engineer detail below its own
+ * divider, so this surface is mostly the report plus the run's bottom-line facts.
+ * When no report was persisted (an older run, or plan/PRD `afk` mode, which emits
+ * none), it falls back to the facts with a one-line note explaining the absence.
+ */
+export declare function formatPlainReport(manifest: RunManifest, reportText: string | null): string;
+/**
+ * Drive the `otto-explain` command: resolve a run id (an explicit id, or
+ * `latest`/no arg → the most recent run under `.otto/runs/`), read its bundle,
+ * and print the plain-language report for a non-engineer. Resolves to the
+ * process exit code. Mirrors {@link import("./inspect.js").runInspect}.
+ */
+export declare function runExplain(argv: string[], deps?: ExplainDeps): Promise<number>;
+//# sourceMappingURL=report-explain.d.ts.map

package/dist/report-explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-explain.d.ts","sourceRoot":"","sources":["../src/report-explain.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAEzB;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B,CAAC;AAWF;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,WAAW,EACrB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,MAAM,CA+BR;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE,WAAyB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAmCjB"}

package/dist/report-explain.js

@@ -0,0 +1,85 @@
+import { resolve } from "node:path";
+import { listRunIds, readManifest, readRunReport, } from "./run-report.js";
+const defaultDeps = {
+    env: process.env,
+    cwd: process.cwd(),
+    out: (m) => process.stdout.write(`${m}\n`),
+    err: (m) => process.stderr.write(`${m}\n`),
+};
+const USAGE = "Usage: otto-explain [<run-id>|latest]";
+/**
+ * Render one run for a non-engineer (P9 #64): the plain-language report the run
+ * emitted, then a compact "run facts" footer (source, iterations, cost) from the
+ * manifest. Pure — takes the already-read manifest and the persisted report text
+ * (or `null` when the run emitted none), returns the report string.
+ *
+ * The persisted report already leads with the layperson prose (What changed /
+ * Why / How to verify / What to watch) and keeps engineer detail below its own
+ * divider, so this surface is mostly the report plus the run's bottom-line facts.
+ * When no report was persisted (an older run, or plan/PRD `afk` mode, which emits
+ * none), it falls back to the facts with a one-line note explaining the absence.
+ */
+export function formatPlainReport(manifest, reportText) {
+    const completed = manifest.completedIterations != null
+        ? `${manifest.completedIterations} of ${manifest.iterations}`
+        : `${manifest.iterations}`;
+    const facts = [];
+    facts.push("— Run facts ————————————————————————————");
+    facts.push(`  What ran:    ${manifest.bin} (${manifest.mode} mode)`);
+    facts.push(`  Asked to do: ${manifest.inputs || "(no inputs)"}`);
+    facts.push(`  Effort:      ${completed} iterations · $${manifest.costUsd.toFixed(2)}`);
+    if (manifest.exitReason) {
+        facts.push(`  Outcome:     ${manifest.exitReason}`);
+    }
+    const lines = [];
+    if (reportText) {
+        lines.push(reportText.trimEnd());
+        lines.push("");
+        lines.push(...facts);
+    }
+    else {
+        lines.push(`Run ${manifest.runId}`);
+        lines.push("");
+        lines.push("This run didn't emit a plain-language report — it's an older run, or a " +
+            "plan/PRD (afk) run, which doesn't produce one yet. The run facts:");
+        lines.push("");
+        lines.push(...facts);
+    }
+    return lines.join("\n");
+}
+/**
+ * Drive the `otto-explain` command: resolve a run id (an explicit id, or
+ * `latest`/no arg → the most recent run under `.otto/runs/`), read its bundle,
+ * and print the plain-language report for a non-engineer. Resolves to the
+ * process exit code. Mirrors {@link import("./inspect.js").runInspect}.
+ */
+export async function runExplain(argv, deps = defaultDeps) {
+    const arg = argv[0];
+    if (arg === "-h" || arg === "--help") {
+        deps.out(USAGE);
+        return 0;
+    }
+    const workspaceDir = resolve(deps.env.OTTO_WORKSPACE ?? deps.cwd);
+    let runId;
+    if (arg && arg !== "latest") {
+        runId = arg;
+    }
+    else {
+        const ids = listRunIds(workspaceDir);
+        if (ids.length === 0) {
+            deps.err(`No runs found under ${workspaceDir}/.otto/runs/. ` +
+                "Run Otto first, then explain the bundle it writes.");
+            return 1;
+        }
+        runId = ids[ids.length - 1];
+    }
+    const manifest = readManifest(workspaceDir, runId);
+    if (!manifest) {
+        deps.err(`No manifest for run '${runId}' under ${workspaceDir}/.otto/runs/. ` +
+            "Check the run id (or pass `latest`).");
+        return 1;
+    }
+    deps.out(formatPlainReport(manifest, readRunReport(workspaceDir, runId)));
+    return 0;
+}
+//# sourceMappingURL=report-explain.js.map

package/dist/report-explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-explain.js","sourceRoot":"","sources":["../src/report-explain.ts"],"names":[],"mappings":"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"}

package/dist/report-rubric.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Report-legibility rubric (issue #64 P9, slice 3 — "report-legibility rubric
+ * + eval signal").
+ *
+ * A pure scorer over a quality-report markdown document: it checks the document
+ * against the structural criteria of the P9 layperson-first contract shape
+ * (quality-report.md) and reports per-criterion results, a met-count / max
+ * score, a 0..1 legibility ratio, and what is missing. It is the measurement
+ * substrate for the P9 success metric ("% of reports a non-engineer understood
+ * without reading code").
+ *
+ * Sibling to `plan-rubric.ts` (which scores a spec/plan document) and to
+ * `eval.ts`'s `scoreTrajectory` (which scores a run trajectory). INERT on the
+ * loop — nothing here runs a stage or changes behaviour; it only describes text.
+ *
+ * The detectors are deterministic header/keyword heuristics (no tokenizer, no
+ * model call): the rubric judges *structural legibility* (does the report have
+ * the layperson sections the P9 contract requires), the orthogonal question to
+ * the *semantic* quality a human judges at review. Heuristic and labelled as
+ * such, mirroring plan-rubric.ts's discipline.
+ */
+export type ReportCriterion = "verdict" | "whatChanged" | "why" | "howToVerify" | "whatToWatch" | "uncertainty" | "engineerDivider";
+type CriterionDef = {
+    criterion: ReportCriterion;
+    /** Human-readable label for the scorecard. */
+    label: string;
+    /** Pure predicate: does the document satisfy this criterion? */
+    detect: (doc: string) => boolean;
+};
+/**
+ * The rubric criteria, in scorecard order. Each detector keys off the proven
+ * P9 quality-report shape: a section header or the characteristic
+ * keywords/markup of that section. Order is fixed so the scorecard and the
+ * `missing` list are stable.
+ */
+export declare const REPORT_CRITERIA: ReadonlyArray<CriterionDef>;
+export type ReportCriterionResult = {
+    criterion: ReportCriterion;
+    label: string;
+    met: boolean;
+};
+export type ReportRubricScore = {
+    /** Per-criterion outcome, in fixed scorecard order. */
+    results: ReportCriterionResult[];
+    /** Criteria met. */
+    metCount: number;
+    /** Total criteria (the denominator). */
+    maxScore: number;
+    /** metCount / maxScore in 0..1; 0 when there are no criteria. */
+    ratio: number;
+    /** Labels of unmet criteria — the "what to improve" surface. */
+    missing: string[];
+};
+/**
+ * Score a quality-report markdown document against {@link REPORT_CRITERIA}.
+ * Pure and deterministic — pass the full report text. Each criterion
+ * contributes equally; the per-criterion breakdown lets a consumer reweight
+ * later without changing the scorer.
+ */
+export declare function scoreReportLegibility(doc: string): ReportRubricScore;
+/**
+ * Render a rubric score as a short, human-readable scorecard: a header with
+ * the met/total and percentage, a checked/unchecked line per criterion, and a
+ * one-line "missing" note when the report is incomplete.
+ */
+export declare function formatReportRubric(score: ReportRubricScore): string;
+export {};
+//# sourceMappingURL=report-rubric.d.ts.map

package/dist/report-rubric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-rubric.d.ts","sourceRoot":"","sources":["../src/report-rubric.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,aAAa,GACb,KAAK,GACL,aAAa,GACb,aAAa,GACb,aAAa,GACb,iBAAiB,CAAC;AAEtB,KAAK,YAAY,GAAG;IAClB,SAAS,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CAClC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC,YAAY,CA0CvD,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,EAAE,eAAe,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,uDAAuD;IACvD,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAepE;AAID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAUnE"}

package/dist/report-rubric.js

@@ -0,0 +1,107 @@
+/**
+ * Report-legibility rubric (issue #64 P9, slice 3 — "report-legibility rubric
+ * + eval signal").
+ *
+ * A pure scorer over a quality-report markdown document: it checks the document
+ * against the structural criteria of the P9 layperson-first contract shape
+ * (quality-report.md) and reports per-criterion results, a met-count / max
+ * score, a 0..1 legibility ratio, and what is missing. It is the measurement
+ * substrate for the P9 success metric ("% of reports a non-engineer understood
+ * without reading code").
+ *
+ * Sibling to `plan-rubric.ts` (which scores a spec/plan document) and to
+ * `eval.ts`'s `scoreTrajectory` (which scores a run trajectory). INERT on the
+ * loop — nothing here runs a stage or changes behaviour; it only describes text.
+ *
+ * The detectors are deterministic header/keyword heuristics (no tokenizer, no
+ * model call): the rubric judges *structural legibility* (does the report have
+ * the layperson sections the P9 contract requires), the orthogonal question to
+ * the *semantic* quality a human judges at review. Heuristic and labelled as
+ * such, mirroring plan-rubric.ts's discipline.
+ */
+/**
+ * The rubric criteria, in scorecard order. Each detector keys off the proven
+ * P9 quality-report shape: a section header or the characteristic
+ * keywords/markup of that section. Order is fixed so the scorecard and the
+ * `missing` list are stable.
+ */
+export const REPORT_CRITERIA = [
+    {
+        criterion: "verdict",
+        label: "Verdict section",
+        detect: (d) => /(?:^|\n)#{1,6}\s+Verdict\b/i.test(d),
+    },
+    {
+        criterion: "whatChanged",
+        label: "What Changed section",
+        detect: (d) => /(?:^|\n)#{1,6}\s+What Changed\b/i.test(d),
+    },
+    {
+        criterion: "why",
+        label: "Why section",
+        detect: (d) => /(?:^|\n)#{1,6}\s+Why\b/i.test(d),
+    },
+    {
+        criterion: "howToVerify",
+        label: "How To Verify section with numbered step",
+        detect: (d) => {
+            // Require BOTH the section heading AND at least one numbered step after it.
+            const headingMatch = /(?:^|\n)(#{1,6}\s+How To Verify\b)/i.exec(d);
+            if (!headingMatch)
+                return false;
+            const afterHeading = d.slice(headingMatch.index + headingMatch[0].length);
+            return /^\s*\d+\./m.test(afterHeading);
+        },
+    },
+    {
+        criterion: "whatToWatch",
+        label: "What To Watch section",
+        detect: (d) => /(?:^|\n)#{1,6}\s+What To Watch\b/i.test(d),
+    },
+    {
+        criterion: "uncertainty",
+        label: "What I Was Unsure About section",
+        detect: (d) => /(?:^|\n)#{1,6}\s+What I Was Unsure About\b/i.test(d),
+    },
+    {
+        criterion: "engineerDivider",
+        label: "Engineer detail divider",
+        detect: (d) => /Engineer detail below/i.test(d),
+    },
+];
+/**
+ * Score a quality-report markdown document against {@link REPORT_CRITERIA}.
+ * Pure and deterministic — pass the full report text. Each criterion
+ * contributes equally; the per-criterion breakdown lets a consumer reweight
+ * later without changing the scorer.
+ */
+export function scoreReportLegibility(doc) {
+    const results = REPORT_CRITERIA.map((c) => ({
+        criterion: c.criterion,
+        label: c.label,
+        met: c.detect(doc),
+    }));
+    const metCount = results.reduce((n, r) => n + (r.met ? 1 : 0), 0);
+    const maxScore = results.length;
+    return {
+        results,
+        metCount,
+        maxScore,
+        ratio: maxScore > 0 ? metCount / maxScore : 0,
+        missing: results.filter((r) => !r.met).map((r) => r.label),
+    };
+}
+const pct = new Intl.NumberFormat("en-US", { maximumFractionDigits: 0 });
+/**
+ * Render a rubric score as a short, human-readable scorecard: a header with
+ * the met/total and percentage, a checked/unchecked line per criterion, and a
+ * one-line "missing" note when the report is incomplete.
+ */
+export function formatReportRubric(score) {
+    const header = `report legibility: ${score.metCount}/${score.maxScore} ` +
+        `(${pct.format(score.ratio * 100)}%)`;
+    const lines = score.results.map((r) => `  [${r.met ? "x" : " "}] ${r.label}`);
+    const tail = score.missing.length > 0 ? [`  missing: ${score.missing.join(", ")}`] : [];
+    return [header, ...lines, ...tail].join("\n");
+}
+//# sourceMappingURL=report-rubric.js.map

package/dist/report-rubric.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-rubric.js","sourceRoot":"","sources":["../src/report-rubric.ts"],"names":[],"mappings":"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"}

package/dist/run-bin.d.ts

@@ -45,6 +45,8 @@ export type RunBinConfig = {
     issueStage?: Stage;
     /** Single read-only gate stage used when --verify is set. Only otto-afk sets this. */
     verifyStage?: Stage;
+    /** Single authoring gate stage used when --plan is set (#63 P8). Only otto-afk sets this. */
+    planStage?: Stage;
     /** Gate stage used when --apply-review is set. Only otto-afk sets this. */
     applyReviewStage?: Stage;
     /** Run mode identifier threaded into runLoop state (e.g. "afk" / "ghafk"). */

package/dist/run-bin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-bin.d.ts","sourceRoot":"","sources":["../src/run-bin.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,MAAM,YAAY,GAAG;IACzB,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;IAC5B;;;;OAIG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7E,iEAAiE;IACjE,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,MAAM,CAAC;IACjC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,gFAAgF;IAChF,UAAU,CAAC,EAAE,KAAK,CAAC;IACnB,sFAAsF;IACtF,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,KAAK,CAAC;IACzB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAAC;CAC/C,CAAC;AA2BF;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAgjB7E"}
+{"version":3,"file":"run-bin.d.ts","sourceRoot":"","sources":["../src/run-bin.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,MAAM,YAAY,GAAG;IACzB,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;IAC5B;;;;OAIG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7E,iEAAiE;IACjE,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,MAAM,CAAC;IACjC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,gFAAgF;IAChF,UAAU,CAAC,EAAE,KAAK,CAAC;IACnB,sFAAsF;IACtF,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,KAAK,CAAC;IAClB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,KAAK,CAAC;IACzB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAAC;CAC/C,CAAC;AA2BF;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAskB7E"}

package/dist/run-bin.js

@@ -65,6 +65,16 @@ export async function runBin(argv, cfg) {
             process.exit(code);
         return;
     }
+    // --plan-report (issue #63 P8): a read-only surface scoring the authored plans
+    // under .otto/tasks/ with the plan-quality rubric. Like --context-report it
+    // prints and exits without running a stage.
+    if (flags.planReport) {
+        const { runPlanReport } = await import("./plan-report-cli.js");
+        const code = await runPlanReport();
+        if (code !== 0)
+            process.exit(code);
+        return;
+    }
     const envMaxWait = process.env.OTTO_MAX_WAIT?.trim();
     const maxWaitMs = flags.maxWaitMs ?? (envMaxWait ? parseDurationMs(envMaxWait) : undefined);
     let tokenMode = flags.tokenMode ?? "off";
@@ -157,9 +167,11 @@ export async function runBin(argv, cfg) {
     // the selected mode. Depends only on flags, not on the guards below.
     const runMode = flags.verify
         ? "verify"
-        : flags.applyReview != null
-            ? "review"
-            : cfg.mode;
+        : flags.plan
+            ? "plan"
+            : flags.applyReview != null
+                ? "review"
+                : cfg.mode;
     // Single source of truth for the --watch label: the per-mode resolver
     // (otto-linear-afk → OTTO_LINEAR_LABEL) falling back to OTTO_WATCH_LABEL.
     // Both --print-config and the runWatch call below read this, so the reported
@@ -362,16 +374,21 @@ export async function runBin(argv, cfg) {
     }
     const modeCount = (flags.issue != null ? 1 : 0) +
         (flags.verify ? 1 : 0) +
+        (flags.plan ? 1 : 0) +
         (flags.applyReview != null ? 1 : 0) +
         (flags.watch ? 1 : 0);
     if (modeCount > 1) {
-        console.error("--issue, --verify, --apply-review, and --watch are mutually exclusive");
+        console.error("--issue, --verify, --plan, --apply-review, and --watch are mutually exclusive");
         process.exit(1);
     }
     if (flags.verify && !cfg.verifyStage) {
         console.error("--verify is only supported by otto-afk");
         process.exit(1);
     }
+    if (flags.plan && !cfg.planStage) {
+        console.error("--plan is only supported by otto-afk");
+        process.exit(1);
+    }
     if (flags.applyReview != null && !cfg.applyReviewStage) {
         console.error("--apply-review is only supported by otto-afk");
         process.exit(1);
@@ -390,21 +407,24 @@ export async function runBin(argv, cfg) {
         : cfg.takesInputArg
             ? flags.rest[1]
             : flags.rest[0];
-    if (flags.verify && (!cfg.takesInputArg || !inputs)) {
-        console.error(`Usage: ${cfg.bin} --verify "<plan-and-prd>"`);
+    // --verify and --plan are both one-shot, input-taking gates (no iterations arg).
+    const oneShot = flags.verify || flags.plan;
+    const oneShotFlag = flags.verify ? "--verify" : "--plan";
+    if (oneShot && (!cfg.takesInputArg || !inputs)) {
+        console.error(`Usage: ${cfg.bin} ${oneShotFlag} "<plan-and-prd>"`);
         process.exit(1);
     }
-    if (!flags.verify && ((cfg.takesInputArg && !inputs) || !iterationsArg)) {
+    if (!oneShot && ((cfg.takesInputArg && !inputs) || !iterationsArg)) {
         console.error(`Usage: ${cfg.bin} ${cfg.usage}`);
         console.error(`       ${cfg.bin} --help`);
         process.exit(1);
     }
-    // --verify is one-shot regardless of any positional count.
-    if (flags.verify && iterationsArg) {
-        console.error("--verify is one-shot; ignoring the iterations argument");
+    // One-shot regardless of any positional count.
+    if (oneShot && iterationsArg) {
+        console.error(`${oneShotFlag} is one-shot; ignoring the iterations argument`);
     }
-    const iterations = flags.verify ? 1 : Number.parseInt(iterationsArg, 10);
-    if (!flags.verify && (!Number.isFinite(iterations) || iterations < 1)) {
+    const iterations = oneShot ? 1 : Number.parseInt(iterationsArg, 10);
+    if (!oneShot && (!Number.isFinite(iterations) || iterations < 1)) {
         console.error(`Invalid iterations: ${iterationsArg}`);
         process.exit(1);
     }
@@ -421,11 +441,13 @@ export async function runBin(argv, cfg) {
     }
     const stages = flags.verify
         ? [cfg.verifyStage]
-        : flags.applyReview != null
-            ? [cfg.applyReviewStage, ...cfg.stages.slice(1)]
-            : flags.issue != null
-                ? [cfg.issueStage, ...cfg.stages.slice(1)]
-                : cfg.stages;
+        : flags.plan
+            ? [cfg.planStage]
+            : flags.applyReview != null
+                ? [cfg.applyReviewStage, ...cfg.stages.slice(1)]
+                : flags.issue != null
+                    ? [cfg.issueStage, ...cfg.stages.slice(1)]
+                    : cfg.stages;
     if (flags.detach && detachLogPath) {
         detachAndExit({
             logPath: detachLogPath,