@phamvuhoang/otto-core 0.21.0 → 0.23.0

package/templates/plan.md

@@ -22,7 +22,7 @@
 
 You are PLANNING, not implementing. Turn the thin task in `<inputs>` into a
 world-class, structured **spec** and a task-decomposed **plan**, persisted for
-human review *before* any code is written. There is NO human available during
+human review _before_ any code is written. There is NO human available during
 this run: act autonomously and **record your reasoning** instead of waiting for
 approval ("record assumptions and proceed").
 
@@ -66,7 +66,7 @@ plan-quality rubric scores — a world-class plan has all of them):
 
 - `## Problem` — who is blocked, what they cannot do, and why it matters.
 - `## Decisions` (or `## Assumptions`) — each `question → chosen answer →
-  rationale`; record blockers and the safest assumption taken.
+rationale`; record blockers and the safest assumption taken.
 - `## Scope guard` — what is explicitly **out of scope** / the **non-goals**, so
   the implementer does not sprawl.
 - `## File map` — the component/file map: the specific files this work will
@@ -96,8 +96,20 @@ independent tasks out to isolated sub-agents (issue #66 P11). Shape:
 {
   "version": 1,
   "tasks": [
-    { "id": "t1", "title": "<short>", "fileScope": ["path/you/expect/to/touch"], "dependsOn": [], "parallelSafe": true },
-    { "id": "t2", "title": "<short>", "fileScope": ["other/path"], "dependsOn": ["t1"], "parallelSafe": false }
+    {
+      "id": "t1",
+      "title": "<short>",
+      "fileScope": ["path/you/expect/to/touch"],
+      "dependsOn": [],
+      "parallelSafe": true
+    },
+    {
+      "id": "t2",
+      "title": "<short>",
+      "fileScope": ["other/path"],
+      "dependsOn": ["t1"],
+      "parallelSafe": false
+    }
   ]
 }
 ```
@@ -109,9 +121,29 @@ Rules: `id` unique; `dependsOn` lists earlier task ids that must land first;
 if the work does not decompose into cleanly independent tasks, omit it and the
 run proceeds sequentially. A malformed file is ignored (fan-out simply disabled).
 
+## 4c. SELF-CHECK PLAN DEPTH ONCE
+
+Before committing, inspect the spec + plan you wrote. If any item below is
+missing, revise the artifacts once before you commit:
+
+- File map names at least two real repo paths in backticks.
+- Every task names the failing test file/case it will start with and includes an
+  explicit `verify:` command.
+- Success criteria are concretely testable: a reviewer can tell pass/fail from
+  an observable result, test, or command.
+
 ## 5. COMMIT
 
 Commit ONLY the spec + plan + (if written) the task graph — this is the whole
 run, no code. Use a `docs(plan):` or `chore(plan):` commit. Then print a one-line
 summary of the task-key and the number of plan tasks authored. Do not implement;
 the human reviews the plan next.
+
+## 6. QUALITY REPORT
+
+Before you output `<promise>NO MORE TASKS</promise>`, emit one Otto quality
+report for this plan-authoring run. Frame it around what the maintainer can now
+do with the authored plan (approve it, edit it, or reject it before
+implementation), not around the diff.
+
+@include:quality-report.md

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 }}