@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.35 → 0.1.46

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/plans_layout/test_check.py

@@ -3,17 +3,22 @@
 Two committed corpora plus trees built at `tmp_path` for the individual
 branches. Nothing reads the repository this package lives in.
 
-The previous suite tested the `.plans/a_new|b_committed|c_done` lifecycle tree:
-filename dates, `plan_state` agreement with the directory, the eight
-executable-shape concepts, duplicate names across states. None of those rules
-exist any more — documents no longer move and state lives only on the board —
-so the tests were replaced rather than adapted.
+R1–R7 (ADL process handover, 2026-10-12) reshaped the tree this gate grades:
+`spec.md` became `requirements.md`, `intent.md` is the one required plan file
+(a Feature with only `intent.md` passes until planning), `design.md` and
+`file-map-reference.md` joined the Feature-folder allow-list, plan files carry
+the five Feature states while item files keep the twelve item states,
+`GAPS-AND-FINDINGS.md` left the plans root, and each plan file and item file
+now has a required-section list, with EARS acceptance criteria in
+`requirements.md` and a `feature:` board URL on every item file.
 """
 
 from __future__ import annotations
 
 import pathlib
 
+import pytest
+
 from helpers import corpus
 
 from adl_compliance.checks.layout.plans_layout import PlansLayout
@@ -28,7 +33,34 @@ ROW = load().by_id("LAY-009")
 
 AZ = "https://dev.azure.com/org/proj/_workitems/edit"
 
-FEATURE = """---
+INTENT = """---
+type: intent
+title: "A feature"
+status: New
+work_item: {az}/{{work_item}}
+last_update: 2026-09-15T03:20:00Z
+---
+
+# A feature
+
+## Why
+
+Because the board needs the file.
+
+## Outcome
+
+The file exists.
+
+## Constraints
+
+None.
+
+## Non-goals
+
+None.
+""".format(az=AZ)
+
+REQUIREMENTS = """---
 type: feature
 title: "A feature"
 status: New
@@ -36,22 +68,107 @@ epic: {az}/320
 work_item: {az}/{{work_item}}
 last_update: 2026-09-15T03:20:00Z
 sources:
-  - docs/architecture/workflow-automation.md
+  - intent.md
 ---
 
 # A feature
+
+## Problem
+
+## Acceptance criteria
+
+- AC-1: THE SYSTEM SHALL keep the plan files in step with the board.
+
+## Scope
+
+## Predecessors
+
+## Items
+
+## Open questions for G1
+
+none
+
+## Revision log
+""".format(az=AZ)
+
+DESIGN = """---
+type: design
+title: "A feature"
+status: New
+work_item: {az}/{{work_item}}
+last_update: 2026-09-15T03:20:00Z
+sources:
+  - requirements.md
+---
+
+# A feature
+
+## Solution
+
+## Decisions
+
+## Verification
+
+## Docs impact
+
+## Size estimate
+
+## Risks
+""".format(az=AZ)
+
+FILE_MAP = """---
+type: file-map
+title: "A feature"
+status: New
+work_item: {az}/{{work_item}}
+last_update: 2026-09-15T03:20:00Z
+---
+
+# A feature
+
+## Baseline
+
+## Map
 """.format(az=AZ)
 
 ITEM = """---
-type: {{item_type}}
+type: {item_type}
 title: "An item"
 status: New
-work_item: {az}/{{work_item}}
+work_item: {az}/{work_item}
+feature: {az}/{feature}
 last_update: 2026-09-15T03:20:00Z
 ---
 
 # An item
-""".format(az=AZ)
+""".format(az=AZ, item_type="{item_type}", work_item="{work_item}", feature="{feature}")
+
+PBI_SECTIONS = "## What it delivers\n\n## Verification\n"
+BUG_SECTIONS = (
+    "## Current behaviour\n\n## Expected behaviour\n\n"
+    "## Behaviour that must not change\n\n## Responsible Feature\n\n"
+    "## Predecessors\n\n## Verification\n"
+)
+
+
+def item_body(item_type: str, work_item: int, feature: int = 1) -> str:
+    body = ITEM.replace("{item_type}", item_type)
+    body = body.replace("{work_item}", str(work_item))
+    body = body.replace("{feature}", str(feature))
+    return body.rstrip("\n") + "\n\n" + (
+        BUG_SECTIONS if item_type == "bug" else PBI_SECTIONS
+    )
+
+
+def feature_files(work_item: int = 1) -> dict[str, str]:
+    """A complete, conforming Feature folder (all four plan files, no items)."""
+    return {
+        "plans/features/az1-x/intent.md": INTENT.format(work_item=work_item),
+        "plans/features/az1-x/requirements.md": REQUIREMENTS.format(work_item=work_item),
+        "plans/features/az1-x/design.md": DESIGN.format(work_item=work_item),
+        "plans/features/az1-x/file-map-reference.md": FILE_MAP.format(work_item=work_item),
+    }
 
 
 def graded_directly(root: pathlib.Path) -> object:
@@ -85,8 +202,8 @@ def test_the_violation_corpus_reports_each_disagreement() -> None:
     verdict = graded_directly(VIOLATION)
     assert verdict.outcome is Outcome.FINDINGS
     messages = " | ".join(f.message for f in verdict.findings)
-    # spec work_item 999 vs directory az347, item work_item 352 vs filename
-    # az351, item feature az999 vs its actual directory, and a bad item_type.
+    # requirements work_item 999 vs directory az347, item work_item 352 vs
+    # filename az351, and a bad item_type.
     assert "work_item 999 disagrees with az347" in messages, verdict.render()
     assert "work_item 352 disagrees with az351" in messages, verdict.render()
     assert "'chore' is not pbi or bug" in messages, verdict.render()
@@ -112,7 +229,7 @@ def test_a_leftover_lifecycle_directory_is_reported(tmp_path: pathlib.Path) -> N
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1),
                 "plans/a_new/26-09-15-old-plan.md": "# old",
             },
         )
@@ -131,7 +248,7 @@ def test_an_unapproved_root_directory_is_reported(tmp_path: pathlib.Path) -> Non
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1),
                 "plans/archive/old.md": "# old",
             },
         )
@@ -144,7 +261,7 @@ def test_an_unapproved_root_file_is_reported(tmp_path: pathlib.Path) -> None:
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1),
                 "plans/NOTES.md": "# notes",
             },
         )
@@ -152,12 +269,30 @@ def test_an_unapproved_root_file_is_reported(tmp_path: pathlib.Path) -> None:
     assert any("direct plans files must be" in f.message for f in verdict.findings)
 
 
+def test_gaps_and_findings_is_no_longer_allowed_at_the_plans_root(
+    tmp_path: pathlib.Path,
+) -> None:
+    """R7: the register is retired; findings enter only through report-bug."""
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1),
+                "plans/GAPS-AND-FINDINGS.md": "# gaps\n",
+            },
+        )
+    )
+    finding = next(f for f in verdict.findings if f.path == "plans/GAPS-AND-FINDINGS.md")
+    assert "direct plans files must be" in finding.message
+    assert "GAPS-AND-FINDINGS.md" not in finding.message
+
+
 def test_a_loose_file_in_features_is_reported(tmp_path: pathlib.Path) -> None:
     verdict = graded_directly(
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1),
                 "plans/features/stray.md": "# stray",
             },
         )
@@ -183,7 +318,7 @@ def test_a_gitkeep_beside_a_feature_is_reported_and_names_the_deletion(
     tmp_path: pathlib.Path,
 ) -> None:
     files = {
-        "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
+        "plans/features/az1-x/intent.md": INTENT.format(work_item=1),
         "plans/features/.gitkeep": "",
     }
     verdict = graded_directly(build(tmp_path, {"plans/AGENTS.md": "x", **files}))
@@ -207,7 +342,7 @@ def test_any_other_loose_file_is_still_reported_beside_a_gitkeep(
 def test_a_gitkeep_is_only_the_features_directorys_exemption(tmp_path: pathlib.Path) -> None:
     """Strictness: the allowance is for `features/` alone, not a Feature folder."""
     files = {
-        "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
+        "plans/features/az1-x/intent.md": INTENT.format(work_item=1),
         "plans/features/az1-x/.gitkeep": "",
     }
     verdict = graded_directly(build(tmp_path, {"plans/AGENTS.md": "x", **files}))
@@ -216,31 +351,70 @@ def test_a_gitkeep_is_only_the_features_directorys_exemption(tmp_path: pathlib.P
 
 def test_a_feature_directory_not_named_az_id_is_reported(tmp_path: pathlib.Path) -> None:
     verdict = graded_directly(
-        build(tmp_path, {"plans/features/coverage/spec.md": FEATURE.format(work_item=1)})
+        build(tmp_path, {"plans/features/coverage/intent.md": INTENT.format(work_item=1)})
     )
     assert any(
         "must be named az<work item id>-<kebab-slug>" in f.message for f in verdict.findings
     )
 
 
-def test_a_feature_directory_without_a_spec_is_reported(tmp_path: pathlib.Path) -> None:
+# ------------------------------------------------------------------ R2: intent
+
+
+def test_a_feature_directory_without_an_intent_is_reported(tmp_path: pathlib.Path) -> None:
     verdict = graded_directly(
         build(
             tmp_path,
             {
-                "plans/features/az1-x/items/az2-y.md": ITEM.format(item_type="pbi", work_item=2)
+                "plans/features/az1-x/items/az2-y.md": item_body("pbi", 2),
             },
         )
     )
-    assert any("must hold a spec.md" in f.message for f in verdict.findings)
+    assert any("must hold an intent.md" in f.message for f in verdict.findings)
 
 
-def test_an_extra_file_beside_spec_is_reported(tmp_path: pathlib.Path) -> None:
+def test_a_feature_folder_holding_only_intent_passes_until_planning(
+    tmp_path: pathlib.Path,
+) -> None:
+    """R2: `requirements.md` arrives with the planning run, not before it."""
+    verdict = graded_directly(
+        build(tmp_path, {"plans/features/az1-x/intent.md": INTENT.format(work_item=1)})
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_the_missing_intent_fix_points_at_the_workitems_process_skill(
+    tmp_path: pathlib.Path,
+) -> None:
+    """R5: templates ship with the workitems-process skill only."""
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                "plans/features/az1-x/items/az2-y.md": item_body("pbi", 2),
+            },
+        )
+    )
+    finding = next(f for f in verdict.findings if "must hold an intent.md" in f.message)
+    assert "workitems-process" in finding.fix
+
+
+# ---------------------------------------------------- R3/R6: plan file siblings
+
+
+def test_design_and_file_map_are_permitted_beside_requirements(
+    tmp_path: pathlib.Path,
+) -> None:
+    verdict = graded_directly(build(tmp_path, feature_files()))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_an_extra_file_beside_the_plan_files_is_reported(tmp_path: pathlib.Path) -> None:
     verdict = graded_directly(
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
+                **feature_files(),
                 "plans/features/az1-x/notes.md": "# notes",
             },
         )
@@ -248,11 +422,16 @@ def test_an_extra_file_beside_spec_is_reported(tmp_path: pathlib.Path) -> None:
     # The message ENUMERATES what is allowed, so whoever hits it can correct the
     # file without opening the check. A bare "not allowed" sends the reader here.
     finding = next(f for f in verdict.findings if "Feature directory holds" in f.message)
-    assert finding.message == "a Feature directory holds spec.md, handoff.md, intent.md, review.md, items/ only"
-    assert "rename it to one of handoff.md, intent.md, review.md" in finding.fix
+    assert finding.message == (
+        "a Feature directory holds intent.md, requirements.md, design.md, "
+        "file-map-reference.md, handoff.md, review.md, items/ only"
+    )
+    assert "rename it to one of handoff.md, review.md" in finding.fix
 
 
-def test_supporting_documents_are_permitted_beside_spec(tmp_path: pathlib.Path) -> None:
+def test_supporting_documents_are_permitted_beside_the_plan_files(
+    tmp_path: pathlib.Path,
+) -> None:
     """handoff.md and review.md are named by ROLE, so a feature's supporting documents
     sit at the same path in every feature. A topic-named file (CHANNELS-HANDOVER.md)
     states the topic a second time and differently each time, which is the drift the
