Plot: layered specifications and exact-target approvals
- My contribution
- Design and implementation.
- Scope
- Specification inheritance, exact-target approvals and prerequisite gates.
- Evidence
- Implementation inspected at 4e12b21; reconstructed examples are labelled.
Page by Julian Ramirez ·
A specification can become impressively detailed before anyone agrees on the problem it is meant to solve. By the time a reviewer sees the mismatch, the work has already spread into technical choices, tests and feature assumptions.
Plot addresses that drift by organizing intent into layers and putting approval boundaries between them. The question is no longer just whether a document looks complete. It is whether the next layer is allowed to proceed from the intent already agreed above it.
I find that boundary more useful than an approval attached to the conversation as a whole. The approval needs a target a future reader can identify.
My contribution and design scope
I built Plot around layered specifications and target-specific approval gates. The goal of the representation is to make the parent contract visible before more detailed work proceeds. This case distinguishes the domain model from the narrower scaffold actually exposed to users.
Let detail grow from a named parent
Plot distinguishes a concept specification, an umbrella layer and feature specifications. The concept layer contains one concept.spec; the umbrella and feature layers contain functional, technical and test specifications.
Sources & implementation notes
These layers have different jobs. The concept provides an anchor for the overall intent. The umbrella describes broader contracts. A feature adds detail within those contracts instead of quietly inventing its own version of the system.
XML extends relationships express that inheritance. Umbrella specifications refer to the concept, while feature specifications refer to the matching umbrella document. The snippets below show the relationship, not complete valid specification files.
<spec extends="concept.spec">↑ umbrella inherits concept
<spec extends="../../functional.spec">↑ feature inherits matching umbrella
Sources & implementation notes
The exact extends values come from expectedExtendsValue. These snippets illustrate the relationships; they are not complete valid documents.
Make an approval say exactly what it approves
“Approved” can be ambiguous after several documents or revisions have appeared in a conversation. Plot’s gate compares the supplied phrase with a target-specific phrase: approve followed by the normalized path.
For the example concept file, that means approve docs/concept.spec. Try the two inputs below. The difference is not stylistic; it determines whether the gate recognizes the approval.
approvedmismatch Expected: approve docs/concept.spec
approve docs/concept.specapproved
Sources & implementation notes
- src/domain/gates.ts · 4e12b21
- src/domain/spec-state.ts · 4e12b21
- src/app/use-cases.ts · 4e12b21
- README.md · 4e12b21
The README quickstart supplies “approved”; the implementation compares against “approve ” plus the normalized target path, after trimming the supplied phrase.
The README quickstart supplies approved, which conflicts with the inspected implementation. The graphic follows the code. An exact phrase identifies a target path; it should not be mistaken for a cryptographic approval of a particular document revision.
Require the parent approval before drafting the child
The exposed scaffold checks prerequisites before moving into more detailed work. Umbrella drafting requires concept approval. Feature drafting requires the concept and the umbrella’s functional, technical and test specifications to be approved.
Sources & implementation notes
This puts the cost of resolving intent earlier in the workflow, before an agent has produced detail that depends on it. It still leaves people responsible for the quality of the approval: a correctly named target can contain a weak or incomplete decision.
For a broader discussion of where human checkpoints belong, see the Intervention Penalty. Plot illustrates a boundary mechanism, not evidence that every approval improves outcomes.
Distinguish the domain model from the exposed scaffold
The domain validator can identify structural problems such as an invalid extends relationship and attach a diagnostic to the affected specification. That is a useful representation because the problem has a location and a classification.
docs/functional.spec
↳ invalid_extends
ERR-PLOT-05 Public validate command: enumerates spec files Sources & implementation notes
The domain validateSpecFile implementation classifies structural failures. At this revision the exposed validate use-case is scaffolded and only enumerates spec files; it does not expose the full domain validation shown here.
The public validate use-case at this revision is more limited: it enumerates specification files rather than exposing the full domain validation shown above. Recovery is similarly constrained to gate inspection and reset in the exposed scaffold. Richer domain planning should not be read as a complete repair system available through the command surface.
Those boundaries matter when evaluating the project. Follow the path from the interface you intend to use to the behavior it actually invokes.
Approve the boundary while the work is still cheap
The useful habit is to ask whether the next layer has a legitimate parent before adding more detail. Plot makes that question concrete with paths, relationships and gates.
Logbook’s durable task records address a complementary problem: preserving the state and context that the next session needs. Together, these ideas show why intent and execution both need representations that outlive a chat message.