A5.3.3 · dive 3/3
The file list
The runtime shape says what runs; the task DAG says in what order. The third thing the topology pins is which files the change touches — created, edited, deleted, and the boundary nothing below it may move.
The brief's Touched files paragraph names every file the agent creates, every file
it edits, and the one it deletes, and pins the engine, store, contexts, and Portal
facade as unchanged. Toggle the figure on the right to read the list as three actions — the agent
creates the new app's files, edits two core files, and deletes one.
The touched files, by action · toggle created / edited / deleted
What a file list is
The first two parts of the execution topology drew the shape and the order: the runtime shape says what runs, and the task DAG says in what order it is assembled. The third part is smaller and more concrete — the exact set of files the change touches. The brief calls it the Touched files paragraph, and it enumerates every path, tagged by what happens to it: created, edited, or deleted.
A file list bounds the work two ways at once. It tells the agent which files to write, so it does not invent a layout. And it tells the agent — and the reviewer — which files must not move, so a change cannot spread past the paths the Operator chose. A change with a written file list has a known blast radius; a change without one can reach anywhere the agent decides to reach.
The principle
The file list bounds the change — the agent creates and edits exactly the named files, and nothing below the boundary. The list of paths is also a list of what stays still.
On the Portal
f6.1.llms.md lists every new apps/portal_web/ file, the
two core touches, and the one deletion, and pins the engine, store, contexts, and Portal
facade as unchanged.
This closes A5.3: the runtime shape, the task DAG, and the file list are the three things a spec leaves open about how code is assembled. A5.4 turns each unit of that work into an agent story with a closing gate.
Touch only the listed files
The file list is not only a to-do list of files to write. It is a fence. An edit to a file the brief names
is in scope; an edit to anything below the facade boundary is out of scope, even when the edit would compile
and even when it would “work.” The boundary the list respects is the same
context boundary the companion course draws: the web layer
reaches the domain only through the Portal facade, never
Portal.Engine. So the engine, the store, the contexts, and the facade are absent
from the list by design.
Toggle the test below between an edit to a listed file and an edit to the engine. The first is in scope — it is one of the thirteen paths the brief names. The second is out of scope — it sits below the boundary the brief pins unchanged, so it never appears in the list at all.
In the list, or below the boundary · toggle the candidate edit
A file list is the change's blast radius, written down before the agent runs.
On the Portal
The Portal's web bootstrap ships from f6.1.llms.md, and its Touched files
paragraph is exact. The new app apps/portal_web/ brings ten created files — its
mix.exs, the portal_web.ex entrypoint,
telemetry.ex, endpoint.ex,
router.ex, the controller, the view, and the two
.heex templates. Two core files are edited, two lines only:
apps/portal/lib/portal/application.ex drops the Bandit
child, and apps/portal/mix.exs drops the bandit dep. One
file is deleted: the old Portal.Web.Router, replaced by the Phoenix router in the
new app.
# f6.1.llms.md — Touched files (created · edited · deleted), and the pinned boundary # # CREATED — new app apps/portal_web/ (10): apps/portal_web/mix.exs apps/portal_web/lib/portal_web.ex application.ex telemetry.ex apps/portal_web/lib/portal_web/endpoint.ex router.ex apps/portal_web/lib/portal_web/controllers/course_controller.ex apps/portal_web/lib/portal_web/controllers/course_html.ex apps/portal_web/lib/portal_web/controllers/course_html/index.html.heex apps/portal_web/lib/portal_web/controllers/course_html/error.html.heex # # EDITED — two core lines only (2): apps/portal/lib/portal/application.ex # drop the Bandit child (four → three) apps/portal/mix.exs # drop the bandit dep # # DELETED (1): apps/portal/lib/portal_web/router.ex # the old Portal.Web.Router (a Plug.Router) # # PINNED UNCHANGED — below the facade boundary, absent from the list by design: # Portal.Engine · Portal.Store · the contexts · the Portal facade (as F5 left them)
The principle
An agent told only to “add the web layer” might edit anything. A file list names the exact paths and the exact action on each, so the change cannot spread past what the Operator chose.
On the Portal
f6.1.llms.md ships ten created files in apps/portal_web/,
two one-line edits, and one deletion, and the Portal facade, engine, store, and
contexts never appear — the blast radius is the list.
A4 wrote what to build; the topology's file list writes exactly where — and where the agent may not reach.
Recap — the file list bounds the change
The runtime shape, the task DAG, and the file list are the three parts of the execution topology — what runs, in what order it is built, and in which files. The file list enumerates every touched path tagged created, edited, or deleted, and pins everything below the facade boundary as unchanged, so the agent creates and edits exactly the named files and the change has a known blast radius. With the topology fixed, the next module turns each unit of that work into an agent story — a Directive and the Acceptance gate that closes it.
Next in A5: Agent stories — the executable counterpart of a user story, a Directive plus the Acceptance gate that closes it.
References
Primary sources for a machine-readable file manifest and for bounding the change an implementer is allowed to make, and where the topology this dive completes and the boundary it respects are defined in the courses.
Sources
- llmstxt.org — The /llms.txt convention — the machine-readable brief whose Touched-files section enumerates the exact paths the agent acts on.
- Hunt, A. & Thomas, D. — The Pragmatic Programmer — orthogonality and a known blast radius: a change should touch only the parts named, nothing below the boundary.
- Anthropic — Building effective agents — scoping a coding agent's edits to an explicit set of files rather than an open-ended workspace.
Related in this course
- A5.3 · Execution topology — the module hub: runtime shape, task DAG, file list.
- A5.3.2 · The task DAG — the build order the files realise.
- A5 · The agent brief — the chapter landing.
- Companion · Phoenix request lifecycle (F6) — the real chapter whose
f6.1.llms.mdthis dive grounds on. - Companion · Phoenix contexts (F6) — the boundary the file list keeps below itself.