@@ -261,7 +440,7 @@ def test_supporting_documents_are_permitted_beside_spec(tmp_path: pathlib.Path)
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
+                **feature_files(),
                 "plans/features/az1-x/handoff.md": "# handoff",
                 "plans/features/az1-x/review.md": "# review",
             },
@@ -275,7 +454,7 @@ def test_a_topic_named_supporting_file_is_still_reported(tmp_path: pathlib.Path)
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
+                **feature_files(),
                 "plans/features/az1-x/CHANNELS-HANDOVER.md": "# handover",
             },
         )
@@ -288,8 +467,8 @@ def test_an_item_not_named_az_id_is_reported(tmp_path: pathlib.Path) -> None:
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
-                "plans/features/az1-x/items/26-09-15-old-name.md": ITEM.format(item_type="pbi", work_item=2),
+                **feature_files(),
+                "plans/features/az1-x/items/26-09-15-old-name.md": item_body("pbi", 2),
             },
         )
     )
@@ -302,23 +481,23 @@ def test_an_item_not_named_az_id_is_reported(tmp_path: pathlib.Path) -> None:
 # ----------------------------------------------------------------- frontmatter
 
 
-def test_a_spec_without_an_epic_is_reported(tmp_path: pathlib.Path) -> None:
+def test_a_requirements_file_without_an_epic_is_reported(tmp_path: pathlib.Path) -> None:
     verdict = graded_directly(
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": "---\ntype: Feature\nwork_item: 1\n---\n\n# x\n",
+                "plans/features/az1-x/requirements.md": "---\ntype: feature\nwork_item: 1\n---\n\n# x\n",
             },
         )
     )
     assert any("must name the Epic" in f.message for f in verdict.findings)
 
 
