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

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

@@ -1,4 +1,12 @@
-"""LAY-016 — the exact active-work lifecycle and the ten-item boundary."""
+"""LAY-016 — at most ten open plans, by default.
+
+R7 (ADL process handover, 2026-10-12) retired `plans/GAPS-AND-FINDINGS.md`
+and with it the open-gaps half of this gate: the register columns, the
+at-most-ten-open-gaps rule and the `open-gaps` declaration are gone. The
+open-plans cap stays. A Feature's state is read from its `intent.md` — the one
+plan file that exists from the Feature's first day (R2); plan files carry the
+five Feature states (R1).
+"""
 
 from __future__ import annotations
 
@@ -17,44 +25,19 @@ from adl_compliance.policy.registry import load
 ROW = load().by_id("LAY-016")
 AZ = "https://dev.azure.com/org/project/_workitems/edit"
 CLEAN = pathlib.Path(__file__).parent / "fixtures" / "open-work-cap-clean"
-HEADER = (
-    "| Found | Finding | From plan | Item file | Work item |\n"
-    "| --- | --- | --- | --- | --- |\n"
-)
-
-
-def spec(status: str, item: int) -> str:
-    return f"---\ntype: feature\nstatus: {status}\nwork_item: {AZ}/{item}\n---\n"
 
 
-def item(status: str, item_id: int) -> str:
-    return f"---\ntype: bug\nstatus: {status}\nwork_item: {AZ}/{item_id}\n---\n"
+def intent(status: str, item: int) -> str:
+    return f"---\ntype: intent\nstatus: {status}\nwork_item: {AZ}/{item}\n---\n"
 
 
 def features(count: int, status: str = "New") -> dict[str, str]:
     return {
-        f"plans/features/az{600 + n}-feature-{n}/spec.md": spec(status, 600 + n)
+        f"plans/features/az{600 + n}-feature-{n}/intent.md": intent(status, 600 + n)
         for n in range(1, count + 1)
     }
 
 
-def register(*rows: str) -> dict[str, str]:
-    return {"plans/GAPS-AND-FINDINGS.md": HEADER + "".join(rows)}
-
-
-def unraised(n: int, finding: str | None = None) -> str:
-    return (
-        f"| 2026-09-17 | {finding or f'Unraised gap {n}'} | spec.md | TBD | TBD |\n"
-    )
-
-
-def linked(n: int, path: str) -> str:
-    return (
-        f"| 2026-09-17 | Linked gap {n} | spec.md | `{path}` | "
-        f"[{n}]({AZ}/{n}) |\n"
-    )
-
-
 def build(root: pathlib.Path, files: dict[str, str]) -> pathlib.Path:
     for relative, body in files.items():
         target = root / relative
@@ -79,11 +62,8 @@ def test_the_committed_clean_corpus_is_silent() -> None:
     assert verdict.outcome is Outcome.CLEAN, verdict.render()
 
 
