Add control loop, gating primitives, and transport interface (A4/B1)

Step-2 PR A: the approval loop end to end with a stub agent, no LLM
and no network.

- transport.py: Transport interface per A1 (send_message,
  send_approval_request, ask_question, on_message) with an
  InMemoryTransport; no platform SDK outside an implementation
- gates.py: PlanRevision with monotonic rev-N tags; Gate.evaluate
  enforces revision binding (stale tags refused with a notice),
  operator allowlisting, and approve-word-only semantics; any other
  reply is rejection feedback. Channel seam ready for Gitea/Vikunja
  approval sources
- control.py: B1 state machine subset with structural gating — the
  agent's only actions are SubmitPlan (ends its turn) and AskHuman;
  no proceed tool exists. Gate state, revision counters, task_id,
  and pending questions checkpoint through StateStore, and boot
  resumes an open gate or gates to AWAIT_INPUT, never blind-resumes
- gate.open/approve/reject A9 events complete the log taxonomy
- CLAUDE.md: record the plan-first working convention
- Tests: 15 unit (gates + orchestrator flows), 2 integration
  (mid-gate restart with revisions intact; unresolved intents gate
  the whole boot)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

nisse-dev/tests/test_control.py

@@ -0,0 +1,155 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+from nisse_dev.control import (
+    AWAIT_ARCH_SIGNOFF,
+    AWAIT_INPUT,
+    AWAIT_MILESTONE_SIGNOFF,
+    EXECUTING,
+    IDLE,
+    AskHuman,
+    Orchestrator,
+    StubAgent,
+    SubmitPlan,
+)
+from nisse_dev.oplog import OpLog
+from nisse_dev.state import StateStore
+from nisse_dev.transport import InMemoryTransport
+
+
+class Harness:
+    def __init__(self, tmp_path: Path, agent: object | None = None) -> None:
+        self.stream = io.StringIO()
+        self.store = StateStore(
+            tmp_path / "state.db", oplog=OpLog("nisse-dev", self.stream)
+        )
+        self.transport = InMemoryTransport()
+        self.orch = Orchestrator(
+            self.store, self.transport, agent or StubAgent(), operators={"don"}
+        )
+        self.orch.start()
+
+    @property
+    def state(self) -> str:
+        state = self.store.get_state()
+        assert state is not None
+        return state.state
+
+    def events(self, kind: str) -> list[dict]:
+        return [
+            e
+            for e in map(json.loads, self.stream.getvalue().splitlines())
+            if e["event"] == kind
+        ]
+
+    def outbound_texts(self) -> list[str]:
+        return [m.text for m in self.transport.outbound]
+
+
+@pytest.fixture
+def h(tmp_path: Path) -> Harness:
+    return Harness(tmp_path)
+
+
+def test_boots_idle_and_greets(h: Harness) -> None:
+    assert h.state == IDLE
+    assert "ready" in h.outbound_texts()[0]
+
+
+def test_use_project_submits_arch_plan_and_opens_gate(h: Harness) -> None:
+    h.transport.receive("don", "use demo")
+    assert h.state == AWAIT_ARCH_SIGNOFF
+    request = h.transport.outbound[-1]
+    assert request.kind == "approval_request"
+    assert "rev-1" in request.text
+    [opened] = h.events("gate.open")
+    assert opened["gate"] == "arch"
+    assert opened["rev"] == "rev-1"
+    assert opened["task_id"] is not None
+
+
+def test_full_happy_path_to_executing(h: Harness) -> None:
+    h.transport.receive("don", "use demo")
+    h.transport.receive("don", "approve")
+    assert h.state == AWAIT_MILESTONE_SIGNOFF
+    h.transport.receive("don", "approve")
+    assert h.state == AWAIT_MILESTONE_SIGNOFF  # approved, awaiting start
+    h.transport.receive("don", "start milestone 1")
+    assert h.state == EXECUTING
+    approvals = h.events("gate.approve")
+    assert [e["gate"] for e in approvals] == ["arch", "milestone-1"]
+
+
+def test_reject_replans_with_feedback_and_bumps_revision(h: Harness) -> None:
+    h.transport.receive("don", "use demo")
+    h.transport.receive("don", "too vague, add tests")
+    assert h.state == AWAIT_ARCH_SIGNOFF
+    request = h.transport.outbound[-1]
+    assert "rev-2" in request.text
+    assert "too vague, add tests" in request.text
+    [rejected] = h.events("gate.reject")
+    assert rejected["rev"] == "rev-1"
+
+
+def test_stale_approval_is_refused_then_current_works(h: Harness) -> None:
+    h.transport.receive("don", "use demo")
+    h.transport.receive("don", "needs work")  # now at rev-2
+    h.transport.receive("don", "approve rev-1")
+    assert h.state == AWAIT_ARCH_SIGNOFF
+    assert "not applied" in h.outbound_texts()[-1]
+    assert h.events("gate.approve") == []
+    h.transport.receive("don", "approve rev-2")
+    assert h.state == AWAIT_MILESTONE_SIGNOFF
+
+
+def test_non_operator_messages_are_ignored(h: Harness) -> None:
+    h.transport.receive("don", "use demo")
+    before = len(h.transport.outbound)
+    h.transport.receive("mallory", "approve")
+    assert h.state == AWAIT_ARCH_SIGNOFF
+    assert len(h.transport.outbound) == before
+
+
+def test_start_milestone_requires_approval_first(h: Harness) -> None:
+    h.transport.receive("don", "use demo")
+    h.transport.receive("don", "approve")
+    h.transport.receive("don", "start milestone 1")
+    assert h.state == AWAIT_MILESTONE_SIGNOFF  # it was rejection feedback
+    h.transport.receive("don", "approve rev-2")
+    h.transport.receive("don", "start milestone 1")
+    assert h.state == EXECUTING
+
+
+def test_status_reports_state_and_gate(h: Harness) -> None:
+    h.transport.receive("don", "use demo")
+    h.transport.receive("don", "status")
+    status = h.outbound_texts()[-1]
+    assert "AWAIT_ARCH_SIGNOFF" in status
+    assert "demo" in status
+    assert "rev-1" in status
+
+
+class QuestionThenPlan:
+    def plan(
+        self,
+        gate: str,
+        project: str,
+        feedback: str | None = None,
+        answer: str | None = None,
+    ) -> SubmitPlan | AskHuman:
+        if answer is None:
+            return AskHuman("monorepo or polyrepo?")
+        return SubmitPlan(f"[stub] {gate} plan using {answer}")
+
+
+def test_ask_human_pauses_and_answer_resumes(tmp_path: Path) -> None:
+    h = Harness(tmp_path, agent=QuestionThenPlan())
+    h.transport.receive("don", "use demo")
+    assert h.state == AWAIT_INPUT
+    assert h.transport.outbound[-1].kind == "question"
+    h.transport.receive("don", "monorepo")
+    assert h.state == AWAIT_ARCH_SIGNOFF
+    assert "monorepo" in h.transport.outbound[-1].text