Merge: v1.3.16 — ledger parses the plan template's checkbox bullets (the parser had never met Sage's own output; E9/E10 fixtures structurally blind); manifest resume display same fix; template-conformance suite pins every artifact parser against the actual templates + the ledger↔spec-gate round-trip

Author: xoai

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sage",
-  "version": "1.3.15",
+  "version": "1.3.16",
   "description": "AI skills framework: UNDERSTAND → ENVISION → DELIVER. Mechanical process enforcement, 9 workflows, 12 core skills (+ installable packs), 5 agent personas.",
   "author": {
     "name": "xoai",

CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to Sage will be documented in this file.
 
+## [1.3.16] — the ledger reads the plans Sage writes, and templates become the tested contract
+
+### The ledger reads the plans Sage actually writes
+
+Field report (2026-08-04, the first real `--subagents` cycle to get past
+the flag parser): `ledger.py init` refused a 24-task plan — "no `## Task
+N — title` headings found". The plan template Sage itself generates
+(`core/templates/plan/standard.plan-template.md`) writes checkbox bullets
+(`- [ ] **Task N:** title`); the ledger's parser was written against the
+E9 fixture's heading convention and had never met the product's own
+output. A parser tested only on test-authored data.
+
+- `ledger.py` parses both forms now — heading or checkbox bullet, checked
+  or not (done ≠ independently reviewed), `[DOC]` markers stripped,
+  duplicate ids first-wins. The error message names both accepted forms.
+  Regression-pinned with the template's own shape AND verified against
+  the reporting cycle's real 24-task plan.
+- `manifest.py plan_tasks` had the same assumption with a worse failure
+  mode: on bullet plans the `/continue` resume display printed section
+  headings ("Tasks", "Rollback") as if they were the plan's tasks.
+  Bullet-aware now, same fallback chain.
+- The workflow doc names both forms where it describes ledger generation.
+- **The class is now pinned, not just this instance**: a new
+  template-conformance suite (`test_template_conformance.py`, in
+  fastcheck) runs every parser of a Sage artifact against the TEMPLATE
+  that produces it — ledger and resume task parsing, the judge's
+  current-task and spec-boundary reads, scope-derive's declaration-line
+  regex, and the cross-language ledger↔spec-gate round-trip (scaffold →
+  blocked while pending → allowed when done+approved), all against
+  `standard.plan-template.md` and both spec templates verbatim. A parser
+  that stops reading Sage's own output now fails in fastcheck, not in a
+  field report. The audit that produced it found no further mismatches:
+  manifest frontmatter keys, `## Boundaries`, and `- **Files:**` lines
+  all conform.
+
 ## [1.3.15] — the flag parser survives its own flags, and the dead tests rise
 
 ### `/build --subagents` no longer crashes the flag parser

VERSION

@@ -1 +1 @@
-1.3.15
+1.3.16

core/workflows/sub-workflows/subagent-execution.workflow.md

@@ -63,7 +63,8 @@ python3 sage/runtime/tools/ledger.py init \
   .sage/work/<initiative>/plan.md
 ```
 
-This generates one ledger entry per `## Task N` in the approved plan and sets
+This generates one ledger entry per plan task — the template's
+`- [ ] **Task N:**` bullets or `## Task N` headings — and sets
 `execution_mode: subagent`, which arms the completion guard.
 
 **Why a script and not an instruction to you.** E9 measured this. Given a ledger,

develop/evals/coverage.yaml

@@ -159,7 +159,13 @@ surfaces:
       sage-task-reviewer / sage-branch-reviewer iff the user's config carries
       a model (modelless = unbound, [V-E]); E9/E10 still measure the
       claude-code inherit path — the binding branch is deterministic-only,
-      and the cost comparison stays P5-T3, unclaimed.
+      and the cost comparison stays P5-T3, unclaimed. 2026-08-04 later the
+      same day: ledger.py now parses the plan template's checkbox-bullet
+      tasks as well as the E9-fixture heading form — the first real
+      --subagents cycle could not scaffold a ledger from a plan Sage itself
+      generated (both scenario fixtures use headings, so E9/E10 could never
+      see it; BulletPlanTest pins the template's shape, and the fix was
+      verified against the reporting cycle's real 24-task plan).
 
   subworkflow-quality-gates:
     path: core/workflows/sub-workflows/quality-gates.workflow.md

develop/fastcheck.sh

@@ -47,6 +47,7 @@ CHECKS=(
   "ledger tests           :: python3 develop/validators/tools/test_ledger.py"
   "agent-binding tests    :: python3 develop/validators/tools/test_agent_binding.py"
   "flag parser tests      :: python3 develop/validators/tools/test_sage_flags.py"
+  "template conformance   :: python3 develop/validators/tools/test_template_conformance.py"
   "scope-judge runtime tests :: python3 develop/validators/scope-judge/test_scope_judge.py"
   "review controller tests :: python3 develop/validators/review/test_review_controller.py"
   "review ledger tests    :: python3 develop/validators/review/test_review_ledger.py"

develop/validators/tools/test_ledger.py

@@ -80,7 +80,68 @@ def test_a_plan_with_no_tasks_fails_loudly(self):
         (self.d / "plan.md").write_text("# Plan\n\nSome prose, no task headings.\n")
         r = run("init", self.m(), self.p())
         self.assertEqual(r.returncode, 1)
-        self.assertIn("no `## Task N", r.stderr)
+        self.assertIn("no plan tasks found", r.stderr)
+
+
+
+PLAN_BULLETS = """# Plan
+
+## Tasks
+
+- [ ] **Task 1:** Migration 0005: schema + RLS + down-guard
+  - **Files:** internal/platform/db/migrations/0005.sql
+  - **Action:** schema only
+- [x] **Task 2:** Public IDs (whk_/del_/sbr_) [DOC]
+  - **Depends on:** Task 1
+- [ ] **Task 3:** Signer + signature vectors
+
+## Rollback
+
+Not a task, just a section heading.
+"""
+
+
+class BulletPlanTest(unittest.TestCase):
+    """Field report 2026-08-04: the first real --subagents run could not
+    scaffold a ledger, because ledger.py parsed only `## Task N` headings —
+    the E9 FIXTURE's format — while the plan template Sage itself generates
+    (core/templates/plan/standard.plan-template.md) writes checkbox bullets.
+    A parser tested only against test-authored data had never met the
+    product's own output."""
+
+    def setUp(self):
+        self.d = pathlib.Path(tempfile.mkdtemp())
+        (self.d / "plan.md").write_text(PLAN_BULLETS)
+        (self.d / "manifest.md").write_text(
+            '---\ncycle_id: "t"\ngate_state: plan-approved\n---\n\n# Cycle\n')
+
+    def test_template_bullets_scaffold_a_ledger(self):
+        r = run("init", str(self.d / "manifest.md"), str(self.d / "plan.md"))
+        self.assertEqual(r.returncode, 0, r.stderr)
+        fm = (self.d / "manifest.md").read_text()
+        self.assertEqual(fm.count("- id:"), 3)
+        self.assertIn("title: Signer + signature vectors", fm)
+
+    def test_checked_bullets_and_doc_markers(self):
+        """A checked task still belongs in the ledger (done is not
+        independently reviewed), and [DOC] is presentation, not title."""
+        import importlib.util as _iu
+        spec = _iu.spec_from_file_location("ledger", LEDGER)
+        led = _iu.module_from_spec(spec)
+        spec.loader.exec_module(led)
+        tasks = led.parse_plan_tasks(PLAN_BULLETS)
+        self.assertEqual([n for n, _ in tasks], [1, 2, 3])
+        self.assertEqual(tasks[1][1], "Public IDs (whk_/del_/sbr_)")
+
+    def test_mixed_forms_dedupe_by_id_first_wins(self):
+        import importlib.util as _iu
+        spec = _iu.spec_from_file_location("ledger", LEDGER)
+        led = _iu.module_from_spec(spec)
+        spec.loader.exec_module(led)
+        mixed = "## Task 1 — heading form\n\n- [ ] **Task 1:** bullet form\n- [ ] **Task 2:** only bullet\n"
+        tasks = led.parse_plan_tasks(mixed)
+        self.assertEqual(tasks, [(1, "heading form"), (2, "only bullet")])
+
 
 if __name__ == "__main__":
     unittest.main()

develop/validators/tools/test_template_conformance.py

@@ -0,0 +1,154 @@
+"""Every parser of a Sage artifact, run against the TEMPLATE that produces it.
+
+THE CLASS THIS KILLS. The ledger schism (2026-08-04): ledger.py parsed only
+`## Task N` headings — the E9 fixture's convention — while the plan template
+Sage generates writes `- [ ] **Task N:**` bullets. Green suite, broken
+product: the parser had been tested exclusively against fixture-authored
+data and had never once met Sage's own output. The first real --subagents
+cycle was the first meeting, and it failed.
+
+So: the templates are the contract, and this suite is the handshake. Every
+consumer of plan.md / spec.md / the ledger block parses the ACTUAL template
+file (or an artifact scaffolded from it) and must find what the template
+promises. A parser change that breaks template conformance fails HERE, in
+fastcheck, before any field report. If you add a template or a parser, add
+its handshake.
+
+Python 3.8+, stdlib only.
+"""
+import json
+import pathlib
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+REPO = pathlib.Path(__file__).resolve().parents[3]
+sys.path.insert(0, str(REPO / "runtime" / "tools"))
+
+import ledger as LED            # noqa: E402
+import manifest as MAN          # noqa: E402
+import scope_judge as SJ        # noqa: E402
+
+PLAN_TEMPLATE = REPO / "core" / "templates" / "plan" / "standard.plan-template.md"
+SPEC_TEMPLATES = (REPO / "core" / "templates" / "spec" / "full.spec-template.md",
+                  REPO / "core" / "templates" / "spec" / "minimal.spec-template.md")
+SPEC_GATE = (REPO / "runtime" / "platforms" / "claude-code" / "hooks"
+             / "sage-spec-gate.sh")
+
+PLAN_TEXT = PLAN_TEMPLATE.read_text(encoding="utf-8")
+
+
+class PlanTemplateHandshake(unittest.TestCase):
+    """plan.md consumers × the plan template, verbatim."""
+
+    def test_ledger_parses_the_template_tasks(self):
+        tasks = LED.parse_plan_tasks(PLAN_TEXT)
+        self.assertGreaterEqual(len(tasks), 2,
+                                "the template ships a code task AND a DOC task")
+        self.assertEqual(tasks[0][0], 1)
+        self.assertNotIn("[DOC]", tasks[1][1],
+                         "[DOC] is presentation, not title")
+
+    def test_manifest_plan_tasks_sees_tasks_not_section_headings(self):
+        d = pathlib.Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, d, ignore_errors=True)
+        (d / "plan.md").write_text(PLAN_TEXT)
+        tasks = MAN.plan_tasks(d)
+        self.assertTrue(tasks and all(t.startswith("Task ") for t in tasks),
+                        "bullet plans must yield tasks, not section headings "
+                        "(the /continue display printed 'Gate Log' as a task "
+                        "before 2026-08-04): %r" % tasks[:3])
+
+    def test_scope_judge_current_task_reads_the_template(self):
+        d = pathlib.Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, d, ignore_errors=True)
+        (d / "plan.md").write_text(PLAN_TEXT)
+        tid, title = SJ.current_task(d)
+        self.assertEqual(tid, 1)
+        block = SJ.current_task_block(d)
+        self.assertIn("**Files:**", block,
+                      "the packet must carry the task's declaration lines")
+
+    def test_scope_derive_files_regex_matches_the_template_lines(self):
+        files_lines = [l for l in PLAN_TEXT.splitlines()
+                       if MAN._FILES_LINE_RE.match(l)]
+        self.assertGreaterEqual(
+            len(files_lines), 2,
+            "the template's `- **Files:**` and `- **Output:**` lines are what "
+            "scope derive reads; if this regex stops matching them, every "
+            "derived scope is empty")
+
+
+class SpecTemplateHandshake(unittest.TestCase):
+    """spec.md consumers × both spec templates."""
+
+    def test_judge_boundary_section_found_in_both_templates(self):
+        for tpl in SPEC_TEMPLATES:
+            d = pathlib.Path(tempfile.mkdtemp())
+            self.addCleanup(shutil.rmtree, d, ignore_errors=True)
+            (d / "spec.md").write_text(tpl.read_text(encoding="utf-8"))
+            self.assertTrue(SJ.spec_boundary(d),
+                            "%s: the judge packet's boundary section came "
+                            "back empty — heading drifted?" % tpl.name)
+
+
+class LedgerRoundTrip(unittest.TestCase):
+    """The cross-language seam: ledger.py WRITES the tasks block, the
+    spec-gate hook READS it (R101). Scaffolded from a template-form plan,
+    driven through the real gate, both directions — the live probe from the
+    2026-08-04 review, pinned."""
+
+    def setUp(self):
+        self.root = pathlib.Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.root, ignore_errors=True)
+        cyc = self.root / ".sage" / "work" / "001-x"
+        cyc.mkdir(parents=True)
+        (self.root / ".sage" / "config.yaml").write_text(
+            "hard_enforcement: true\n")
+        (cyc / "plan.md").write_text(
+            "# Plan\n\n## Tasks\n\n"
+            "- [ ] **Task 1:** one\n  - **Files:** src/a.py\n"
+            "- [ ] **Task 2:** two [DOC]\n  - **Output:** docs/x.md\n")
+        (cyc / "manifest.md").write_text(
+            '---\ncycle_id: "001-x"\ngate_state: building\n'
+            "status: in-progress\n---\n# x\n")
+        self.cyc = cyc
+        r = subprocess.run(
+            [sys.executable, str(REPO / "runtime" / "tools" / "ledger.py"),
+             "init", str(cyc / "manifest.md"), str(cyc / "plan.md")],
+            capture_output=True, text=True)
+        assert r.returncode == 0, r.stderr
+
+    def gate(self):
+        payload = json.dumps({
+            "tool_name": "Edit",
+            "tool_input": {"file_path": str(self.cyc / "manifest.md"),
+                           "old_string": "gate_state: building",
+                           "new_string": "gate_state: gates-passed"},
+            "cwd": str(self.root)})
+        return subprocess.run(
+            ["bash", str(SPEC_GATE)], input=payload, capture_output=True,
+            text=True, env={"PATH": "/usr/bin:/bin",
+                            "CLAUDE_PROJECT_DIR": str(self.root)}).returncode
+
+    def mark(self, status, review):
+        m = self.cyc / "manifest.md"
+        t = m.read_text()
+        t = t.replace("status: pending", "status: %s" % status)
+        t = t.replace("review: pending", "review: %s" % review)
+        m.write_text(t)
+
+    def test_gate_blocks_then_allows_the_scaffolded_ledger(self):
+        self.assertEqual(self.gate(), 2,
+                         "pending ledger must block gates-passed (R101)")
+        self.mark("done", "approved")
+        self.assertEqual(self.gate(), 0,
+                         "done+approved (with the model: field present) "
+                         "must pass — the gate parser tolerates the schema")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

