its-magic 0.1.3-2 → 0.1.3-4

package/template/tests/us0118_contract_test.py

@@ -0,0 +1,330 @@
+"""
+US-0118 contract tests (R-0106 Q4 LOCKED — 12 `test_us0118_*` markers).
+
+Covers:
+    - Each work-kind classification (DOC / MINI / CODE).
+    - Each recommended phase plan.
+    - Default-off zero-overhead behavior.
+    - L8 precedence vs explicit DELIVERY_MODE / AUTO_PHASE_*.
+    - Operator override path (backlog-row accepted recommendation).
+    - Each fail-closed reason code in the WORK_KIND_* family.
+    - --explain rule_trace emission.
+    - classify_touched_files reuse boundary (Q9 LOCKED import contract).
+
+Pure stdlib pytest — no external deps. Active + `template/` parity.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+_SCRIPTS_DIR = _REPO_ROOT / "scripts"
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+import work_kind_classify_lib as wkc  # noqa: E402
+import work_kind_routing_lib as wkr  # noqa: E402
+from work_kind_classify_lib import (  # noqa: E402
+    WorkKind,
+    classify_work_kind,
+)
+from work_kind_routing_lib import resolve_delivery_mode_with_work_kind  # noqa: E402
+
+# Also import dev_environment_lib to verify the reuse boundary.
+import dev_environment_lib  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# AC-1, AC-2 — work-kind classification + phase plans
+# ---------------------------------------------------------------------------
+
+
+def test_us0118_doc_kind_routes_to_lean_plan():
+    """DOC kind → `[intake, execute, release]` (skip discovery/research/
+    architecture/sprint-plan/plan-verify/qa/verify-work)."""
+    result = classify_work_kind(
+        story_prose="Update README",
+        acceptance_criteria=["AC-1 README updated"],
+        touched_file_hints=["docs/engineering/runbook.md", "docs/product/backlog.md"],
+    )
+    assert result.work_kind is WorkKind.DOC
+    assert result.recommended_phase_plan == ["intake", "execute", "release"]
+    assert result.recommended_delivery_mode == "ultra_lean"
+
+
+def test_us0118_mini_kind_routes_to_ultra_lean():
+    """MINI kind → ultra_lean when mega_quick ineligible (AC count > 3)."""
+    result = classify_work_kind(
+        story_prose="Tweak nginx config",
+        acceptance_criteria=["AC-1", "AC-2", "AC-3", "AC-4"],  # 4 > 3
+        touched_file_hints=[".env.example"],
+        component_scope="web",
+    )
+    assert result.work_kind is WorkKind.MINI
+    assert result.recommended_delivery_mode == "ultra_lean"
+    assert result.recommended_phase_plan == ["spec", "plan", "build+verify", "ship"]
+
+
+def test_us0118_mini_kind_routes_to_mega_quick_when_eligible():
+    """MINI kind + US-0096 eligibility (≤3 ACs, single component, no DEC)
+    → mega_quick."""
+    result = classify_work_kind(
+        story_prose="Tiny fix",
+        acceptance_criteria=["AC-1", "AC-2"],  # 2 ≤ 3
+        touched_file_hints=[".env.example"],
+        component_scope="web",
+        has_companion_dec=False,
+    )
+    assert result.work_kind is WorkKind.MINI
+    assert result.recommended_delivery_mode == "mega_quick"
+    assert result.recommended_phase_plan == ["quick"]
+
+
+def test_us0118_code_kind_routes_to_standard():
+    """CODE kind (tier A — package.json, or any non-skip source path) →
+    standard full lifecycle."""
+    result = classify_work_kind(
+        story_prose="New feature",
+        acceptance_criteria=["AC-1", "AC-2", "AC-3", "AC-4"],
+        touched_file_hints=["package.json", "src/index.ts"],
+    )
+    assert result.work_kind is WorkKind.CODE
+    assert result.recommended_delivery_mode == "standard"
+    assert result.recommended_phase_plan == [
+        "intake",
+        "discovery",
+        "research",
+        "architecture",
+        "sprint-plan",
+        "plan-verify",
+        "execute",
+        "qa",
+        "verify-work",
+        "release",
+        "refresh-context",
+    ]
+
+
+# ---------------------------------------------------------------------------
+# AC-6 — L8 precedence chain
+# ---------------------------------------------------------------------------
+
+
+def test_us0118_explicit_delivery_mode_wins_over_work_kind():
+    """L8 precedence: explicit DELIVERY_MODE wins over WORK_KIND_ROUTING-
+    derived recommendation even when the story is CODE."""
+    mode, plan, reason = resolve_delivery_mode_with_work_kind(
+        scratchpad={"WORK_KIND_ROUTING": "1", "DELIVERY_MODE": "ultra_lean"},
+        story_prose="code feature",
+        ac_set=["AC-1", "AC-2", "AC-3", "AC-4"],
+        touched_file_hints=["package.json", "src/index.ts"],
+    )
+    assert mode == "ultra_lean"
+    # Explicit resolution → reason is None (no conflict because no
+    # backlog recommendation was supplied to compare against).
+    assert reason is None
+    assert plan == ["spec", "plan", "build+verify", "ship"]
+
+
+def test_us0118_auto_phase_wins_over_work_kind():
+    """L8 precedence: explicit AUTO_PHASE_* wins over WORK_KIND_ROUTING-
+    derived recommendation."""
+    mode, plan, reason = resolve_delivery_mode_with_work_kind(
+        scratchpad={
+            "WORK_KIND_ROUTING": "1",
+            "AUTO_PHASE_PLAN": '["spec","plan"]',
+        },
+        story_prose="code feature",
+        ac_set=["AC-1"],
+        touched_file_hints=["package.json"],
+    )
+    assert mode == "standard"
+    # Explicit AUTO_PHASE_* resolution → reason is None.
+    assert reason is None
+
+
+# ---------------------------------------------------------------------------
+# AC-3, AC-8 — default-off zero-overhead + backward compat
+# ---------------------------------------------------------------------------
+
+
+def test_us0118_routing_off_is_noop():
+    """WORK_KIND_ROUTING=0 → zero overhead: returns standard + full plan +
+    WORK_KIND_ROUTING_OFF; classifier NOT invoked."""
+    mode, plan, reason = resolve_delivery_mode_with_work_kind(
+        scratchpad={"WORK_KIND_ROUTING": "0"},
+        story_prose="anything",
+        ac_set=["AC-1"],
+        touched_file_hints=["docs/foo.md"],
+    )
+    assert mode == "standard"
+    assert reason == wkc.WORK_KIND_ROUTING_OFF
+    assert plan == wkr.FULL_STANDARD_PLAN
+
+
+def test_us0118_default_off_zero_overhead():
+    """WORK_KIND_ROUTING=0 behavior byte-identical to pre-US-0118
+    (standard delivery mode + full canonical phase plan)."""
+    # Absent key → treated as "0" (default-off).
+    mode1, plan1, reason1 = resolve_delivery_mode_with_work_kind(
+        scratchpad={},
+        story_prose="anything",
+        ac_set=["AC-1"],
+        touched_file_hints=["docs/foo.md"],
+    )
+    mode2, plan2, reason2 = resolve_delivery_mode_with_work_kind(
+        scratchpad={"WORK_KIND_ROUTING": "0"},
+        story_prose="different",
+        ac_set=["AC-99"],
+        touched_file_hints=["src/x.ts"],
+    )
+    assert (mode1, plan1, reason1) == (mode2, plan2, reason2)
+    assert mode1 == "standard"
+    assert reason1 == wkc.WORK_KIND_ROUTING_OFF
+
+
+# ---------------------------------------------------------------------------
+# AC-8 — reuse boundary (Q9 LOCKED import contract)
+# ---------------------------------------------------------------------------
+
+
+def test_us0118_classify_touched_files_reuse():
+    """classify_touched_files imported from dev_environment_lib — NOT
+    reimplemented in work_kind_classify_lib (Q9 LOCKED)."""
+    # The classifier module must reference the same function object.
+    assert wkc.classify_touched_files is dev_environment_lib.classify_touched_files
+    assert wkc.TIER_C_SKIP_PREFIXES is dev_environment_lib.TIER_C_SKIP_PREFIXES
+    # And the classifier produces tier-consistent results.
+    assert wkc.classify_touched_files(["package.json"]) == "A"
+    assert wkc.classify_touched_files([".env.example"]) == "B"
+    assert wkc.classify_touched_files(["docs/foo.md"]) is None
+
+
+# ---------------------------------------------------------------------------
+# AC-5, AC-9 — intake evidence schema extension
+# ---------------------------------------------------------------------------
+
+
+def test_us0118_intake_evidence_records_work_kind():
+    """The classifier output carries the intake-evidence schema extension
+    fields (work_kind, recommended_delivery_mode, work_kind_operator_decision)
+    so /intake step 5 can persist them directly."""
+    result = classify_work_kind(
+        story_prose="README update",
+        acceptance_criteria=["AC-1"],
+        touched_file_hints=["docs/foo.md"],
+    )
+    out = result.as_dict()
+    # work_kind is a string in the serialized form.
+    assert out["work_kind"] == "doc"
+    assert out["recommended_delivery_mode"] in ("standard", "ultra_lean", "mega_quick")
+    # work_kind_operator_decision defaults to None until the operator
+    # accept/override gate records a value.
+    assert "work_kind_operator_decision" in out
+
+
+# ---------------------------------------------------------------------------
+# AC-7 — fail-closed reason codes (R-0106 Q2 LOCKED)
+# ---------------------------------------------------------------------------
+
+
+def test_us0118_reason_codes_preserved():
+    """All WORK_KIND_* reason codes are emitted by the appropriate failure
+    modes (R-0106 Q2 LOCKED)."""
+    # WORK_KIND_ROUTING_OFF — info-only when flag off.
+    _, _, reason = resolve_delivery_mode_with_work_kind(
+        scratchpad={"WORK_KIND_ROUTING": "0"},
+        story_prose="x",
+        ac_set=["AC-1"],
+        touched_file_hints=["docs/foo.md"],
+    )
+    assert reason == wkc.WORK_KIND_ROUTING_OFF
+
+    # WORK_KIND_DELIVERY_MODE_CONFLICT — explicit DELIVERY_MODE conflicts
+    # with backlog-row recommendation.
+    _, _, reason = resolve_delivery_mode_with_work_kind(
+        scratchpad={"WORK_KIND_ROUTING": "1", "DELIVERY_MODE": "ultra_lean"},
+        story_prose="x",
+        ac_set=["AC-1"],
+        touched_file_hints=["package.json"],
+        backlog_work_kind="code",
+        backlog_recommended_delivery_mode="standard",
+    )
+    assert reason == wkc.WORK_KIND_DELIVERY_MODE_CONFLICT
+
+    # WORK_KIND_CLASSIFY_FAILED — classifier raises → fail-closed standard.
+    _, _, reason = resolve_delivery_mode_with_work_kind(
+        scratchpad={"WORK_KIND_ROUTING": "1"},
+        story_prose="x",
+        ac_set=["AC-1"],
+        touched_file_hints=None,  # type: ignore[arg-type]  # provokes TypeError
+    )
+    assert reason == "WORK_KIND_CLASSIFY_FAILED"
+
+    # All reason codes are present in the WORK_KIND_REASON_CODES tuple.
+    expected = {
+        "WORK_KIND_ROUTING_OFF",
+        "WORK_KIND_DELIVERY_MODE_CONFLICT",
+        "WORK_KIND_CLASSIFY_FAILED",
+        "WORK_KIND_UNKNOWN_ROUTE",
+        "WORK_KIND_PLAN_COVERAGE_MISSING",
+        "WORK_KIND_TIE_BREAK_APPLIED",
+    }
+    assert set(wkc.WORK_KIND_REASON_CODES) == expected
+    # Every reason code has remediation guidance.
+    for code in wkc.WORK_KIND_REASON_CODES:
+        assert code in wkc.REASON_CODE_REMEDIATION
+        assert wkc.REASON_CODE_REMEDIATION[code]
+
+
+# ---------------------------------------------------------------------------
+# AC-1 — --explain flag emits rule_trace (Q3 LOCKED)
+# ---------------------------------------------------------------------------
+
+
+def test_us0118_explain_emits_rule_trace():
+    """--explain flag (explain=True) emits a non-empty rule_trace list of
+    (rule_id, matched_signal, contribution) tuples."""
+    result = classify_work_kind(
+        story_prose="code feature",
+        acceptance_criteria=["AC-1"],
+        touched_file_hints=["package.json"],
+        explain=True,
+    )
+    assert result.rule_trace
+    for entry in result.rule_trace:
+        assert isinstance(entry, tuple)
+        assert len(entry) == 3
+        rule_id, matched_signal, contribution = entry
+        assert isinstance(rule_id, str) and rule_id
+        assert isinstance(matched_signal, str) and matched_signal
+        assert isinstance(contribution, str) and contribution
+
+    # Without explain, rule_trace is empty.
+    no_explain = classify_work_kind(
+        story_prose="code feature",
+        acceptance_criteria=["AC-1"],
+        touched_file_hints=["package.json"],
+    )
+    assert no_explain.rule_trace == []
+
+
+# ---------------------------------------------------------------------------
+# Q1 LOCKED — tie-break (highest tier wins)
+# ---------------------------------------------------------------------------
+
+
+def test_us0118_tie_break_code_wins():
+    """Story touching both docs/ and src/ (mixed tier) → CODE (highest
+    tier wins per Q1 LOCKED)."""
+    result = classify_work_kind(
+        story_prose="Feature + docs",
+        acceptance_criteria=["AC-1"],
+        touched_file_hints=["docs/foo.md", "package.json"],
+    )
+    assert result.work_kind is WorkKind.CODE

package/template/tests/us0119_autonomy_preset_test.py

@@ -0,0 +1,168 @@
+"""
+Contract tests for US-0119 — Autonomous-autonomy presets.
+
+10 test markers per DEC-0119 §9, covering AC-6, AC-7, AC-10, AC-12.
+"""
+import pytest
+import sys
+from pathlib import Path
+
+
+def test_us0119_preset_none_is_noop():
+    """AC-6: AUTONOMY_PRESET=none produces byte-identical pre-US-0119 behaviour (empty expansion)."""
+    sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+    from autonomy_preset_lib import expand_autonomy_preset
+
+    result = expand_autonomy_preset("none")
+    assert result == {}, "AUTONOMY_PRESET=none MUST produce empty expansion (byte-identical pre-US-0119)"
+
+
+def test_us0119_preset_balanced_expansion():
+    """AC-2: balanced preset expands into documented 8 flags per DEC-0119 §7."""
+    sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+    from autonomy_preset_lib import expand_autonomy_preset
+
+    result = expand_autonomy_preset("balanced")
+    assert len(result) == 8, f"balanced preset MUST expand to 8 flags, got {len(result)}"
+    expected_keys = {
+        "WORK_KIND_AUTO_ACCEPT",
+        "CROSS_MODEL_REWORK_EXHAUSTED_POLICY",
+        "CROSS_MODEL_SKIP_PHASES",
+        "RESUME_BRIEF_AUTO_REFRESH",
+        "RUNTIME_PROOF_KIND",
+        "GOAL_CONVERGENCE_INTERVAL",
+        "SOVEREIGN_DRAIN_AUTO_ACCEPT",
+        "AUTONOMY_STOP_POLICY",
+    }
+    assert set(result.keys()) == expected_keys, f"balanced preset keys mismatch: {set(result.keys())} != {expected_keys}"
+
+
+def test_us0119_preset_full_expansion():
+    """AC-2: full preset expands into documented 12 flags per DEC-0119 §7."""
+    sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+    from autonomy_preset_lib import expand_autonomy_preset
+
+    result = expand_autonomy_preset("full")
+    assert len(result) == 12, f"full preset MUST expand to 12 flags, got {len(result)}"
+    expected_keys = {
+        "INTAKE_AUTONOMY_MODE",
+        "INTAKE_MINIMAL_PACK",
+        "INTAKE_ASSUME_STACK_CONTEXT",
+        "WORK_KIND_AUTO_ACCEPT",
+        "CROSS_MODEL_REWORK_EXHAUSTED_POLICY",
+        "CROSS_MODEL_SKIP_PHASES",
+        "RESUME_BRIEF_AUTO_REFRESH",
+        "RUNTIME_PROOF_KIND",
+        "GOAL_CONVERGENCE_INTERVAL",
+        "SOVEREIGN_DRAIN_AUTO_ACCEPT",
+        "RELEASE_PUBLISH_AUTO_CONFIRM",
+        "AUTONOMY_STOP_POLICY",
+    }
+    assert set(result.keys()) == expected_keys, f"full preset keys mismatch: {set(result.keys())} != {expected_keys}"
+
+
+def test_us0119_explicit_flag_overrides_preset():
+    """AC-2: explicit per-flag > preset expansion (LOCKED precedence)."""
+    sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+    from autonomy_preset_lib import expand_autonomy_preset
+
+    result = expand_autonomy_preset("balanced", {"WORK_KIND_AUTO_ACCEPT": "0"})
+    assert result["WORK_KIND_AUTO_ACCEPT"] == "0", "explicit override MUST win over preset value"
+
+
+def test_us0119_preset_expansion_uses_known_keys_only():
+    """AC-12: expansion output contains only keys in pre-US-0119 scratchpad schema (compose guard)."""
+    sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+    from autonomy_preset_lib import expand_autonomy_preset, AUTONOMY_FLAGS
+
+    for preset in ["none", "balanced", "full"]:
+        result = expand_autonomy_preset(preset)
+        unknown_keys = set(result.keys()) - AUTONOMY_FLAGS
+        assert not unknown_keys, f"preset={preset} expansion contains unknown keys: {unknown_keys}"
+
+
+def test_us0119_matrix_validator_passes():
+    """AC-4: scripts/validate_autonomy_stop_matrix.py --self-test exits 0."""
+    import subprocess
+
+    validator_path = Path(__file__).parent.parent / "scripts" / "validate_autonomy_stop_matrix.py"
+    result = subprocess.run(
+        ["python", str(validator_path), "--self-test"],
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, f"validator --self-test MUST exit 0, got {result.returncode}\nstderr: {result.stderr}"
+
+
+def test_us0119_security_hard_gates_never_auto_repaired():
+    """AC-7: matrix security_hard rows all carry auto_repair_kind=n/a."""
+    sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+    from validate_autonomy_stop_matrix import parse_yaml_matrix, REPO_ROOT
+
+    yaml_path = REPO_ROOT / "scripts" / "data" / "autonomy_stop_matrix.yaml"
+    matrix = parse_yaml_matrix(yaml_path)
+
+    for entry in matrix.get("reason_codes", []):
+        if entry.get("stop_class") == "security_hard":
+            assert entry.get("auto_repair_kind") == "n/a", (
+                f"security_hard code {entry['code']} MUST have auto_repair_kind=n/a, "
+                f"got {entry.get('auto_repair_kind')}"
+            )
+
+
+def test_us0119_stop_policy_affects_repair_dispatch():
+    """AC-3: auto_repair_then_block vs auto_repair_then_skip dispatch correctly."""
+    # This test verifies the stop-policy dispatch logic is documented in scratchpad
+    # Actual dispatch happens at runtime based on AUTONOMY_STOP_POLICY value
+
+    scratchpad_path = Path(__file__).parent.parent / ".cursor" / "scratchpad.md"
+    content = scratchpad_path.read_text(encoding="utf-8")
+
+    assert "AUTONOMY_STOP_POLICY=" in content, "AUTONOMY_STOP_POLICY MUST be documented in scratchpad"
+    assert "block|" in content or "auto_repair_then_block|" in content, (
+        "AUTONOMY_STOP_POLICY MUST document block/auto_repair_then_block/auto_repair_then_skip enum"
+    )
+
+
+def test_us0119_repair_ledger_cap_escalates():
+    """AC-8: cap exhaustion -> AUTONOMY_REPAIR_CAP_EXHAUSTED terminal stop."""
+    # This test verifies the terminal stop code is in the matrix
+
+    sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+    from validate_autonomy_stop_matrix import parse_yaml_matrix, REPO_ROOT
+
+    yaml_path = REPO_ROOT / "scripts" / "data" / "autonomy_stop_matrix.yaml"
+    matrix = parse_yaml_matrix(yaml_path)
+
+    reason_codes = {entry["code"]: entry for entry in matrix.get("reason_codes", [])}
+    assert "AUTONOMY_REPAIR_CAP_EXHAUSTED" in reason_codes, (
+        "AUTONOMY_REPAIR_CAP_EXHAUSTED terminal stop code MUST be in matrix"
+    )
+
+    terminal_entry = reason_codes["AUTONOMY_REPAIR_CAP_EXHAUSTED"]
+    assert terminal_entry["stop_class"] == "autonomy_resolvable", (
+        "AUTONOMY_REPAIR_CAP_EXHAUSTED MUST be autonomy_resolvable (bounded cap)"
+    )
+    assert terminal_entry["auto_repair_kind"] == "n/a", (
+        "AUTONOMY_REPAIR_CAP_EXHAUSTED MUST have auto_repair_kind=n/a (terminal)"
+    )
+    assert terminal_entry["cap"] == 0, (
+        "AUTONOMY_REPAIR_CAP_EXHAUSTED MUST have cap=0 (terminal stop)"
+    )
+
+
+def test_us0119_matrix_no_orphan_codes():
+    """AC-4: no orphan reason codes outside YAML manifest."""
+    # This test is implicitly covered by test_us0119_matrix_validator_passes,
+    # which runs the validator's --self-test. If the validator passes, no orphan
+    # codes exist.
+
+    sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+    from validate_autonomy_stop_matrix import self_test
+
+    passed, violations = self_test()
+    assert passed, f"validator self_test MUST pass, got violations: {violations}"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])