Files
gcp_solution_architecture_a…/.agents/plans/iter-09-scoping/steps/step-1.md
Jonathan Boniface afe78640f8
Some checks failed
validation / verify (push) Failing after 10s
feat: start an Execution from a scope spec (ADR-0008, iteration 9 step 1)
A scope spec is a YAML file of what the customer wants and the facts a design
depends on, complete or partly filled. It sits beside the Intent, which stays
in the customer's words.

- skills/scoping holds a provider-neutral catalogue of 63 fields; the Cloud
  provider's bundle supplies the values it allows for the fields left to it.
- app/scope.py reads a spec against the catalogue with no model: it refuses an
  unknown field or a value of the wrong type, and yields what is stated, what
  is left to the agent, what is unknown and how pressing each gap is. A field
  may say ask, decide or not_applicable.
- ExecutionEngine.start(scope=...), /generate, A2A metadata and evaluation
  cases accept one. Its statement is the request, its engagement reference
  names the Customer case, and its run options apply. A pre-approved start is
  refused when an essential field is not settled.
- The spec as supplied is kept unaltered beside a completed copy with
  assumptions, gaps, provenance, readiness and a status.
- Every Specialist is shown the spec and given the Skill: a stated choice
  binds, exclusions are out of scope.
- Covers workloads and platform foundations; case-08-landing-zone starts from
  a benchmark spec.

Plans for scoping (iteration 9) and the work breakdown structure (iteration
10, nothing built), and the design spec they come from. Not run with real
models.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 17:53:00 +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:

  • 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).