jonnifyagile agents
jonnify / Agile Agent Workflow / A4 · Spec / A4.6 / A4.6.1 · The chain

A4.6 · Traceability · dive 1

The chain

Every artifact carries a stable id, and every id is reachable from intent to proof. The chain is the spine of “correct by definition.”

A deliverable is realized by a story; the story is accepted by a Given/When/Then and encodes an invariant; the deliverable is also built by an agent story governed by a requirement, proven in turn. Step each link on the right over the Portal's real F6.1 ids — the path is read from the text, never inferred.

Step each link · F6.1 intent to proof

F6.1-D4 deliverable · controller F6.1-US2 user story Given/When/Then acceptance criteria F6.1-INV1 invariant (master) F6.1-AS# agent story F6.1-R# requirement invariant or acceptance test the proof the chain ends in six edges, all read from the text · intent on the left, proof at the foot
realized · F6.1-D4 (the course controller) is realized by F6.1-US2 (see a user's courses) — every deliverable maps to at least one story, the chain's first edge.

The chain, link by link

Traceability means each artifact carries a stable id so the path from intent to proof is explicit. The chain runs straight down: a deliverable is realized by a user story; the story is accepted by its Given/When/Then and encodes an invariant; the deliverable is also built by an agent story, which is governed by a requirement, proven by an invariant or an acceptance test.

None of these links is inferred. Each is named in the text: the stories file's Coverage line records which stories realize each deliverable, each story's INVEST line names the invariant it encodes, and each requirement carries its [US: …] tag. That is what lets a reader — or a Claude Author — walk the rung end to end and confirm nothing is left unpinned.

# specs.approach.md — the traceability chain (verbatim).
Deliverable (fN.M.md  · FN.M-D#)
   └─ realized by → User story (fN.M.stories.md · FN.M-US#)
        ├─ accepted by → Acceptance criteria (Given/When/Then on the story)
        └─ encodes     → Invariant (fN.M.md · FN.M-INV#)
   └─ built by   → Agent story (fN.M.llms.md · FN.M-AS#)
        └─ governed by → Requirement (fN.M.llms.md · FN.M-R#)
             └─ proven by → Invariant (FN.M-INV#)  or  an acceptance test
deliverable
A concrete artifact named in the spec (f6.1.md) with an id FN.M-D# — e.g. F6.1-D4, the course controller.
realized by
The user story that delivers the value — recorded in the stories file's Coverage line, so every deliverable maps to at least one.
encodes
The invariant a story exercises, named on its INVEST line (encodes FN.M-INV#) — the path that makes every invariant reachable.
governed by
The requirement an agent story is built under, tagged [US: FN.M-US#] and proven by an invariant or an acceptance test.

Resolve an id from the text

Because every link is named, an id resolves without judgement. Pick a deliverable and the Coverage line gives the stories that realize it; pick a story and its INVEST line gives the invariant it encodes. The block below holds the three real F6.1 lines verbatim. Select an id and the readout names its kind, where it lives, and what it links to — read straight from the file.

Pick an F6.1 id · resolve its links

# f6.1.md / f6.1.stories.md — the three lines this id resolution reads (verbatim).
# Deliverable   F6.1-D4 — PortalWeb.CourseController.index/2: calls only Portal.courses_of/1
# Coverage      D4→US2,US3,US5
# Story         F6.1-US2 — "As a visitor, I want to open a course page…"  encodes F6.1-INV1
# Invariant     F6.1-INV1 (master) — PortalWeb calls only the Portal facade
F6.1-D4 · a Deliverable in f6.1.md (the course controller). The Coverage line resolves it: realized by US2, US3, US5. Read from the text — no judgement needed.

An id resolves from the file, not from opinion: the Coverage line and the INVEST line name every link, so the chain is walkable by reading.

The chain on the Portal

On the Portal — the learning platform this course builds — the worked rung is F6.1, the web chapter's bootstrap, drawn from . Take F6.1-D4, the course controller. Its story is F6.1-US2, the F6.1 draft “see a user's courses”; its draft acceptance is the Given/When/Then “given a known user id, when the page renders, then it shows that user's courses”; the invariant it encodes is F6.1-INV1, the master rule that the web layer calls only the Portal facade. The deliverable is also built by an agent story governed by a requirement tagged [US: F6.1-US2], proven by F6.1-INV1 or its acceptance test.

That F6.1 draft named a /courses/:user_id page; reconciled the surface to the protected /my/courses — a learner's own enrollments, no :user_id in the URL. The facade function it calls, Portal.courses_of/1, is unchanged across both rungs.

One deliverable, walked from intent to proof, every link named in the F6.1 triad. The framework that implements this rung is taught in F6 — the Portal on the web; here the concern is only the chain of ids, not the code.

# Walk F6.1-D4 from intent to proof — every link read from the triad.
F6.1-D4   # deliverable: PortalWeb.CourseController.index/2 (f6.1.md)
  → realized by  F6.1-US2          # "see a user's courses"  (Coverage: D4→US2,US3,US5)
      → accepted by  Given/When/Then  # known user id → renders that user's courses
      → encodes      F6.1-INV1        # master: web calls only the Portal facade (INVEST line)
  → built by     agent story       # F6.1-AS# [implements F6.1-US2]  (f6.1.llms.md)
      → governed by  F6.1-R#          # requirement [US: F6.1-US2]
          → proven by  F6.1-INV1 / acceptance test
the principle

Every artifact carries a stable id, so the path from intent to proof is explicit and walkable from the text — not inferred and not asserted.

on the Portal

F6.1's ids form one walkable chain over the real triad: D4 → US2 → its Given/When/Then → INV1, and the agent story → requirement → proof.

A chain of stable ids makes a rung readable end to end: pick any deliverable and walk it forward to the check and the invariant that prove it, without guessing.

Recap — intent to proof, by id

The chain links every artifact id from intent to proof: deliverable realized by a story, story accepted by a check and encoding an invariant, deliverable built by an agent story governed by a requirement proven in turn. Each link is named in the text — the Coverage line, the INVEST line, the [US: …] tag — so the rung is walkable by reading. With the chain in hand, the next dive draws the rule that makes it a guarantee.

Next in A4.6: A4.6.2 · The closure — the completion rule, clause by clause, and what “run, not asserted” means.

References

The sources behind the traceable chain, and where it connects in the course.

Sources

Related in this course