feat: scoping is the first Phase, completed in conversation (iteration 9 step 2)
Some checks failed
validation / verify (push) Failing after 10s

Every Execution now begins by agreeing the scope, before requirements.

- A new Phase and Deliverable, produced by a scope analyst with two tools:
  scope_read shows what is settled and what is not; scope_set records fields
  with where each value came from (the request, the customer's answer, or an
  assumption with its reason). Code checks each value against the catalogue.
- With someone present the analyst asks for what is missing; with nobody
  present it assumes it, visibly. With no spec it drafts one from the request.
  A value the customer stated in the file is changed only by their own answer.
- A submission cannot leave an essential field unknown. Code writes the
  completed spec, the data every later Specialist reads, and the information
  register, from what was recorded.
- The spec's status follows the Execution: under review, approved, then
  locked as a Baseline. A Change request starts from the delivered scope.
- The requirements analyst derives from the agreed scope and no longer asks
  for what it settles.

About 80 tests assumed requirements came first; tests/scoped.py runs scoping
ahead of a test's own script, and tests about order and counts are updated.
Not run with real models.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-11 18:17:32 +01:00
parent afe78640f8
commit 545097530b
38 changed files with 1054 additions and 123 deletions

View File

@@ -25,6 +25,14 @@ def approve(ledger: Ledger, phase: P) -> None:
ledger.approve(phase, actor="user")
def scoped(**options) -> Ledger:
"""A Ledger whose scope is agreed: where requirements discovery begins."""
ledger = Ledger(**options)
produce(ledger, K.SCOPE)
approve(ledger, P.SCOPING)
return ledger
def through_phase_one(ledger: Ledger) -> None:
produce(ledger, K.REQUIREMENTS, K.TECHNICAL_DECOMPOSITION)
approve(ledger, P.REQUIREMENTS_DISCOVERY)
@@ -49,22 +57,29 @@ def through_phase_three(ledger: Ledger) -> None:
# --- ready work and the two acceptance thresholds -------------------------------
def test_new_execution_has_only_requirements_ready():
def test_a_new_execution_has_only_the_scope_ready():
ledger = Ledger()
assert ledger.ready_work() == (K.REQUIREMENTS,)
assert ledger.ready_work() == (K.SCOPE,)
assert all(ledger.phase_status(p) is PhaseStatus.OPEN for p in P)
def test_once_the_scope_is_approved_requirements_are_ready():
ledger = scoped()
assert ledger.ready_work() == (K.REQUIREMENTS,)
assert ledger.phase_status(P.SCOPING) is PhaseStatus.APPROVED
def test_same_phase_dependency_is_met_once_submitted():
ledger = Ledger()
ledger = scoped()
produce(ledger, K.REQUIREMENTS)
assert ledger.ready_work() == (K.TECHNICAL_DECOMPOSITION,)
def test_cross_phase_dependency_needs_the_earlier_phase_approved():
ledger = Ledger()
ledger = scoped()
produce(ledger, K.REQUIREMENTS, K.TECHNICAL_DECOMPOSITION)
assert K.PRODUCT_SELECTION not in ledger.ready_work()
@@ -75,7 +90,7 @@ def test_cross_phase_dependency_needs_the_earlier_phase_approved():
def test_independent_work_becomes_ready_together():
ledger = Ledger()
ledger = scoped()
through_phase_one(ledger)
produce(
ledger, K.PRODUCT_SELECTION, K.DESIGN_RECOMMENDATIONS, K.TARGET_ARCHITECTURE
@@ -93,7 +108,7 @@ def test_independent_work_becomes_ready_together():
def test_ready_phases_lists_open_phases_with_every_deliverable_submitted():
ledger = Ledger()
ledger = scoped()
produce(ledger, K.REQUIREMENTS)
assert ledger.phases_ready_for_approval() == ()
@@ -106,7 +121,7 @@ def test_ready_phases_lists_open_phases_with_every_deliverable_submitted():
def test_start_refuses_work_that_is_not_ready_and_changes_nothing():
ledger = Ledger()
ledger = scoped()
with pytest.raises(LedgerRefusal, match="technical_decomposition"):
ledger.start([K.REQUIREMENTS, K.TECHNICAL_DECOMPOSITION], actor="orchestrator")
@@ -115,7 +130,7 @@ def test_start_refuses_work_that_is_not_ready_and_changes_nothing():
def test_start_moves_ready_work_in_progress_and_returns_attempts():
ledger = Ledger()
ledger = scoped()
attempts = ledger.start([K.REQUIREMENTS], actor="orchestrator")
@@ -125,7 +140,7 @@ def test_start_moves_ready_work_in_progress_and_returns_attempts():
def test_submit_requires_the_current_attempt():
ledger = Ledger()
ledger = scoped()
attempt = ledger.start([K.REQUIREMENTS], actor="orchestrator")[K.REQUIREMENTS]
with pytest.raises(LedgerRefusal, match="attempt"):
@@ -136,7 +151,7 @@ def test_submit_requires_the_current_attempt():
def test_late_submission_from_a_superseded_attempt_is_refused_after_restart():
ledger = Ledger()
ledger = scoped()
first = ledger.start([K.REQUIREMENTS], actor="orchestrator")[K.REQUIREMENTS]
ledger.release(K.REQUIREMENTS, first, reason="needs input")
second = ledger.start([K.REQUIREMENTS], actor="orchestrator")[K.REQUIREMENTS]
@@ -149,14 +164,14 @@ def test_late_submission_from_a_superseded_attempt_is_refused_after_restart():
def test_submit_refuses_work_not_in_progress():
ledger = Ledger()
ledger = scoped()
with pytest.raises(LedgerRefusal, match="in_progress"):
ledger.submit(K.REQUIREMENTS, 1, actor="requirements-analyst")
def test_release_returns_work_to_pending_without_a_revision():
ledger = Ledger()
ledger = scoped()
attempt = ledger.start([K.REQUIREMENTS], actor="orchestrator")[K.REQUIREMENTS]
ledger.release(K.REQUIREMENTS, attempt, reason="needs input")
@@ -172,7 +187,7 @@ def test_release_returns_work_to_pending_without_a_revision():
def test_request_approval_refuses_until_every_deliverable_is_submitted():
ledger = Ledger()
ledger = scoped()
produce(ledger, K.REQUIREMENTS)
with pytest.raises(LedgerRefusal, match="technical_decomposition"):
@@ -182,7 +197,7 @@ def test_request_approval_refuses_until_every_deliverable_is_submitted():
def test_approval_moves_through_awaiting_to_approved_by_the_user():
ledger = Ledger()
ledger = scoped()
produce(ledger, K.REQUIREMENTS, K.TECHNICAL_DECOMPOSITION)
ledger.request_approval(P.REQUIREMENTS_DISCOVERY, actor="orchestrator")
@@ -198,14 +213,14 @@ def test_approval_moves_through_awaiting_to_approved_by_the_user():
def test_approve_refuses_a_phase_not_awaiting_approval():
ledger = Ledger()
ledger = scoped()
with pytest.raises(LedgerRefusal, match="awaiting_approval"):
ledger.approve(P.REQUIREMENTS_DISCOVERY, actor="user")
def test_pre_approved_ledger_grants_approval_immediately():
ledger = Ledger(pre_approved=True)
ledger = scoped(pre_approved=True)
produce(ledger, K.REQUIREMENTS, K.TECHNICAL_DECOMPOSITION)
ledger.request_approval(P.REQUIREMENTS_DISCOVERY, actor="orchestrator")
@@ -216,7 +231,7 @@ def test_pre_approved_ledger_grants_approval_immediately():
def test_request_changes_reopens_the_phase_for_further_work():
ledger = Ledger()
ledger = scoped()
produce(ledger, K.REQUIREMENTS, K.TECHNICAL_DECOMPOSITION)
ledger.request_approval(P.REQUIREMENTS_DISCOVERY, actor="orchestrator")
@@ -228,7 +243,7 @@ def test_request_changes_reopens_the_phase_for_further_work():
def test_finish_is_allowed_only_once_packaging_is_approved():
ledger = Ledger()
ledger = scoped()
through_phase_three(ledger)
assert not ledger.can_finish()
@@ -242,7 +257,7 @@ def test_finish_is_allowed_only_once_packaging_is_approved():
def test_reopen_cascades_to_dependents_and_withdraws_affected_approvals():
ledger = Ledger()
ledger = scoped()
through_phase_three(ledger)
result = ledger.reopen(
@@ -274,7 +289,7 @@ def test_reopen_cascades_to_dependents_and_withdraws_affected_approvals():
def test_reopen_invalidates_attempts_of_dependents_already_in_progress():
ledger = Ledger()
ledger = scoped()
through_phase_one(ledger)
produce(ledger, K.PRODUCT_SELECTION)
attempt = ledger.start([K.DESIGN_RECOMMENDATIONS], actor="orchestrator")[
@@ -289,14 +304,14 @@ def test_reopen_invalidates_attempts_of_dependents_already_in_progress():
def test_reopen_refuses_deliverables_that_were_never_submitted():
ledger = Ledger()
ledger = scoped()
with pytest.raises(LedgerRefusal, match="submitted"):
ledger.reopen(K.REQUIREMENTS, "why", actor="orchestrator")
def test_reopen_escalates_at_the_revision_cap_without_changing_state():
ledger = Ledger(max_revisions=2)
ledger = scoped(max_revisions=2)
produce(ledger, K.REQUIREMENTS)
for _ in range(2):
ledger.reopen(K.REQUIREMENTS, "again", actor="orchestrator")
@@ -313,7 +328,7 @@ def test_reopen_escalates_at_the_revision_cap_without_changing_state():
def test_user_can_override_the_revision_cap():
ledger = Ledger(max_revisions=1)
ledger = scoped(max_revisions=1)
produce(ledger, K.REQUIREMENTS)
ledger.reopen(K.REQUIREMENTS, "first", actor="orchestrator")
produce(ledger, K.REQUIREMENTS)
@@ -327,7 +342,7 @@ def test_user_can_override_the_revision_cap():
def test_default_revision_cap_is_three():
assert Ledger().max_revisions == 3
assert scoped().max_revisions == 3
# --- records and persistence -------------------------------------------------------
@@ -335,16 +350,16 @@ def test_default_revision_cap_is_three():
def test_transitions_are_recorded_as_ordered_events():
ledger = Ledger()
produce(ledger, K.REQUIREMENTS)
produce(ledger, K.SCOPE)
assert [(e.sequence, e.type, e.subject) for e in ledger.events] == [
(1, "started", "requirements"),
(2, "submitted", "requirements"),
(1, "started", "scope"),
(2, "submitted", "scope"),
]
def test_round_trips_through_plain_data():
ledger = Ledger(max_revisions=5)
ledger = scoped(max_revisions=5)
through_phase_one(ledger)
produce(ledger, K.PRODUCT_SELECTION)
ledger.reopen(K.PRODUCT_SELECTION, "cost", actor="user")
@@ -358,7 +373,7 @@ def test_round_trips_through_plain_data():
def test_revising_the_target_architecture_returns_the_code_to_draft():
ledger = Ledger()
ledger = scoped()
through_phase_three(ledger)
result = ledger.reopen(