The Artifact Chain

Why this matters

Nadia wants a newsletter. Omar types into the Quill chat: "Export customer emails for the newsletter" (CR-103). Quill reads the Shelf repository, writes scripts/export-emails.ts, runs it once to check the output, and opens a pull request with a tidy 4,212-row CSV attached. Tests pass. Omar merges before lunch.

A week later Priya opens the CSV. About half of those customers bought a gift card at a till and never ticked the newsletter box. Bramble Books has no consent to email them. Priya owns the customer-data policy, and nobody asked her. Nobody asked her because there was nothing to route to her: the request lived in a chat window, and chat windows do not have a "who needs to see this" field. This lesson gives the request a shape that does.

1. The chain in one picture

The artifact chain is the ordered set of files a change passes through on its way from an idea to production. An artifact is a file that is written down, committed, and can be pointed at later. Each link in the chain has one job and one person who accepts it.

Read the table top to bottom. Nothing in link 3 is written until link 2 is accepted. No code exists until link 3 is approved. The PR in link 6 cannot merge until links 4 and 5 have produced their evidence.

2. intent.md: the product owner accepts

intent.md is the first link. It states the business outcome in one paragraph, with no implementation detail. The product owner is the person who decides what the business wants. At Bramble Books that is Nadia. She accepts the intent by putting her name and the date on it.

Intent answers "what should be true for the business when this is done?" It never answers "how." If a sentence mentions a script, a table, or a file format, it belongs further down the chain.

Notice what that paragraph does. The phrase "who have agreed to receive it" is the whole reason the chat-window version went wrong. Nadia did not write it because she is a privacy expert. She wrote it because "send the newsletter to everyone" is not the business outcome she wanted. Writing the outcome down forces the question.

3. spec.md: concerns routed to policy owners

spec.md is the second link. It grows the intent into six parts: intent, constraints, acceptance criteria, verification, human gates, and evidence. L2 teaches each part in detail. This lesson cares about one thing the spec does that no chat message can: it routes concerns to policy owners.

A policy owner is the person accountable for a rule that the business must follow. Priya owns the rules about payments and customer data. "Routed to" means the constraints section of the spec names the policy owner, states the rule as the author understands it, and asks the owner to confirm or correct it before any code is generated.

Priya's two answers change the spec before Quill reads it. A till purchase is not consent. Consent older than two years has lapsed. Both become acceptance criteria, and both become tests in L3. The week-late discovery becomes a two-line comment on day two.

4. plan.md: the engineer approves before build

plan.md is the third link. It is what Quill proposes to do, written down before it does any of it. A plan holds four things: the steps in order, the files that will be touched, the commands that will be run, and the files that will not be touched. The engineer, Omar, reads it and approves it, or edits it, before the build starts.

Why approve a plan when you could review the code later? Because a bad plan produces a bad diff, and reading a bad diff costs far more than reading a bad plan. A plan is a page. A diff can be forty files. Omar can spot "this touches the payments module" in a plan in ten seconds. In a diff he might not spot it at all.

Omar's first edit stops a CSV of personal data from being committed by accident. His second edit is the one that matters most. The chat-window version of CR-103 ran the export against production "to check the output." The plan now says that will not happen, and in L4 a hook will make sure of it.

5. make test: output attached to the PR

make test is the fourth link. It is the one command that builds Shelf, runs the test suite, and runs the linter. Its result is an exit code: zero means everything passed, and any other number means something failed. Nobody signs this link. Instead, its output becomes an artifact by being attached to the pull request.

Why attach it? Because "the tests passed" is a claim, and a log is evidence. A log shows which command ran, on which commit, at what time, and what it printed. A claim shows that someone typed a sentence.

The four test names are Priya's two answers turned into checks. Anyone reading the PR can see that the consent rule was tested without opening a single source file. That is what "attached" buys you.

6. evals/*.json: pass rate gates the merge

The fifth link is the eval suite, a folder of JSON files under evals/. Each file is an eval case: a real task the team once gave Quill, paired with the outcome the team accepted. The suite runs Quill against every case and reports a pass rate, the share of cases where the checks passed.

The eval suite does not test Shelf. make test does that. The eval suite tests Quill's configuration: CLAUDE.md, the skills, and the hooks that shape how the agent behaves. If a change touches any of those, the suite runs and its pass rate must stay above a threshold for the PR to merge. L5 shows how to write cases and L6 shows how to run them in CI. Here you only need to know that this link exists and what it gates.

CR-103 did not change CLAUDE.md, so the eval check would normally be skipped. It appears here because Omar added a skill that tells Quill how to handle personal data, and a skill is configuration. Configuration changes can change the agent's behavior on every future task, which is why they are gated by a pass rate rather than by a glance.

7. The merged PR: the auditable change

The sixth link is the merged pull request. A pull request is a proposed change to the repository with a description, a diff, and a place for review. When it merges, it becomes the record of the change. An auditable change is one where a stranger can open a single page and answer three questions: what changed, what proves it was checked, and who accepted it.

The reviewer of record is the named person who approved the merge. It is one person, named in the PR, not "the team." Quill can open the PR. Quill cannot be the reviewer of record.

Every line in that description points at a file or a run that exists. Mr. Hale does not need Omar in the room. He reads the description, opens spec.md, sees Priya's signature, and moves on to the next change.

8. Boundaries and who may cross them

A stage boundary is the line between one link and the next. Promotion means moving work across a boundary: accepting the intent, confirming the constraints, approving the plan, merging the PR. The rule of the whole course is that the agent never promotes its own work. Quill produces. A person, or a pass rate a person set, promotes.

Here is what promotion means at each link and who may do it.

Summary

• The artifact chain has six links: intent.md, spec.md, plan.md, make test, evals/*.json, and the merged PR. Each holds what the previous one produced.
• The product owner accepts the intent; the spec routes concerns to the policy owner by naming her, stating the rule, and asking the question in the file.
• The engineer approves the plan before the build because a page of steps is cheaper to correct than forty files of diff, and the "will not touch" list is the part to read slowly.
• make test output and the eval pass rate are attached to the PR as evidence, because a log proves and a sentence only claims.
• The merged PR is the auditable change: code, evidence, and a named reviewer of record. The agent never promotes its own work across any boundary.