runtime/tools/ledger.py

@@ -38,17 +38,39 @@
 import re
 import sys
 
-TASK_RE = re.compile(r"^##\s*Task\s+(\d+)\s*[—:-]\s*(.+?)\s*$", re.M)
+# The plan template's canonical task form is a CHECKBOX BULLET —
+# `- [ ] **Task N:** title` (core/templates/plan/standard.plan-template.md)
+# — while `## Task N — title` headings are the convention the E9/E10
+# fixtures were authored in. The first shipped parser read only headings:
+# written against the fixture, never against the template, so the first
+# real `--subagents` run (field report 2026-08-04) could not scaffold a
+# ledger from a plan Sage itself had generated. Both forms parse now.
+TASK_RE = re.compile(
+    r"^##\s*Task\s+(\d+)\s*[—:-]\s*(.+?)\s*$"
+    r"|^\s*-\s*\[[ xX]\]\s*\*\*Task\s+(\d+)\s*:?\*\*:?\s*(.+?)\s*$",
+    re.M)
 
 
 def parse_plan_tasks(plan_text):
-    """Every `## Task N — title` in the approved plan, in order.
+    """Every plan task, in document order — heading or checkbox-bullet form.
 
     The plan is the contract the ledger must mirror. If the plan has three tasks
     and the ledger has two, the cycle is claiming a review of work it never
     listed — which is the failure the ledger exists to make impossible.