-def test_a_spec_work_item_disagreeing_with_its_directory_is_reported(
+def test_a_plan_work_item_disagreeing_with_its_directory_is_reported(
     tmp_path: pathlib.Path,
 ) -> None:
     verdict = graded_directly(
-        build(tmp_path, {"plans/features/az1-x/spec.md": FEATURE.format(work_item=2)})
+        build(tmp_path, {"plans/features/az1-x/intent.md": INTENT.format(work_item=2)})
     )
     assert any(
         "work_item 2 disagrees with az1" in f.message for f in verdict.findings
@@ -334,8 +513,8 @@ def test_an_item_work_item_disagreeing_with_its_filename_is_reported(
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
-                "plans/features/az1-x/items/az2-y.md": ITEM.format(item_type="pbi", work_item=3),
+                **feature_files(),
+                "plans/features/az1-x/items/az2-y.md": item_body("pbi", 3),
             },
         )
     )
@@ -350,7 +529,7 @@ def test_a_status_outside_the_board_vocabulary_is_reported(tmp_path: pathlib.Pat
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1).replace(
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1).replace(
                     "status: New", "status: draft"
                 )
             },
@@ -359,6 +538,88 @@ def test_a_status_outside_the_board_vocabulary_is_reported(tmp_path: pathlib.Pat
     assert any("is not a work item state" in f.message for f in verdict.findings)
 
 
+@pytest.mark.parametrize(
+    "status", ("New", "In Progress", "Awaiting Release", "Done", "Removed")
+)
+def test_each_feature_state_is_accepted_on_every_plan_file(
+    tmp_path: pathlib.Path, status: str
+) -> None:
+    """R1: plan files mirror the FEATURE's board state, not an item's."""
+    files = feature_files()
+    for path in files:
+        files[path] = files[path].replace("status: New", f"status: {status}")
+    verdict = graded_directly(build(tmp_path, files))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+@pytest.mark.parametrize(
+    "status",
+    (
+        "In Planning", "Awaiting Approval", "Approved", "Design Validation",
+        "In Implementation", "In Testing", "In Review", "Updating Docs",
+        "Parked for Removal",
+    ),
+)
+def test_an_item_state_on_a_plan_file_is_reported(
+    tmp_path: pathlib.Path, status: str
+) -> None:
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1).replace(
+                    "status: New", f"status: {status}"
+                )
+            },
+        )
+    )
+    assert any("is not a work item state" in f.message for f in verdict.findings)
+
+
+def test_a_feature_state_on_an_item_file_is_reported(tmp_path: pathlib.Path) -> None:
+    """R1 the other way: `Awaiting Release` is a Feature state, not an item's."""
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                **feature_files(),
+                "plans/features/az1-x/items/az2-y.md": item_body("pbi", 2).replace(
+                    "status: New", "status: Awaiting Release"
+                ),
+            },
+        )
+    )
+    assert any("is not a work item state" in f.message for f in verdict.findings)
+
+
+def test_design_validation_is_the_renamed_item_state(tmp_path: pathlib.Path) -> None:
+    """F8: Spec Validation became Design Validation in the item vocabulary."""
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                **feature_files(),
+                "plans/features/az1-x/items/az2-y.md": item_body("pbi", 2).replace(
+                    "status: New", "status: Design Validation"
+                ),
+            },
+        )
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    retired = graded_directly(
+        build(
+            tmp_path,
+            {
+                **feature_files(),
+                "plans/features/az1-x/items/az2-y.md": item_body("pbi", 2).replace(
+                    "status: New", "status: Spec Validation"
+                ),
+            },
+        )
+    )
+    assert any("is not a work item state" in f.message for f in retired.findings)
+
+
 def test_a_bare_work_item_id_is_reported(tmp_path: pathlib.Path) -> None:
     # The id is already in the filename; the field earns its place by being the
     # link a reader can click through to the board.
