Files
gcp_solution_architecture_a…/.agents/plans/iter-09-scoping/steps/step-1.md
Jonathan Boniface 545097530b
Some checks failed
validation / verify (push) Failing after 10s
feat: scoping is the first Phase, completed in conversation (iteration 9 step 2)
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>
2026-10-11 18:17:32 +01:00

3.1 KiB

Step 1 — Implementation Detail

Built on 2026-10-11. Not run with real models.

  1. The catalogue is skills/scoping/assets/catalogue.yaml: 63 fields as dotted paths, each with a type, a tier (which may differ by kind of engagement), the question to ask and guidance for a default. It names no Cloud provider. providers/gcp.yaml adds, under scope.values, what Google Cloud allows for the four fields left to a provider: the provider itself, encryption type, network topology and the kind of hybrid connection.
  2. Reading a spec is read_scope in app/scope.py, with no model. It refuses, naming every problem: YAML that does not parse, a field the catalogue does not have, a value of the wrong type, and an engagement reference and a customer case that disagree. A whole section may be marked ask, decide or not_applicable at once.
  3. What it yields: the stated values; the gaps, most pressing first, each with its question and a severity (HIGH essential, MEDIUM important, LOW optional); the assumptions, one per decide, with the default to take and what a wrong one would change; a count of each; and a status.
  4. Starting from a spec: ExecutionEngine.start(scope=...), scope in the /generate body and in A2A metadata, and on an evaluation case. The spec's statement is the request when none is given, its engagement reference names the Customer case, and its run section applies where the caller gave nothing. A pre-approved start is refused when an essential field is not settled.
  5. The two files are written beside the Intent: NNN.scope.yaml, the spec as supplied, byte for byte; and NNN.scope.completed.yaml, every field of the catalogue with the agent's sections (inferred_assumptions, discovery_gaps, provenance, readiness) and metadata.status. history.json names both. A completed copy can be supplied again as a spec; the agent's sections are replaced.
  6. Every Specialist is shown the spec as scope in its context (what is stated, what is theirs to decide, what is unknown) and is given the scoping Skill. The protocol says a stated choice binds, an exclusion is out of scope, and the customer's requirement ids are to be named. The requirements analyst is told to derive from it and ask only for what it leaves unknown.
  7. For a person: python -m app.scope check <file> says what a spec settles and what it lacks; python -m app.scope template <kind> prints one to fill in.
  8. A benchmark spec: eval/datasets/specs/landing-zone.yaml, a fictional regulated payment platform, and case-08-landing-zone which starts from it.

Interim, until step 2 (now built; see step-2.md):

  • Gaps are asked by the requirements analyst, who is handed them, not by a scoping Phase. Answers are not written back into the completed copy.
  • Status is set once, at the start: DRAFT with gaps to ask, UNDER_REVIEW when complete and someone is present, APPROVED when pre-approved. BASELINE_LOCKED is not set.
  • A caller's pre_approved wins over the spec's when both are given. /generate is always pre-approved.

Tests: tests/test_scope.py (18), tests/execution/test_scope_spec.py (8).