+
+    A checked bullet still belongs in the ledger (done ≠ independently
+    reviewed); `[DOC]` markers are presentation, stripped from titles; a
+    duplicate id keeps its first occurrence.
     """
-    return [(int(n), title.strip()) for n, title in TASK_RE.findall(plan_text)]
+    tasks, seen = [], set()
+    for m in TASK_RE.finditer(plan_text):
+        n = int(m.group(1) or m.group(3))
+        title = re.sub(r"\s*\[DOC\]\s*$", "", (m.group(2) or m.group(4)).strip())
+        if n in seen:
+            continue
+        seen.add(n)
+        tasks.append((n, title))
+    return tasks
 
 
 def split_frontmatter(text):
@@ -94,9 +116,11 @@ def init(manifest_path, plan_path):
 
     tasks = parse_plan_tasks(plan.read_text(encoding="utf-8"))
     if not tasks:
-        print("✗ no `## Task N — title` headings found in %s.\n"
-              "   The ledger is generated from the plan's tasks; a plan with no "
-              "parseable tasks cannot produce one." % plan, file=sys.stderr)
+        print("✗ no plan tasks found in %s.\n"
+              "   Accepted forms: `- [ ] **Task N:** title` (the plan template's\n"
+              "   bullets) or `## Task N — title` headings. The ledger is\n"
+              "   generated from the plan's tasks; a plan with no parseable "
+              "tasks cannot produce one." % plan, file=sys.stderr)
         return 1
 
     text = manifest.read_text(encoding="utf-8")

runtime/tools/manifest.py

@@ -403,13 +403,19 @@ def _read(path: pathlib.Path) -> str:
 
 
 def plan_tasks(cycle_dir: pathlib.Path):
-    """The plan's task headings, verbatim. Falls back to every ## heading when the
-    plan does not use the `## Task N` convention."""
+    """The plan's tasks: `## Task N` headings, else the plan template's
+    canonical `- [ ] **Task N:**` checkbox bullets (which real plans use —
+    the resume display was printing section headings for them, field report
+    2026-08-04), else every ## heading as the last resort."""
     plan = cycle_dir / "plan.md"
     if not plan.is_file():
         return []
     text = _read(plan)
     tasks = re.findall(r"^##\s+(Task\b.*?)\s*$", text, re.M)
+    if not tasks:
+        tasks = ["Task %s: %s" % (n, t) for n, t in re.findall(
+            r"^\s*-\s*\[[ xX]\]\s*\*\*Task\s+(\d+)\s*:?\*\*:?\s*(.+?)\s*$",
+            text, re.M)]
     return tasks or re.findall(r"^##\s+(.*?)\s*$", text, re.M)