Organizing project documents

Series: Aigile deep dives, paper 02 of 09. Elaborates working paper Section 6. Depends on Paper 01.

Abstract

Agents are stateless; some written layer is therefore mandatory. But treating all written artifacts alike reproduces either waterfall (everything heavy) or vibe coding (everything absent). This paper develops the three-layer model that resolves the tension: a durable layer maintained like law, an ephemeral layer treated as disposable work product, and a derived layer regenerated rather than maintained. It then specifies layered truth: the precedence rules that decide, in advance, which representation wins when representations disagree. The layer assignment of an artifact determines its maintenance model, its authority, its review process, and its drift exposure; most documentation dysfunction in agentic projects traces to artifacts living in the wrong layer.

1. Position in the framework

This paper formalizes the backward edge’s landing zones. Learning that flows upstream (Paper 01, R1) must arrive somewhere specific; the layers define where. Papers 03, 05, and 08 govern the durable layer’s lifecycle. Paper 04 governs the ephemeral layer’s economics.

2. The problem in full

2.1 Agent amnesia

A human team accumulates tacit knowledge automatically: every decision, every burned finger, every naming convention persists in heads and transfers socially. Agile could run documentation-light because this free memory system existed. Agents have no equivalent. Every context window begins near zero; yesterday’s subtle workaround is gone today. Mixed teams inherit the problem partially: the humans remember, the agents do not, and the humans progressively stop being the ones who implemented things (Paper 08).

Aigile’s position, stated in the working paper and repeated here as doctrine: pure tribal knowledge is a defect in any collaboration form, human-human, human-agent, or agent-agent. It was always a continuity liability; agile tolerated it because conversation was cheap. Aigile cannot tolerate it, and therefore must make written knowledge cheap to keep truthful, which is what the layer model is for.

2.2 The maintenance trap

The naive response, write everything down and keep it current, fails on cost. Documentation has a carrying cost proportional to its size and its rate of invalidation. Undifferentiated corpora grow until the carrying cost exceeds the will to pay it, then decay wholesale, and one stale document poisons trust in all of them. The escape is differentiation: pay heavy maintenance on a deliberately tiny set, pay nothing on a set that is regenerated, and let the middle be honestly disposable.

3. The mechanism: three layers

3.1 Layer 1, durable: maintained like law

Contents: the constitution (Paper 03), architecture decision records, domain invariants, cross-cutting concepts, collaboration and prompt norms (Paper 08). Character: read by every agent every session and by every onboarding human; smallest possible size; slowest rate of change; changed only through the amendment process; versioned semantically; refactored on the gardening cadence. This layer plays the role senior memory and culture played in human teams. Its size discipline is not aesthetic: every line costs context window in every agent session forever, so the durable layer has the highest price per line in the system.

3.2 Layer 2, ephemeral: condensed but comprehensible

Contents: feature intents, story specifications, task descriptions, acceptance criteria. Character: written per increment; sized by the increment rule (Paper 04); condensed, but explicitly required to remain comprehensible to a human reviewer, because the reviewer must be able to verify that the right thing is being built from the artifact alone. A story spec fits on one screen. Acceptance criteria are executable wherever possible, which moves them out of prose and out of drift’s reach. After validation, ephemeral artifacts are archived with their increment, never maintained. Their staleness after sealing is by design and costs nothing, because nothing reads them operationally again; historical readers get the archive plus the version stamp (Paper 03).

3.3 Layer 3, derived: regenerated, never maintained

Contents: module overviews, behavior summaries, data-flow explanations, API descriptions, onboarding tours. Character: produced on demand by an agent reading code and tests; timestamped; disposable. A regenerated document cannot drift, because it is recomputed from the source of truth at read time. The rule of thumb from the working paper holds: roughly half of what traditional projects maintained belongs here, and moving it here is the largest single reduction of drift surface available. The test for membership: if an agent with the codebase could reproduce the document, the document is derived; maintaining it by hand is paying to compete with a machine that works for free.

3.4 The misplacement diagnostic

Most documentation dysfunction is layer misplacement:

• A derived artifact maintained by hand produces endless descriptive drift (the module overview that is always wrong).
• An ephemeral artifact treated as durable produces the bloated spec corpus nobody reads (the SDD failure mode).
• A durable truth living only ephemerally produces the invariant that is violated every third feature because it is buried in an archived story (resolved by promotion, Paper 05).
• A durable layer holding derivable content produces a constitution too fat to read (resolved by demotion at gardening, Paper 08).

Drift statistics make misplacement measurable: chronic drift in a section is the signal that it lives in the wrong layer (Paper 05, Section 10.4 of the working paper).

4. Layered truth: precedence when representations disagree

Two truth anchors exist, and they answer different questions.

• Behavioral truth: code plus executable tests. For the question what does the system do, the running system and its tests win. Tests are the executable fraction of the specification. When prose and passing tests disagree, the prose is corrected. This is working software over documentation, applied with precision rather than as slogan.
• Intentional truth: the durable layer. For the question what should the system do and why, the constitution and decision records win, because intent, rationale, and rejected alternatives cannot be encoded in tests. When code violates the constitution, the code is the defect, however green its tests.

The contradiction rule. When the anchors contradict each other (tests pass, constitution violated; or two constitution clauses conflict), the contradiction is not a documentation chore. It is a discovered defect in one of the two anchors, it is information, and it takes the constitutional escalation path (Papers 03 and 05). Framing such findings as free bug reports, rather than hygiene failures, is what makes people willing to surface them.

5. Normative protocol

R2 (Total assignment). Every project artifact is assigned to exactly one layer, and the assignment is recorded. Unassigned artifacts default to derived, meaning nobody maintains them. R3 (Durable minimalism). Layer 1 admits content only through the amendment process and only when the content is intent, invariant, or decision rationale that no other layer can carry. Derivable content is inadmissible. R4 (Ephemeral comprehensibility). A story specification must be reviewable by one human in one sitting and must suffice, alone, for that human to verify the right thing is being built. Acceptance criteria are executable unless a written justification says why not. R5 (Derived non-maintenance). Layer 3 artifacts carry a generation timestamp and are never hand-edited. Corrections go to the source (code, tests, or Layer 1) and the artifact is regenerated. R6 (Layered truth). Behavioral disagreements resolve toward code and tests; intentional disagreements resolve toward the durable layer; anchor-versus-anchor contradictions escalate constitutionally and are never patched locally.

6. Orderly worked example

Orderly’s initial repository, inherited from its SDD phase, contains 14,000 lines of markdown. The layer triage: a 9-page architecture document is split into a 1-page constitution (Layer 1, after the Paper 03 process) and module descriptions that are deleted and replaced by a regeneration prompt (Layer 3). Forty accumulated feature specs are archived with their increments (Layer 2, sealed). Three sentences scattered across old specs turn out to be load-bearing invariants (idempotent order ingestion; billing entity is the invoice grouping key, the hard-won lesson of Paper 01; money is integer cents) and are promoted to the constitution. The maintained corpus drops from 14,000 lines to roughly 300. Six months later, the only documents anyone distrusts are two module overviews someone hand-edited in violation of R5.

7. Failure modes

• Layer creep: durable layer grows because promotion is easier than gardening. Counter: Paper 08’s cadence and R3.
• Hand-edited derived docs: the fastest way to rebuild universal distrust. Counter: R5 plus making regeneration one command.
• Prose acceptance criteria by default: silently re-expands the drift surface. Counter: R4’s written-justification requirement.
• Archaeology confusion: treating archived ephemeral specs as current truth. Counter: sealed archives carry the increment and constitution version stamps.

8. Metrics

Maintained-line count per layer (Layer 1 should be stable or shrinking); drift incidents per layer per month; fraction of acceptance criteria executable; regeneration coverage (share of descriptive questions answerable by Layer 3 generation).

9. Open questions

Optimal constitution size as a function of team and system scale; whether Layer 3 generation should be cached and diffed to detect behavioral change as a side effect; federation of layers across multiple teams (working paper Part VI, question 4).

10. Derivative artifacts

Playbook chapter with the layer-triage procedure for existing repositories; repository template (folder structure, stamps, regeneration prompts); website explainer with Figure 1; tooling requirements for freshness metadata and regeneration commands.