@@ -366,7 +627,7 @@ def test_a_bare_work_item_id_is_reported(tmp_path: pathlib.Path) -> None:
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1).replace(
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1).replace(
                     f"work_item: {AZ}/1", "work_item: 1"
                 )
             },
@@ -375,26 +636,340 @@ def test_a_bare_work_item_id_is_reported(tmp_path: pathlib.Path) -> None:
     assert any("must be a board URL" in f.message for f in verdict.findings)
 
 
-def test_a_spec_without_sources_is_reported(tmp_path: pathlib.Path) -> None:
+# ------------------------------------------------------- R4: required sections
+
+
+def test_a_plan_file_missing_a_required_section_is_reported(tmp_path: pathlib.Path) -> None:
     verdict = graded_directly(
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1).replace(
-                    "sources:\n  - docs/architecture/workflow-automation.md\n", ""
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1).replace(
+                    "## Outcome\n", ""
                 )
             },
         )
     )
+    assert any("missing section ## Outcome" in f.message for f in verdict.findings)
+
+
+def test_each_required_section_of_requirements_is_reported_by_name(
+    tmp_path: pathlib.Path,
+) -> None:
+    body = REQUIREMENTS.format(work_item=1)
+    for section in ("## Problem", "## Acceptance criteria", "## Items", "## Revision log"):
+        verdict = graded_directly(
+            build(
+                tmp_path,
+                {"plans/features/az1-x/requirements.md": body.replace(f"{section}\n", "")},
+            )
+        )
+        assert any(
+            f"missing section {section}" in f.message for f in verdict.findings
+        ), f"{section} removed but not reported: {verdict.render()}"
+
+
+def test_each_required_section_of_design_is_reported_by_name(
+    tmp_path: pathlib.Path,
+) -> None:
+    body = DESIGN.format(work_item=1)
+    for section in ("## Solution", "## Docs impact", "## Size estimate", "## Risks"):
+        verdict = graded_directly(
+            build(
+                tmp_path,
+                {"plans/features/az1-x/design.md": body.replace(f"{section}\n", "")},
+            )
+        )
+        assert any(
+            f"missing section {section}" in f.message for f in verdict.findings
+        ), f"{section} removed but not reported: {verdict.render()}"
+
+
+def test_each_required_section_of_the_file_map_is_reported_by_name(
+    tmp_path: pathlib.Path,
+) -> None:
+    body = FILE_MAP.format(work_item=1)
+    for section in ("## Baseline", "## Map"):
+        verdict = graded_directly(
+            build(
+                tmp_path,
+                {"plans/features/az1-x/file-map-reference.md": body.replace(f"{section}\n", "")},
+            )
+        )
+        assert any(
+            f"missing section {section}" in f.message for f in verdict.findings
+        ), f"{section} removed but not reported: {verdict.render()}"
+
+
+def test_a_pbi_item_missing_its_sections_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                **feature_files(),
+                "plans/features/az1-x/items/az2-y.md": item_body("pbi", 2).replace(
+                    "## Verification\n", ""
+                ),
+            },
+        )
+    )
+    assert any("missing section ## Verification" in f.message for f in verdict.findings)
+
+
+def test_a_bug_item_uses_the_fixes_bug_section_set(tmp_path: pathlib.Path) -> None:
+    """A type: bug item file is a Fixes Bug item file: Bugs are never planned,
+    so its sections are the bugfix shape, not the PBI's."""
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                **feature_files(),
+                "plans/features/az1-x/items/az2-y.md": item_body("bug", 2).replace(
+                    "## Responsible Feature\n", ""
+                ),
+            },
+        )
+    )
+    messages = [f.message for f in verdict.findings if f.path.endswith("az2-y.md")]
+    assert "missing section ## Responsible Feature" in messages
+    assert not any("missing section ## What it delivers" in m for m in messages)
+
+
+def test_a_pbi_item_with_bug_sections_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                **feature_files(),
+                "plans/features/az1-x/items/az2-y.md": item_body("pbi", 2).replace(
+                    "## What it delivers\n", "## Current behaviour\n"
+                ),
+            },
+        )
+    )
+    assert any(
+        "missing section ## What it delivers" in f.message for f in verdict.findings
+    )
+
+
+def test_optional_sections_are_not_required(tmp_path: pathlib.Path) -> None:
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                **feature_files(),
+                "plans/features/az1-x/items/az2-y.md": item_body("pbi", 2).replace(
+                    "## Verification\n", "## Verification\n\n## Related\n"
+                ),
+            },
+        )
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+# ------------------------------------------------------------------ R4: EARS
+
+
+def test_every_numbered_acceptance_criterion_must_be_an_ears_sentence(
+    tmp_path: pathlib.Path,
+) -> None:
+    body = REQUIREMENTS.format(work_item=1).replace(
+        "- AC-1: THE SYSTEM SHALL keep the plan files in step with the board.",
+        "- AC-1: THE SYSTEM SHALL keep the plan files in step with the board.\n"
+        "- AC-2: keep the board in step.\n"
+        "- AC-3: THE SYSTEM SHALL also do this.\n",
+    )
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1),
+                "plans/features/az1-x/requirements.md": body,
+            },
+        )
+    )
+    ac2 = [f for f in verdict.findings if "AC-2" in f.message]
+    assert len(ac2) == 1, verdict.render()
+    assert not [f for f in verdict.findings if "AC-3" in f.message], verdict.render()
+    assert not [f for f in verdict.findings if "AC-1" in f.message], verdict.render()
+
+
+@pytest.mark.parametrize(
+    "opener",
+    (
+        "WHEN the board moves",
+        "WHILE the run is open",
+        "IF the plan drifts THEN",
+        "WHERE the file maps",
+    ),
+)
+def test_an_ears_opener_is_accepted_before_the_system_shall(
+    tmp_path: pathlib.Path, opener: str
+) -> None:
+    body = REQUIREMENTS.format(work_item=1).replace(
+        "- AC-1: THE SYSTEM SHALL keep the plan files in step with the board.",
+        f"- AC-1: {opener} THE SYSTEM SHALL keep the plan files in step with the board.",
+    )
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1),
+                "plans/features/az1-x/requirements.md": body,
+            },
+        )
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_an_if_opener_without_then_is_not_ears(tmp_path: pathlib.Path) -> None:
+    body = REQUIREMENTS.format(work_item=1).replace(
+        "- AC-1: THE SYSTEM SHALL keep the plan files in step with the board.",
+        "- AC-1: IF the plan drifts THE SYSTEM SHALL keep the plan files in step.",
+    )
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1),
+                "plans/features/az1-x/requirements.md": body,
+            },
+        )
+    )
+    assert any("AC-1" in f.message for f in verdict.findings), verdict.render()
+
+
+def test_non_criterion_lines_are_not_ears_checked(tmp_path: pathlib.Path) -> None:
+    body = REQUIREMENTS.format(work_item=1).replace(
+        "- AC-1: THE SYSTEM SHALL keep the plan files in step with the board.",
+        "AC-1 is the load-bearing criterion.\n\n"
+        "- AC-1: THE SYSTEM SHALL keep the plan files in step with the board.\n",
+    )
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1),
+                "plans/features/az1-x/requirements.md": body,
+            },
+        )
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+# ------------------------------------------------------------ R4: feature link
+
+
+def test_an_item_without_a_feature_link_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                **feature_files(),
+                "plans/features/az1-x/items/az2-y.md": item_body("pbi", 2).replace(
+                    f"feature: {AZ}/1\n", ""
+                ),
+            },
+        )
+    )
+    assert any("missing feature link" in f.message for f in verdict.findings)
+
+
+def test_an_item_feature_link_disagreeing_with_its_folder_is_reported(
+    tmp_path: pathlib.Path,
+) -> None:
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                **feature_files(),
+                "plans/features/az1-x/items/az2-y.md": item_body("pbi", 2, feature=999),
+            },
+        )
+    )
+    assert any("feature 999 disagrees with az1" in f.message for f in verdict.findings)
+
+
+def test_an_item_feature_link_must_be_a_board_url(tmp_path: pathlib.Path) -> None:
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                **feature_files(),
+                "plans/features/az1-x/items/az2-y.md": item_body("pbi", 2).replace(
+                    f"feature: {AZ}/1", "feature: 1"
+                ),
+            },
+        )
+    )
+    assert any("feature must be a board URL" in f.message for f in verdict.findings)
+
+
+# --------------------------------------------------------------- plan file keys
+
+
+def test_a_requirements_file_without_sources_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                "plans/features/az1-x/requirements.md": REQUIREMENTS.format(
+                    work_item=1
+                ).replace("sources:\n  - intent.md\n", "")
+            },
+        )
+    )
+    assert any("must link the documents it derives from" in f.message for f in verdict.findings)
+
+
+def test_requirements_sources_must_list_intent_first(tmp_path: pathlib.Path) -> None:
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                "plans/features/az1-x/requirements.md": REQUIREMENTS.format(
+                    work_item=1
+                ).replace("  - intent.md", "  - docs/architecture/workflow-automation.md"),
+            },
+        )
+    )
+    assert any("must list intent.md first" in f.message for f in verdict.findings)
+
+
+def test_a_design_file_without_sources_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                "plans/features/az1-x/design.md": DESIGN.format(
+                    work_item=1
+                ).replace("sources:\n  - requirements.md\n", "")
+            },
+        )
+    )
     assert any("must link the documents it derives from" in f.message for f in verdict.findings)
 
 
