@phamvuhoang/otto-core 0.20.0 → 0.22.0

package/templates/quality-report.md

@@ -7,10 +7,13 @@
 
 Produce an **Otto quality report** with the exact section headings below. Rules:
 
+- **Outcome-first.** Lead with what the end user can now do, drawn from the
+  issue/plan intent and traceable to evidence — not marketing claims and not a
+  diff summary. Keep the change description below the engineer divider.
 - **Layperson-first.** Lead with plain language a non-engineer can act on — the
-  prose sections (What Changed · Why · How To Verify · What To Watch · What I Was
-  Unsure About) come first; keep code-cited engineer detail below the divider.
-  Write the top sections with no jargon, file paths, or SHAs.
+  prose sections (What You Can Now Do · Why · How To Verify · What To Watch ·
+  What I Was Unsure About) come first; keep code-cited engineer detail below the
+  divider. Write the top sections with no jargon, file paths, or SHAs.
 - **Readable first.** Keep it short enough to review in a couple of minutes — a
   maintainer should not have to replay the run log. Specific beats exhaustive.
 - **Verification a non-engineer can run.** _How To Verify_ is numbered,
@@ -33,10 +36,11 @@ Produce an **Otto quality report** with the exact section headings below. Rules:
 One of — **Accepted** · **Accepted with follow-ups** · **Needs human review** · **Rejected**
 (when uncertain, choose **Needs human review**)
 
-## What Changed
+## What You Can Now Do
 
-<Plain language, no jargon — what is different now for a person using this, in
-one or two sentences. No file paths or SHAs here; those go under Evidence.>
+<Plain language, no jargon — the user-visible outcome this run enables, in one
+or two sentences. Draw it from the issue/plan intent. No file paths, SHAs, or
+diff summaries here; those go below the divider.>
 
 ## Why
 
@@ -72,6 +76,11 @@ _Engineer detail below — a non-engineer can stop reading here._
 - Source: <plan/PRD path, GitHub issue #, or Linear ref>
 - Issue or plan: <link or path>
 
+## What Changed
+
+<Engineer-facing change summary: the concrete implementation or documentation
+changes, one click below the user outcome. Cite evidence in the next section.>
+
 ## Evidence
 
 - Implementation evidence: <file:line or commit SHA proving each claim; the
@@ -97,8 +106,8 @@ _Engineer detail below — a non-engineer can stop reading here._
 ### Human verdict trail
 
 Prior **human** verdicts on past Otto runs (most recent last) — consult them so a
-recurring reason ("scope creep", "thin evidence") informs *this* run's Verdict
-and *Recommended next action* before you commit to one:
+recurring reason ("scope creep", "thin evidence") informs _this_ run's Verdict
+and _Recommended next action_ before you commit to one:
 
 <verdict-trail>
 
@@ -109,7 +118,7 @@ and *Recommended next action* before you commit to one:
 **Maintainer:** after reviewing this report, append your verdict to
 `./.otto/verdicts.md` (create it lazily) — a dated `##` heading plus one line:
 the human verdict (**Accepted** · **Accepted with follow-ups** · **Rejected** ·
-**Needs investigation**) and *why* (what was accepted with caveats, or the
+**Needs investigation**) and _why_ (what was accepted with caveats, or the
 concrete reason it was rejected). The file is git-tracked; it feeds the existing
 learning loop, so future runs see what was accepted or rejected and why.
 

package/templates/report-rewrite.md

@@ -0,0 +1,25 @@
+{{ RESUME }}
+
+A quality report failed Otto's emit-time legibility rubric. The missing
+required section(s): **{{ MISSING }}**.
+
+Your only job: emit a corrected **Otto quality report** that includes ALL
+required sections. Lead the prose with `## What You Can Now Do`. Keep the
+leading `# Otto quality report` H1 marker so the harness re-captures it.
+
+Rules — read carefully, this is a tight rewrite, not a new run:
+
+- **Read-only.** Do NOT edit files, do NOT commit, do NOT run the loop or any
+  build/test stage. You are reformatting an existing report.
+- **No invented value.** Base every claim ONLY on the report below and real run
+  evidence. Never fabricate outcomes, verdicts, or evidence to fill a section —
+  if the original report did not establish something, say so plainly.
+- **Layperson-first, terse.** Match the style of the quality-report contract:
+  the prose sections (What You Can Now Do · Why · How To Verify · What To Watch ·
+  What I Was Unsure About) come first, no jargon, then the
+  `_Engineer detail below — a non-engineer can stop reading here._` divider, then
+  the engineer sections. Short enough to review in a couple of minutes.
+
+The report to correct:
+
+{{ REPORT }}

package/templates/review-lens.md

@@ -24,6 +24,8 @@ Read that file with `Read` (use `offset`/`limit` for large diffs) before reviewi
 
 # REVIEWER — {{ LENS }} lens
 
