feat: start an Execution from a scope spec (ADR-0008, iteration 9 step 1)
Some checks failed
validation / verify (push) Failing after 10s

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>
This commit is contained in:
2026-10-11 17:53:00 +01:00
parent a48468d477
commit afe78640f8
27 changed files with 2122 additions and 8 deletions

View File

@@ -14,6 +14,8 @@ One directory per iteration of this agent. Each holds the plan for that iteratio
| 6 | `iter-06-target-architecture-graph/` | complete: all four cases pass with real models, each run twice on 2026-10-08; thresholds set | The Target architecture as one explicit graph of Elements, Relationships and Checks, established before infrastructure code, with validation as a verdict per Check. |
| 7 | `iter-07-change-requests/` | complete (2026-10-09): the change case ran with real models and passed | A user restates a request to say how requirements changed; a new Execution starts from a Baseline Execution of the same Customer case and delivers the updated architecture with what changed. |
| 8 | `iter-08-terraform-modules/` | steps 1–5 built and run once each way on 2026-10-09, both at 100%; steps 6 and 7 wait on Azure and AWS provider bundles | Infrastructure code is plain resources by default. An Execution may opt into published Terraform modules: only from registry namespaces the provider bundle lists, at one exact version, with a lookup of what a module accepts and a Skill of four Google modules tested against the pinned provider. |
| 9 | `iter-09-scoping/` | step 1 built on 2026-10-11, not run with real models; steps 2–6 planned; ADR-0008 accepted | An engagement is scoped from a scope spec: a structured file, complete or partly filled, read against a catalogue in code, completed in conversation and approved before requirements begin. Covers workloads and platform foundations. |
| 10 | `iter-10-work-breakdown/` | planned; nothing built | A work breakdown structure as a Deliverable: work packages traced to Elements and Checks, activities in sequence, and a timeline on a relative day axis computed and drawn by code. |
Numbers record when an iteration was planned, not the order to build in. Build iteration 6 before the remaining steps of iteration 4 (10 to 14) and before iteration 5: it changes the Deliverables, Phases and validation format they build on. Its `MAP.md` lists the effect on each of their steps.

View File

@@ -0,0 +1,34 @@
# Plan Map
**Iteration:** 9, Scoping
**Intent:** Scope an engagement from a scope spec: a structured file that may arrive complete, partly filled or not at all, completed in conversation and approved by the customer before requirements begin. So that a design's quality no longer rests on what the agents had to assume.
**Status:** step 1 built on 2026-10-11, not run with real models; steps 2 to 6 planned
**This directory covers:** steps 1 to 6
## Sources of truth
- `docs/adr/0008-scoping-starts-from-a-scope-spec.md`: the decisions.
- `.scratch/scoping-and-work-breakdown/spec.md`: the design, including the draft spec, the owner's own example and how the two were combined.
- `skills/scoping/assets/catalogue.yaml`: every field a scope spec may hold.
## Status
| Step | What | Status |
|---|---|---|
| 1 | The catalogue, reading and validating a spec, the gap list, the two files beside the Intent, run options from the spec, the spec shown to every Specialist | built 2026-10-11 (`steps/step-1.md`); not run with real models |
| 2 | The conversation that fills gaps and writes answers into the completed copy; scoping as a Phase with its Deliverable and Approval; a spec drafted from a sentence | planned |
| 3 | Requirements traced to the customer's requirement ids and to spec fields, in `requirements.json`; readiness in the solution guide | planned |
| 4 | An edited spec as a Change request, compared field by field | planned |
| 5 | Evaluation cases as specs, replacing answers matched by pattern | planned; `case-08-landing-zone` is the first |
| 6 | The status `BASELINE_LOCKED` set when the Execution completes | planned |
## Dependency graph
- Step 1: no dependencies
- Step 2: depends on step 1
- Step 3: depends on step 1
- Step 4: depends on step 1, iteration 7
- Step 5: depends on step 1
- Step 6: depends on step 2
The work breakdown structure is iteration 10 and uses the spec's `delivery` section from step 1.

View File

@@ -0,0 +1,20 @@
# 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).

View File

@@ -0,0 +1,23 @@
# Plan Map
**Iteration:** 10, Work breakdown structure
**Intent:** Deliver a plan for building the Target architecture: work packages traced to its Elements and Checks, activities in sequence, and a timeline on a relative day axis that code computes and draws.
**Status:** planned; nothing built
**This directory covers:** steps 1 to 4
## Sources of truth
- `.scratch/scoping-and-work-breakdown/spec.md`, section "The work breakdown structure".
- `docs/adr/0005-the-target-architecture-is-an-explicit-graph.md`: the ids it traces to.
- Iteration 9 step 1: the scope spec's `delivery` section (team size, window, commercial model).
## Status
| Step | What | Status |
|---|---|---|
| 1 | The Deliverable, its Specialist and its data file; every Element in a work package, checked in code | planned |
| 2 | The schedule computed in code: start and finish day, critical path, team size as a limit | planned |
| 3 | The three views written by code: WBS dictionary, activity sequence list, timeline on a relative axis | planned |
| 4 | The delivery window checked; assumptions the plan depends on shown on the timeline; milestones | planned |
Decisions the owner accepted on 2026-10-11: after validation, in the packaging Phase; grouped by component; the technical build only.