+def test_design_sources_must_list_requirements(tmp_path: pathlib.Path) -> None:
+    verdict = graded_directly(
+        build(
+            tmp_path,
+            {
+                "plans/features/az1-x/design.md": DESIGN.format(
+                    work_item=1
+                ).replace("  - requirements.md", "  - intent.md"),
+            },
+        )
+    )
+    assert any("must list requirements.md" in f.message for f in verdict.findings)
+
+
 def test_a_missing_last_update_is_reported(tmp_path: pathlib.Path) -> None:
     verdict = graded_directly(
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1).replace(
+                "plans/features/az1-x/intent.md": INTENT.format(work_item=1).replace(
                     "last_update: 2026-09-15T03:20:00Z\n", ""
                 )
             },
@@ -408,14 +983,37 @@ def test_an_item_type_outside_pbi_and_bug_is_reported(tmp_path: pathlib.Path) ->
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
-                "plans/features/az1-x/items/az2-y.md": ITEM.format(item_type="task", work_item=2),
+                **feature_files(),
+                "plans/features/az1-x/items/az2-y.md": item_body("task", 2),
             },
         )
     )
     assert any("type 'task' is not pbi or bug" in f.message for f in verdict.findings)
 
 
+def test_each_plan_file_type_is_enforced(tmp_path: pathlib.Path) -> None:
+    templates = {
+        "intent.md": INTENT,
+        "requirements.md": REQUIREMENTS,
+        "design.md": DESIGN,
+        "file-map-reference.md": FILE_MAP,
+    }
+    cases = {
+        "intent.md": ("intent", "feature"),
+        "requirements.md": ("feature", "design"),
+        "design.md": ("design", "file-map"),
+        "file-map-reference.md": ("file-map", "intent"),
+    }
+    for name, (want, wrong) in cases.items():
+        body = templates[name].format(work_item=1).replace(f"type: {want}", f"type: {wrong}")
+        verdict = graded_directly(
+            build(tmp_path / name.replace(".md", ""), {f"plans/features/az1-x/{name}": body})
+        )
+        assert any(
+            f"type must be {want!r}" in f.message for f in verdict.findings
+        ), f"{name} with type {wrong}: {verdict.render()}"
+
+
 def test_a_supporting_document_must_carry_the_tree_s_frontmatter(tmp_path: pathlib.Path) -> None:
     """A handoff without frontmatter is an undated wall of prose naming no work item
     — readable today, unattributable in a month. That is the state the channels
@@ -424,7 +1022,7 @@ def test_a_supporting_document_must_carry_the_tree_s_frontmatter(tmp_path: pathl
         build(
             tmp_path,
             {
-                "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
+                **feature_files(),
                 "plans/features/az1-x/handoff.md": "# handoff\n\nprose, no frontmatter\n",
             },
         )
@@ -453,7 +1051,7 @@ def test_a_redeclared_plans_tree_still_catches_a_legacy_lifecycle_dir(
     build(
         root,
         {
-            "roadmap/features/az1-x/spec.md": FEATURE.format(work_item=1),
+            "roadmap/features/az1-x/intent.md": INTENT.format(work_item=1),
             "roadmap/a_new/leftover.md": "# a leftover plan from before the migration\n",
         },
     )
@@ -490,12 +1088,7 @@ def test_ledger_md_is_allowed_at_the_plans_root(tmp_path: pathlib.Path) -> None:
 
 
 def test_ledger_yaml_at_the_plans_root_is_reported(tmp_path: pathlib.Path) -> None:
-    """The retired form is a finding, and the remedy names what IS allowed.
-
-    The message is derived from ROOT_ALLOWED_FILES rather than restated: the
-    hardcoded copy had drifted at both ends, naming `LEDGER.yaml` (no longer
-    allowed) and omitting `GAPS-AND-FINDINGS.md` (allowed all along).
-    """
+    """The retired form is a finding, and the remedy names what IS allowed."""
     verdict = graded_directly(
         build(tmp_path, {
             "plans/AGENTS.md": "x",