+@include:lens-guidance/{{LENS}}.md
+
 You review the most recent commit (HEAD) through ONE lens only: **{{ LENS }}**.
 
 - `correctness` — bugs, regressions, broken logic, unhandled edge cases.
@@ -33,9 +35,22 @@ You review the most recent commit (HEAD) through ONE lens only: **{{ LENS }}**.
 
 If `<head>` shows `(no commits)`, output `<lens>SKIP</lens>` and stop.
 
+## How to report findings
+
+Emit each finding on its own line, pipe-delimited:
+
+`SEVERITY | file:line | claim | why | fix?`
+
+- `SEVERITY` is one of `blocker | major | minor | nit`.
+- `file:line` may be `path` or `path:line` or `path:start-end`.
+- `fix` (a one-line remediation hint) is optional.
+
+Example:
+`major | packages/core/src/loop.ts:120-180 | gate+routing+cost in one block | three responsibilities, hard to scan | extract resolveGate()`
+
 # OUTPUT
 
-List concrete findings for the **{{ LENS }}** lens only, each as `- <file>:<line> — <issue>`. Be terse. If nothing for this lens, output `none`.
+Emit each finding in the wire format above (`SEVERITY | file:line | claim | why | fix?`), one per line, for the **{{ LENS }}** lens only. Be terse. If you have no findings for this lens, output `none`.
 
 # RULES
 

package/templates/review-synth.md

@@ -19,10 +19,26 @@ An adversarial verifier already judged the lens findings and wrote `{{ FINDINGS_
 # ACTION
 
 1. Collect the `CONFIRMED` findings (already deduped and verified). If there are none, output `<review>OK</review>` and do **not** commit.
-2. Otherwise fix them in the working tree (only the latest commit's code — no unrelated changes), run the feedback loops:
+2. Otherwise apply confirmed findings **highest severity first** (blocker → major → minor).
+   **Suppress nits**: if any blocker or major is confirmed, skip nit-severity
+   findings entirely — do not spend a fix on them while real issues remain.
+
+   Fix them in the working tree (only the latest commit's code — no unrelated changes), run the feedback loops:
    - Frontend / Node: `pnpm run test`, `pnpm run typecheck`
    - Backend / Dotnet: `dotnet test`, `dotnet build`
-     then make a SINGLE commit: `git commit -am "fix(review): <short reason>"` (subject ≤72 chars, no `Co-Authored-By`, no file lists). If a finding reflects a durable, reusable learning (e.g. a recurring defect class), you may also append it tersely to `./.otto/LEARNINGS.md` so it rides in this same commit.
+
+   Then make a SINGLE commit, annotating the body with what you fixed:
+
+   ```
+   fix(review): <short summary>
+
+   Addressed:
+   - blocker | file:line | <claim>
+   - major   | file:line | <claim>
+   Suppressed N nit(s).
+   ```
+
+   (subject ≤72 chars, no `Co-Authored-By`, no file lists). If a finding reflects a durable, reusable learning (e.g. a recurring defect class), you may also append it tersely to `./.otto/LEARNINGS.md` so it rides in this same commit.
 
 # RULES
 

package/templates/review-verify.md

@@ -24,7 +24,7 @@ Read that file with `Read` (use `offset`/`limit` for large diffs) before judging
 
 # ADVERSARIAL VERIFICATION
 
-Review lenses (correctness / security / tests) each examined HEAD and wrote findings to `{{ FINDINGS_DIR }}` — `Read` every `findings-*.md` file there.
+Review lenses (correctness / security / tests / task-fit / structural) each examined HEAD and wrote findings to `{{ FINDINGS_DIR }}` — `Read` every `findings-*.md` file there.
 
 Your role is the **SKEPTIC**. The lenses are eager: many findings will be false positives, speculative, pre-existing, out of scope, or things this repo already accepts. Try to **REFUTE** each finding against the actual HEAD diff and the surrounding code before any of them earns a fix.
 
@@ -37,12 +37,17 @@ Bias toward **REJECTED** when genuinely uncertain: this loop commits fixes with
 
 # OUTPUT
 
-Write your verdicts to `{{ FINDINGS_DIR }}verdicts.md`, one finding per line, deduped:
+Write your verdicts to `{{ FINDINGS_DIR }}verdicts.md`, one finding per line, deduped.
 
-```
-CONFIRMED — <file>:<line> — <issue> — <one line: why it is real>
-REJECTED — <file>:<line> — <issue> — <one line: why not>
-```
+Write each verdict on its own line, carrying severity (you MAY **downgrade** a
+finding's severity if it is real but smaller than claimed):
+
+- `CONFIRMED <severity> | file:line | claim | why this is really a problem`
+- `REJECTED | file:line | claim | why this is not a real problem`
+
+`<severity>` is one of `blocker | major | minor | nit`. Stay biased toward
+REJECTED for anything you cannot substantiate — a false positive costs more than
+a missed nit.
 
 If the lenses produced no findings at all, write a single line: `none`.