Architecture / 04
The concepts behind the process.
Each concept has a job. Together they connect a request to evidence, controlled work, and an accountable result.
On this page
- Control outside the model
- Bounded decomposition
- Dependencies that mean something
- Evidence with provenance
- Grounding that can reject a claim
- Care with claims of absence
- Context assembled for the work
- Discovery is not inspection
- Freshness and scope
- Challenge before acceptance
- Structured actions and results
- Staging before commitment
- Verification with a named scope
- Explicit outcomes
- A final check with authority
- Limits on work
- Progress rather than repetition
- Models as replaceable contributors
- Human authority
- Pause, resume, and recovery
- Documents as working evidence
- Specifications that separate intent from fact
01 / Concept
Control outside the model
A model proposes the next useful step. The runtime validates structured operations and governs the workflow around them. We selected this separation because suggestions and authority are different responsibilities.
The benefit is a concrete boundary at which an invalid operation can be rejected. It does not make every valid request wise or every model judgment correct; it gives those judgments a controlled place to operate.
SpecKit 001 · AC-FR003-01
02 / Concept
Bounded decomposition
A large goal becomes smaller tasks with a defined purpose, dependencies, and limits. We selected this approach to make complex work inspectable without requiring one response to hold the entire investigation.
The benefit is clearer responsibility for each result. The limit is that decomposition can be wrong: a valid plan still needs to address the user’s actual question, and more tasks do not imply better coverage.
SpecKit 008 · AC-008-002-14 · SpecKit 009 · AC-009-008-01
03 / Concept
Dependencies that mean something
Some work is useful only after another result exists. Merlin represents those relationships in the plan rather than relying on the model to remember them.
We selected explicit dependencies so a downstream step cannot quietly treat an unfinished prerequisite as complete. This makes blocked work visible. It also means an incomplete prerequisite may legitimately prevent later work; truthful incompleteness is preferable to a fabricated dependency result.
SpecKit 009 · AC-009-005-01
04 / Concept
Evidence with provenance
Evidence is tied to the task that gathered it and the source it describes. We selected attribution because a record that exists somewhere in a session is not automatically proof that the relevant task inspected it.
The benefit is a traceable connection between work and findings. Provenance establishes where an observation came from; interpretation still has to be assessed, and source material itself can be incomplete or wrong.
SpecKit 005 · AC-005-001-01 · AC-005-001-03
05 / Concept
Grounding that can reject a claim
References are checked against recorded material. A citation beyond a known file’s length, or an identifier absent from the cited content, is not accepted just because it looks plausible.
We selected these checks because a polished citation can create false confidence. The benefit is an enforceable baseline for source fidelity. A valid location alone does not prove that a broader conclusion follows from it.
SpecKit 005 · AC-005-004-01 · AC-005-004-02 · AC-005-004-04
06 / Concept
Care with claims of absence
Saying that something does not exist is stronger than saying it was not found. Merlin can reject an absence claim when the stored source contradicts it.
We selected this constraint because negative claims can prematurely close an investigation. Its benefit is to catch a concrete contradiction. It is not a proof that every possible source was searched or that an unseen item is absent.
SpecKit 005 · AC-005-005-01
07 / Concept
Context assembled for the work
The current step receives a working context assembled from relevant state and evidence. We selected a dedicated context layer because a growing conversation is a poor substitute for deliberately organized working material.
The benefit is continuity with a clear purpose: give the step what it needs to act on. Selection still has limits. Material omitted from context must not be described as if the model reviewed it.
SpecKit 007 · AC-007-005-01 · AC-007-008-01 · AC-007-008-02
08 / Concept
Discovery is not inspection
Search and semantic retrieval help locate potentially useful material. Reading the authoritative source is a separate responsibility when a conclusion depends on that source.
We selected this distinction to prevent a short search result from silently standing in for a full document. The benefit is more defensible coverage. Retrieval quality still affects what is discovered, and no index guarantees that all relevant material will be found.
SpecKit 007 · AC-007-003-07
09 / Concept
Freshness and scope
Evidence has a context: the work that gathered it, the workspace it belongs to, and the version of the source it describes. Workspace-level reuse must account for source changes.
We selected explicit scope and invalidation because yesterday’s observation can become today’s confident error. The benefit is safer reuse without treating persistence as truth. Reuse depends on configuration and the source’s lifecycle; a remembered statement is not automatically revalidated evidence.
SpecKit 010 · AC-010-016-35 · AC-010-016-36
10 / Concept
Challenge before acceptance
Analysis v2 gives proposed findings a structured challenge. A rebuttal can survive, refute, or leave a claim inconclusive; verification separately records whether it is confirmed, rejected, or uncertain.
We selected challenge as a normal part of investigation because the first plausible explanation often attracts confirming evidence. The benefit is room for contrary evidence to change the result. Model-assisted challenge is fallible and is not a formal proof of correctness.
SpecKit 006 · AC-006-005-01 · AC-006-006-01
11 / Concept
Structured actions and results
Operations have a defined structure that the runtime can validate. We selected an explicit action interface to make tool use inspectable and reject malformed requests before treating them as work.
The benefit is a clearer boundary between reasoning, a requested action, and its result. Schema validity is only one layer: authorization, tool behavior, and verification remain separate concerns.
SpecKit 001 · AC-FR003-01
12 / Concept
Staging before commitment
Workspace changes enter a controlled staging lifecycle. Content verification is required before completion, and rollback is defined for active staged and failure states.
We selected staging because reasoning should not blur a proposed edit with a completed change. The benefit is a boundary at which required checks can fail without being reported as success. This is a workspace-change contract, not a blanket promise to reverse arbitrary external side effects.
SpecKit 003 · AC-003-002-01 · AC-003-003-01 · AC-003-005-01
13 / Concept
Verification with a named scope
A successful check supports the assertion it actually tested. Merlin distinguishes command evidence and typed verification receipts; a narrow receipt does not stand in for a whole-project build.
We selected scoped verification to prevent a small success from becoming a large claim. Its benefit is a more precise handoff. Tests and validators have blind spots, so passed checks must be described with their scope intact.
SpecKit 004 · AC-004-004-02
14 / Concept
Explicit outcomes
A task can be blocked, and a run can be incomplete. Completion reporting must preserve those outcomes instead of allowing a final summary to overwrite them.
We selected explicit outcomes because an honest partial result is useful only when its limits remain visible. The benefit is knowing what needs attention next. A terminal run state does not, on its own, mean that every requested outcome was achieved.
SpecKit 002 · AC-002-004-01 · AC-002-007-01
15 / Concept
A final check with authority
Before delivery, the proposed answer is compared with recorded work. A completion claim cannot ignore blocking outcomes, and a claim of mutation needs evidence of writes or proposed changes.
We selected this final boundary because even a disciplined investigation can end with an overconfident summary. The benefit is a check that can refuse the conclusion. Its coverage is defined by the implemented controls and available evidence, not by universal knowledge of the world.
SpecKit 004 · AC-004-004-01 · AC-004-004-03 · AC-004-004-04
16 / Concept
Limits on work
Planning, analysis, and execution operate within stage budgets. The runtime, rather than an indefinitely continuing conversation, owns their availability.
We selected explicit limits because time and compute are part of the task’s real constraints. The benefit is bounded work and a reason to surface unfinished scope. Exhausting a budget is not evidence that a problem has been solved.
SpecKit 009 · AC-009-008-01
17 / Concept
Progress rather than repetition
Repeated operations without progress can trigger guidance or bounded termination. We selected this behavior because an active agent can still be stuck.
The benefit is a process that distinguishes activity from useful movement. Progress detection is necessarily limited by what the runtime observes; it should not be read as a guarantee of optimal reasoning or a fixed completion time.
SpecKit 001 · AC-FR003-04
18 / Concept
Models as replaceable contributors
Model calls are accounted for within the staged runtime. We selected a configurable model layer so the process can use different capabilities without making a particular model the entire product.
The benefit is flexibility in deployment and evaluation. Model choice still changes quality, cost, and latency; a larger model is not proof of a better outcome. Any cloud use must follow the configured deployment boundary.
SpecKit 009 · AC-009-008-01 · AC-009-008-02
19 / Concept
Human authority
User intent and authorization constrain the work. A procedural recipe cannot independently grant permission to mutate a workspace; requests to explain or review remain distinct from requests to write.
We selected this separation because knowing how to perform an action is not authority to perform it. The benefit is a clearer relationship between assistance and control. Operators still need to choose appropriate permissions and review requirements for their deployment.
SpecKit 018 · AC-018-001-02 · AC-018-005-03
20 / Concept
Pause, resume, and recovery
A resumable session can continue or report why continuation is not available. User pause preserves a boundary around completed work instead of pretending the task finished.
We selected explicit lifecycle controls because useful work often lasts longer than one uninterrupted interaction. The benefit is continuity that can be inspected. Resume has preconditions; it is not a promise to reproduce a model’s earlier wording or to recover from every failure.
SpecKit 001 · AC-FR001-05 · AC-FR001-09 · AC-FR001-10
21 / Concept
Documents as working evidence
Documentation belongs in the same investigation as code when it governs behavior. Merlin’s indexing requirements include configured document formats even when a repository’s detected language would otherwise focus discovery on code.
We selected this because intended behavior often lives outside the implementation. The benefit is a broader evidence base. Extraction and retrieval still have limits, and discovering a document is not proof that every page was reviewed.
SpecKit 014 · AC-014-002-01
22 / Concept
Specifications that separate intent from fact
SpecKits describe required behavior, acceptance criteria, data, and work. The authoring process distinguishes existing code from the desired contract and checks relationships between artifacts.
We selected this structure to make a change reviewable before and after implementation. The benefit is a named requirement against which behavior can be judged. A generated specification is an artifact, not evidence that the feature it describes has been built.
SpecKit 018 · AC-018-002-04 · AC-018-003-01 · AC-018-004-01 · AC-018-004-04