-@pytest.mark.parametrize(
-    "status",
-    ("New", "In Planning", "Awaiting Approval", "Approved", "Spec Validation", "In Implementation", "In Testing", "In Review", "Updating Docs"),
-)
-def test_each_exact_active_plan_state_counts_as_open(
+@pytest.mark.parametrize("status", ("New", "In Progress", "Awaiting Release"))
+def test_each_exact_active_feature_state_counts_as_open(
     tmp_path: pathlib.Path, status: str
 ) -> None:
     verdict = grade(build(tmp_path, features(11, status)))
@@ -92,60 +72,72 @@ def test_each_exact_active_plan_state_counts_as_open(
 
 
 @pytest.mark.parametrize("status", ("Done", "Removed"))
-def test_each_exact_terminal_plan_state_is_closed(
+def test_each_exact_terminal_feature_state_is_closed(
     tmp_path: pathlib.Path, status: str
 ) -> None:
     tree = features(10)
     tree.update(
         {
-            f"plans/features/az999-{status.casefold()}/spec.md": spec(status, 999),
+            f"plans/features/az999-{status.casefold()}/intent.md": intent(status, 999),
         }
     )
     verdict = grade(build(tmp_path, tree))
     assert verdict.outcome is Outcome.CLEAN, verdict.render()
 
 
-@pytest.mark.parametrize("status", ("Active", "Closed", "Completed", "new", ""))
+@pytest.mark.parametrize("status", ("Approved", "In Implementation", "new", ""))
 def test_a_plan_status_outside_the_exact_board_vocabulary_is_could_not_run(
     tmp_path: pathlib.Path, status: str
 ) -> None:
     verdict = grade(
         build(
             tmp_path,
-            {"plans/features/az601-invalid/spec.md": spec(status, 601)},
+            {"plans/features/az601-invalid/intent.md": intent(status, 601)},
         )
     )
     assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
     assert "work item state" in verdict.message
 
 
-def test_a_plan_spec_must_belong_to_the_git_visible_file_set(
+def test_a_plan_intent_must_belong_to_the_git_visible_file_set(
     tmp_path: pathlib.Path,
 ) -> None:
-    spec_path = "plans/features/az601-feature/spec.md"
+    intent_path = "plans/features/az601-feature/intent.md"
     item_path = "plans/features/az601-feature/items/az701-visible-item.md"
     build(
         tmp_path,
         {
-            spec_path: spec("New", 601),
-            item_path: item("New", 701),
+            intent_path: intent("New", 601),
+            item_path: "---\ntype: pbi\nstatus: New\n---\n",
         },
     )
     verdict = grade(tmp_path, paths=(item_path,))
     assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
-    assert spec_path in verdict.message
+    assert intent_path in verdict.message
     assert "Git-visible file set" in verdict.message
 
 
 def test_status_text_in_the_body_cannot_set_a_plan_state(tmp_path: pathlib.Path) -> None:
-    body = "---\ntype: feature\n---\n\n# Notes\n\nstatus: Done\n"
+    body = "---\ntype: intent\n---\n\n# Notes\n\nstatus: Done\n"
     verdict = grade(
-        build(tmp_path, {"plans/features/az601-body-status/spec.md": body})
+        build(tmp_path, {"plans/features/az601-body-status/intent.md": body})
     )
     assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
     assert "missing status" in verdict.message
 
 
+def test_a_feature_folder_without_an_intent_is_not_counted(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A mid-migration Feature (no intent.md yet) neither counts as open nor
+    poisons the cap: LAY-009 reports the missing file."""
+    tree = features(11)
+    del tree["plans/features/az601-feature-1/intent.md"]
+    verdict = grade(build(tmp_path, tree))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert "az601-feature-1" not in verdict.render()
+
+
 def test_exactly_ten_open_plans_pass_and_eleven_fail_with_every_name(
     tmp_path: pathlib.Path,
 ) -> None:
@@ -167,7 +159,7 @@ def test_a_partial_file_set_counts_the_complete_plan_tree(
     verdict = runner.run(
         ROW,
         root,
-        ("plans/features/az601-feature-1/spec.md",),
+        ("plans/features/az601-feature-1/intent.md",),
         exhaustive=False,
         universe=universe,
         trees={"plans": "plans"},
@@ -177,167 +169,45 @@ def test_a_partial_file_set_counts_the_complete_plan_tree(
     assert "11 open plans, cap is 10" in verdict.render()
 
 
-@pytest.mark.parametrize(
-    "status",
-    ("New", "In Planning", "Awaiting Approval", "Approved", "Spec Validation", "In Implementation", "In Testing", "In Review", "Updating Docs"),
-)
-def test_unraised_and_each_linked_active_gap_state_both_count_as_open(
-    tmp_path: pathlib.Path, status: str
-) -> None:
-    item_path = "plans/features/az601-feature/items/az701-active-gap.md"
-    tree = {
-        **register(unraised(1), *(linked(701, item_path) for _ in range(10))),
-        "plans/features/az601-feature/spec.md": spec("Done", 601),
-        item_path: item(status, 701),
-    }
-    verdict = grade(build(tmp_path, tree))
-    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
-    assert "11 open gaps, cap is 10" in verdict.render()
-
-
-@pytest.mark.parametrize("status", ("Done", "Removed"))
-def test_each_linked_terminal_gap_state_must_be_deleted_from_the_register(
-    tmp_path: pathlib.Path, status: str
-) -> None:
-    item_path = "plans/features/az601-feature/items/az701-closed-gap.md"
-    tree = {
-        **register(linked(701, item_path)),
-        "plans/features/az601-feature/spec.md": spec("Done", 601),
-        item_path: item(status, 701),
-    }
-    verdict = grade(build(tmp_path, tree))
-    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
-    assert "closed gap" in verdict.render().casefold()
-    assert "delete" in verdict.findings[0].fix.casefold()
-
-
-@pytest.mark.parametrize(
-    "work_item",
-    (
-        "ticket 701",
-        f"[701]({AZ}/702)",
-        f"701 ({AZ}/701)",
-    ),
-)
-def test_a_malformed_work_item_cell_is_could_not_run_not_a_raised_gap(
-    tmp_path: pathlib.Path, work_item: str
-) -> None:
-    row = f"| 2026-09-17 | Gap | spec.md | `item.md` | {work_item} |\n"
-    verdict = grade(build(tmp_path, register(row)))
-    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
-    assert "work item link" in verdict.message
-
+# --------------------------------------------------------------- R7: retired
 
-def test_a_linked_gap_requires_the_named_item_file(tmp_path: pathlib.Path) -> None:
-    verdict = grade(
-        build(
-            tmp_path,
-            register(linked(701, "plans/features/az601-feature/items/az701-missing.md")),
-        )
-    )
-    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
-    assert "item file" in verdict.message
-
-
-@pytest.mark.parametrize("spelling", ("absolute", "parent-relative"))
-def test_a_linked_gap_rejects_an_item_path_outside_the_repository(
-    tmp_path: pathlib.Path, spelling: str
-) -> None:
-    outside = tmp_path.parent / f"{tmp_path.name}-outside"
-    outside_item = (
-        outside
-        / "plans/features/az601-feature/items/az701-outside-gap.md"
-    )
-    outside_item.parent.mkdir(parents=True, exist_ok=True)
-    outside_item.write_text(item("New", 701), encoding="utf-8")
-    if spelling == "absolute":
-        item_path = str(outside_item)
-    else:
-        item_path = str(outside_item.relative_to(tmp_path.parent))
-        item_path = f"../{item_path}"
-    verdict = grade(build(tmp_path, register(linked(701, item_path))))
-    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
-    assert "normalized repository-relative" in verdict.message
-
-
-def test_a_linked_gap_item_must_belong_to_the_git_visible_file_set(
-    tmp_path: pathlib.Path,
-) -> None:
-    item_path = "plans/features/az601-feature/items/az701-untracked-gap.md"
-    tree = {
-        **register(linked(701, item_path)),
-        "plans/features/az601-feature/spec.md": spec("Done", 601),
-        item_path: item("New", 701),
-    }
-    build(tmp_path, tree)
-    verdict = grade(tmp_path, paths=("plans/GAPS-AND-FINDINGS.md",))
-    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
-    assert "Git-visible file set" in verdict.message
-
-
-def test_a_linked_gap_with_an_invalid_item_state_is_could_not_run(
+def test_a_gaps_register_at_the_plans_root_is_not_read(
     tmp_path: pathlib.Path,
 ) -> None:
-    item_path = "plans/features/az601-feature/items/az701-invalid-gap.md"
-    tree = {
-        **register(linked(701, item_path)),
-        "plans/features/az601-feature/spec.md": spec("Done", 601),
-        item_path: item("Closed", 701),
-    }
+    """R7: `plans/GAPS-AND-FINDINGS.md` is retired -- its content grades nothing
+    and its absence is not required either."""
+    tree = features(1)
+    tree["plans/GAPS-AND-FINDINGS.md"] = "not a table at all\n"
     verdict = grade(build(tmp_path, tree))
-    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
-    assert "work item state" in verdict.message
-
-
-def test_an_escaped_pipe_in_a_finding_does_not_break_the_table(
-    tmp_path: pathlib.Path,
-) -> None:
-    rows = tuple(unraised(n, rf"Gap {n} uses a \| b") for n in range(1, 11))
-    verdict = grade(build(tmp_path, register(*rows)))
-    assert verdict.outcome is Outcome.CLEAN, verdict.render()
-
-
-def test_a_short_all_dash_divider_row_is_could_not_run(tmp_path: pathlib.Path) -> None:
-    malformed = {"plans/GAPS-AND-FINDINGS.md": HEADER.splitlines()[0] + "\n| --- | --- |\n"}
-    verdict = grade(build(tmp_path, malformed))
-    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
-    assert "2 cells" in verdict.message
-
-
-def test_an_on_disk_register_outside_the_git_visible_set_is_not_read(
-    tmp_path: pathlib.Path,
-) -> None:
-    spec_path = "plans/features/az601-feature/spec.md"
-    tree = {
-        spec_path: spec("Done", 601),
-        **register(*(unraised(n) for n in range(1, 12))),
-    }
-    build(tmp_path, tree)
-    verdict = grade(tmp_path, paths=(spec_path,))
     assert verdict.outcome is Outcome.CLEAN, verdict.render()
 
 
-def test_exactly_ten_open_gaps_pass_and_eleven_fail_with_every_row(
+def test_the_retired_open_gaps_declaration_is_ignored(
     tmp_path: pathlib.Path,
 ) -> None:
-    ten = grade(build(tmp_path / "ten", register(*(unraised(n) for n in range(1, 11)))))
-    eleven = grade(
-        build(tmp_path / "eleven", register(*(unraised(n) for n in range(1, 12))))
+    """R7: `open-gaps` named a cap that no longer exists; an unreadable value
+    for it is not a could-not-run of the plan cap that does."""
+    root = build(tmp_path, features(1))
+    ctx = Context(
+        row=ROW,
+        root=root,
+        inputs={"plans_root": root / "plans"},
+        declarations={"open-gaps": "abc"},
     )
-    assert ten.outcome is Outcome.CLEAN, ten.render()
-    assert eleven.outcome is Outcome.FINDINGS, eleven.render()
-    finding = next(f for f in eleven.findings if "open gaps" in f.message)
-    for n in range(1, 12):
-        assert f"Unraised gap {n}" in finding.message
+    verdict = decide(
+        ROW,
+        tuple(OpenWorkCap().run(ctx, FileSet(paths=tuple(features(1))))),
+        advisories=(),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
 
 
-# ------------------------------------------------- the two caps are declarable
-# `[controls.compliance.limits].open_gaps` / `.open_plans` reach the engine as
-# `--declare open-gaps=N` / `--declare open-plans=N`. The engine default stays
-# ten for each; a repository that carries more open work today states its own
-# cap in its adl-config.toml, and a value the engine cannot read is a
-# could-not-run, never a quiet fall back to ten. The two caps are independent.
-GAPS_DECLARATION = "open-gaps"
+# ------------------------------------------------------- the cap is declarable
+# `[controls.compliance.limits].open_plans` reaches the engine as
+# `--declare open-plans=N`. The engine default stays ten; a repository that
+# carries more open Features today states its own cap in its adl-config.toml,
+# and a value the engine cannot read is a could-not-run, never a quiet fall
+# back to ten.
 PLANS_DECLARATION = "open-plans"
 
 
@@ -355,37 +225,15 @@ def grade_declared(
     return decide(ROW, tuple(OpenWorkCap().run(ctx, FileSet(paths=paths))), advisories=())
 
 
-def gaps(count: int) -> dict[str, str]:
-    return register(*(unraised(n) for n in range(1, count + 1)))
-
-
 def test_no_declaration_keeps_the_engine_default_of_ten() -> None:
     ctx = Context(row=ROW, root=CLEAN)
-    assert OpenWorkCap().open_gaps_limit(ctx) == 10
     assert OpenWorkCap().open_plans_limit(ctx) == 10
     assert OpenWorkCap.OPEN_LIMIT == 10
 
 
-def test_a_declared_gap_cap_is_the_effective_gap_cap_and_leaves_the_plan_cap() -> None:
-    ctx = Context(row=ROW, root=CLEAN, declarations={GAPS_DECLARATION: "37"})
-    assert OpenWorkCap().open_gaps_limit(ctx) == 37
-    assert OpenWorkCap().open_plans_limit(ctx) == 10
-
-
-def test_a_declared_plan_cap_is_the_effective_plan_cap_and_leaves_the_gap_cap() -> None:
+def test_a_declared_plan_cap_is_the_effective_plan_cap() -> None:
     ctx = Context(row=ROW, root=CLEAN, declarations={PLANS_DECLARATION: "11"})
     assert OpenWorkCap().open_plans_limit(ctx) == 11
-    assert OpenWorkCap().open_gaps_limit(ctx) == 10
-
-
-def test_a_declared_gap_cap_accepts_gaps_the_default_would_refuse(
-    tmp_path: pathlib.Path,
-) -> None:
-    root = build(tmp_path, gaps(14))
-    assert grade(root).outcome is Outcome.FINDINGS
-    result = grade_declared(root, {GAPS_DECLARATION: "14"})
-    assert result.outcome is Outcome.CLEAN, result.render()
-    assert result.findings == ()
 
 
 def test_a_declared_plan_cap_accepts_plans_the_default_would_refuse(
@@ -398,19 +246,6 @@ def test_a_declared_plan_cap_accepts_plans_the_default_would_refuse(
     assert result.findings == ()
 
 
-def test_over_a_declared_gap_cap_the_finding_names_the_declared_cap_not_ten(
-    tmp_path: pathlib.Path,
-) -> None:
-    result = grade_declared(build(tmp_path, gaps(16)), {GAPS_DECLARATION: "15"})
-    assert result.outcome is Outcome.FINDINGS, result.render()
-    assert len(result.findings) == 1
-    text = result.render()
-    assert "16 open gaps, cap is 15" in text, text
-    assert "cap is 10" not in text, text
-    for n in range(1, 17):
-        assert f"Unraised gap {n}" in text
-
-
 def test_over_a_declared_plan_cap_the_finding_names_the_declared_cap_not_ten(
     tmp_path: pathlib.Path,
 ) -> None:
@@ -422,18 +257,6 @@ def test_over_a_declared_plan_cap_the_finding_names_the_declared_cap_not_ten(
     assert "cap is 10" not in text, text
 
 
-@pytest.mark.parametrize("cap", (1, 3, 10, 25))
-def test_exactly_the_declared_gap_cap_passes_and_one_more_fails(
-    tmp_path: pathlib.Path, cap: int
-) -> None:
-    declared = {GAPS_DECLARATION: str(cap)}
-    at_cap = grade_declared(build(tmp_path / "at", gaps(cap)), declared)
-    over = grade_declared(build(tmp_path / "over", gaps(cap + 1)), declared)
-    assert at_cap.outcome is Outcome.CLEAN, at_cap.render()
-    assert over.outcome is Outcome.FINDINGS, over.render()
-    assert f"{cap + 1} open gaps, cap is {cap}" in over.render()
-
-
 @pytest.mark.parametrize("cap", (1, 3, 10, 25))
 def test_exactly_the_declared_plan_cap_passes_and_one_more_fails(
     tmp_path: pathlib.Path, cap: int
@@ -449,120 +272,66 @@ def test_exactly_the_declared_plan_cap_passes_and_one_more_fails(
 def test_a_declared_cap_below_ten_refuses_what_the_default_would_accept(
     tmp_path: pathlib.Path,
 ) -> None:
-    root = build(tmp_path, {**gaps(5), **features(5)})
+    root = build(tmp_path, features(5))
     assert grade(root).outcome is Outcome.CLEAN
-    result = grade_declared(root, {GAPS_DECLARATION: "4", PLANS_DECLARATION: "4"})
+    result = grade_declared(root, {PLANS_DECLARATION: "4"})
     assert result.outcome is Outcome.FINDINGS, result.render()
-    text = result.render()
-    assert "5 open gaps, cap is 4" in text, text
-    assert "5 open plans, cap is 4" in text, text
+    assert "5 open plans, cap is 4" in result.render(), result.render()
 
 
 def test_declaring_ten_grades_exactly_like_no_declaration(tmp_path: pathlib.Path) -> None:
-    root = build(tmp_path, {**gaps(11), **features(11)})
-    declared = grade_declared(root, {GAPS_DECLARATION: "10", PLANS_DECLARATION: "10"})
+    root = build(tmp_path, features(11))
+    declared = grade_declared(root, {PLANS_DECLARATION: "10"})
     default = grade(root)
     assert declared.outcome is default.outcome is Outcome.FINDINGS
     assert [f.render() for f in declared.findings] == [f.render() for f in default.findings]
-    assert "11 open gaps, cap is 10" in declared.render()
     assert "11 open plans, cap is 10" in declared.render()
 
 
-def test_the_gap_cap_does_not_move_the_plan_cap(tmp_path: pathlib.Path) -> None:
-    root = build(tmp_path, {**gaps(15), **features(11)})
-    result = grade_declared(root, {GAPS_DECLARATION: "15"})
-    assert result.outcome is Outcome.FINDINGS, result.render()
-    assert len(result.findings) == 1
-    text = result.render()
-    assert "11 open plans, cap is 10" in text, text
-    assert "open gaps" not in text, text
-
-
-def test_the_plan_cap_does_not_move_the_gap_cap(tmp_path: pathlib.Path) -> None:
-    root = build(tmp_path, {**gaps(11), **features(15)})
-    result = grade_declared(root, {PLANS_DECLARATION: "15"})
-    assert result.outcome is Outcome.FINDINGS, result.render()
-    assert len(result.findings) == 1
-    text = result.render()
-    assert "11 open gaps, cap is 10" in text, text
-    assert "open plans" not in text, text
-
-
-def test_both_caps_declared_together_each_apply_to_their_own_count(
-    tmp_path: pathlib.Path,
-) -> None:
-    root = build(tmp_path, {**gaps(37), **features(11)})
-    result = grade_declared(root, {GAPS_DECLARATION: "37", PLANS_DECLARATION: "11"})
-    assert result.outcome is Outcome.CLEAN, result.render()
-    one_below = grade_declared(root, {GAPS_DECLARATION: "36", PLANS_DECLARATION: "10"})
-    assert one_below.outcome is Outcome.FINDINGS, one_below.render()
-    text = one_below.render()
-    assert "37 open gaps, cap is 36" in text, text
-    assert "11 open plans, cap is 10" in text, text
-
-
-def test_an_unrelated_declaration_does_not_change_either_cap(tmp_path: pathlib.Path) -> None:
-    root = build(tmp_path, {**gaps(11), **features(11)})
+def test_an_unrelated_declaration_does_not_change_the_cap(tmp_path: pathlib.Path) -> None:
+    root = build(tmp_path, features(11))
     result = grade_declared(
         root,
         {"license": "Proprietary", "root-dirs": "apps", "scripts-direct-files": "20"},
     )
-    text = result.render()
-    assert "11 open gaps, cap is 10" in text, text
-    assert "11 open plans, cap is 10" in text, text
+    assert "11 open plans, cap is 10" in result.render(), result.render()
 
 
 def test_the_remedy_states_the_effective_cap_and_never_hard_codes_ten(
     tmp_path: pathlib.Path,
 ) -> None:
-    root = build(tmp_path, {**gaps(16), **features(13)})
-    result = grade_declared(root, {GAPS_DECLARATION: "15", PLANS_DECLARATION: "12"})
-    by_subject = {
-        ("gaps" if "open gaps" in f.message else "plans"): f.fix for f in result.findings
-    }
-    assert "no more than 15 remain" in by_subject["gaps"], by_subject
-    assert "no more than 12 remain" in by_subject["plans"], by_subject
-    for fix in by_subject.values():
-        assert re.search(r"\bten\b", fix, re.IGNORECASE) is None, fix
+    result = grade_declared(build(tmp_path, features(13)), {PLANS_DECLARATION: "12"})
+    fix = result.findings[0].fix
+    assert "no more than 12 remain" in fix, fix
+    assert re.search(r"\bten\b", fix, re.IGNORECASE) is None, fix
 
 
 def test_the_default_remedy_states_the_cap_as_a_number(tmp_path: pathlib.Path) -> None:
-    result = grade(build(tmp_path, {**gaps(11), **features(11)}))
-    assert len(result.findings) == 2
-    for finding in result.findings:
-        assert "no more than 10 remain" in finding.fix, finding.fix
-        assert re.search(r"\bten\b", finding.fix, re.IGNORECASE) is None, finding.fix
+    result = grade(build(tmp_path, features(11)))
+    assert len(result.findings) == 1
+    assert "no more than 10 remain" in result.findings[0].fix, result.findings[0].fix
+    assert re.search(r"\bten\b", result.findings[0].fix, re.IGNORECASE) is None
 
 
 UNREADABLE = ["abc", "0", "-3", "2.5", "", "+20", "1_0", "２０"]
 
 
 @pytest.mark.parametrize("value", UNREADABLE)
-@pytest.mark.parametrize("name", (GAPS_DECLARATION, PLANS_DECLARATION))
 def test_an_unreadable_declared_cap_could_not_run(
-    tmp_path: pathlib.Path, name: str, value: str
+    tmp_path: pathlib.Path, value: str
 ) -> None:
     """Never a silent fall back to ten: not a base-10 positive integer is loud."""
-    root = build(tmp_path, {**features(1), **gaps(1)})
+    root = build(tmp_path, features(1))
     with pytest.raises(CouldNotRun) as raised:
-        grade_declared(root, {name: value})
+        grade_declared(root, {PLANS_DECLARATION: value})
     message = str(raised.value)
-    assert name in message, message
+    assert PLANS_DECLARATION in message, message
     assert repr(value) in message, message
     assert could_not_run(ROW, message).outcome is Outcome.COULD_NOT_RUN
 
 
-def test_a_bad_declaration_for_the_cap_that_is_not_exceeded_is_still_could_not_run(
-    tmp_path: pathlib.Path,
-) -> None:
-    """Eleven gaps exceed the gap cap; the unreadable plan cap must still not be skipped."""
-    root = build(tmp_path, gaps(11))
-    with pytest.raises(CouldNotRun, match=PLANS_DECLARATION):
-        grade_declared(root, {PLANS_DECLARATION: "abc"})
-
-
 def test_a_declared_cap_reaches_the_check_through_the_runner(tmp_path: pathlib.Path) -> None:
-    root = build(tmp_path, {**features(11), **gaps(12)})
+    root = build(tmp_path, features(11))
     universe = tuple(
         str(path.relative_to(root)) for path in root.rglob("*") if path.is_file()
     )
@@ -579,8 +348,8 @@ def test_a_declared_cap_reaches_the_check_through_the_runner(tmp_path: pathlib.P
 
     default = run(None)
     assert default.outcome is Outcome.FINDINGS, default.render()
-    declared = run({GAPS_DECLARATION: "12", PLANS_DECLARATION: "11"})
+    declared = run({PLANS_DECLARATION: "11"})
     assert declared.outcome is Outcome.CLEAN, declared.render()
-    refused = run({GAPS_DECLARATION: "abc"})
+    refused = run({PLANS_DECLARATION: "abc"})
     assert refused.outcome is Outcome.COULD_NOT_RUN, refused.render()
-    assert GAPS_DECLARATION in refused.message
+    assert PLANS_DECLARATION in refused.message

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

@@ -7,14 +7,14 @@ from typing import ClassVar
 
 
 class PlanMetadata:
-    """The plans tree's board-state vocabulary and frontmatter readers."""
+    """The plans tree's board-state vocabulary and frontmatter readers (R1: plan files take the FEATURE states, item files the twelve item states)."""
 
-    WORK_ITEM_STATUSES: ClassVar[tuple[str, ...]] = (
+    ITEM_STATUSES: ClassVar[tuple[str, ...]] = (
         "New",
         "In Planning",
         "Awaiting Approval",
         "Approved",
-        "Spec Validation",
+        "Design Validation",
         "In Implementation",
         "In Testing",
         "In Review",
@@ -23,11 +23,26 @@ class PlanMetadata:
         "Parked for Removal",
         "Removed",
     )
-    ACTIVE_STATUSES: ClassVar[frozenset[str]] = frozenset(WORK_ITEM_STATUSES[:9])
-    TERMINAL_STATUSES: ClassVar[frozenset[str]] = frozenset(WORK_ITEM_STATUSES[9:])
+    ITEM_ACTIVE_STATUSES: ClassVar[frozenset[str]] = frozenset(ITEM_STATUSES[:9])
+    ITEM_TERMINAL_STATUSES: ClassVar[frozenset[str]] = frozenset(ITEM_STATUSES[9:])
+
+    FEATURE_STATUSES: ClassVar[tuple[str, ...]] = (
+        "New",
+        "In Progress",
+        "Awaiting Release",
+        "Done",
+        "Removed",
+    )
+    FEATURE_ACTIVE_STATUSES: ClassVar[frozenset[str]] = frozenset(
+        FEATURE_STATUSES[:3]
+    )
+    FEATURE_TERMINAL_STATUSES: ClassVar[frozenset[str]] = frozenset(
+        FEATURE_STATUSES[3:]
+    )
 
     STATUS_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^status:\s*(.+)$")
     WORK_ITEM_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^work_item:\s*(.+)$")
+    FEATURE_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^feature:\s*(.+)$")
     WORK_ITEM_URL: ClassVar[re.Pattern[str]] = re.compile(
         r"^https://dev\.azure\.com/\S+/_workitems/edit/([0-9]+)/?$"
     )
@@ -56,3 +71,14 @@ class PlanMetadata:
         if not found:
             return None, "not a work item URL"
         return int(found.group(1)), None
+
+    @classmethod
+    def feature_id(cls, body: str) -> tuple[int | None, str | None]:
+        """Return the `feature:` link's Azure DevOps id, or why unreadable."""
+        raw = cls.field(body, cls.FEATURE_LINE)
+        if raw is None:
+            return None, "missing"
+        found = cls.WORK_ITEM_URL.match(raw)
+        if not found:
+            return None, "not a work item URL"
+        return int(found.group(1)), None