Architecture as Theory of the System — Evaluation¶

SPEC-138 · research/document deliverable · concludes with one of {Adopt, Defer, Not needed}.

Reading order: this is a research report, not an ADR. It runs Synthesis → Inventory → adversarial Gap Analysis → Recommendation, then appends the source template verbatim. The recommendation (Defer) is offered for the toolkit owner's ratification, not enacted — implementation is explicitly out of scope (SPEC-138 Scope).

1. Source Synthesis¶

Three sources, observed together, reframe system architecture from documentation into the persistent theory of the system that sits beneath specs and plans. Each is cited from a locally-captured primary; the every.to essay was fetched live on 2026-07-06 (not paywalled).

1.1 Naur / Ekrem — "Programming as Theory Building"¶

Source: intake/knowledge/workflows/2026-05-12 programming-as-theory-building.md (Christian Ekrem, revisiting Peter Naur 1985).

The load-bearing claim, verbatim: "a program is not its source code. Rather, programming fundamentally involves constructing a shared mental model—a theory encompassing how systems work, why they work that way, and how they should evolve." (line 26)
The theory-loss point, verbatim: "When those individuals depart, the theory disappears, leaving orphaned code lacking context and purpose." (line 28)
The LLM-era sharpening: LLM output "isn't merely theory-less; it's 'nobody's theory'" — code from statistical patterns "without understanding business domains, system conceptual models, or nuanced architectural trade-offs." (line 36)
A crucial caveat the source itself raises: "While documentation, Architectural Decision Records, and clean code help, written words ultimately fail capturing everything programs represent and mean." (line 60) — i.e. the theory is partly irreducible to any artifact. This is the strongest internal argument against believing a new document will "hold" the theory.

1.2 @timajwilliams — the `ARCHITECTURE.md` template¶

Source: intake/knowledge/patterns/2026-05-12 architecture-md-system-template.md (MIT-licensed, https://architecture.md/).

Stated intent, verbatim: "This document serves as a living template designed to equip agents with comprehensive understanding of codebase architecture, enabling efficient navigation and effective contribution from day one." (line 18)
It is an opinionated 11-section structural artifact (reproduced verbatim in the Appendix):
Project Structure · 2. High-Level System Diagram · 3. Core Components · 4. Data Stores ·
External Integrations · 6. Deployment & Infrastructure · 7. Security Considerations ·
Development & Testing Environment · 9. Future Considerations · 10. Project Identification ·
Glossary / Acronyms.
Its distinguishing property is that it targets an existing, evolving codebase and is agent-first ("from day one"), present-tense and living — not a design-time plan.

1.3 every.to — "The Culture of AI Engineering"¶

Source: https://every.to/thesis/the-culture-of-ai-engineering (fetched 2026-07-06, full text).

Direct quote: "Architecture is the theory of the system" — describing it as capturing how "the business problem maps to the codebase" and the "key decisions."
The foundation-layer framing is expressed as a pace-layers stack (slowest → fastest): Standards → Architecture → Specs → Plans → Code. Architecture is a slow layer that changes rarely and constrains the faster layers above it; specs "shrink the planning space" within that frame.
Nuance worth recording (a refinement of source #3, not a fourth source — so this is not the EC-3 case): the essay does not place architecture at the absolute bottom — standards sit below it — and it does not literally claim "specs are generated from architecture." It claims the weaker, defensible thing: architecture is a slow-moving layer that the faster spec/plan/code layers sit above and are constrained by. SPEC-138's Problem section slightly over-reads this as "specs are derived from architecture"; the accurate reading is constrained by, not derived from. This distinction matters for the gap analysis, because it lowers the strength of the "architecture must generate specs" argument. Verifiability flag (EC-1 / RES-6): this Defer-favorable correction rests on the one source fetched live (every.to, 2026-07-06) rather than from a locally-captured primary — see the durability caveat in §1.4. The interpretation is sound on the fetched full text, but a ratifier who cannot re-fetch the essay cannot independently verify it against a stored copy.

Synthesis. All three converge on one definition: the theory of the system is a persistent, structure-and-rationale-bearing mental model of how the system is built and why, kept current as the system evolves, and — in the LLM era — made legible to agents so they can contribute coherently. Naur supplies the "why it's irreplaceable," the template supplies a concrete "what it looks like," every.to supplies the "where it sits in the stack." Naur (1.1, line 60) also supplies the built-in skepticism: no written artifact fully captures the theory.

1.4 Limitations of this evidence base (stated so the verdict is read with them in view)¶

This is a short list of the ways the evidence here is one-sided or unverifiable, consolidated in one place rather than scattered as inline caveats:

The evidence is one-directional — all three primaries advocate the concept. None argues the against case, and no counter-source on the maintenance cost of living documentation (the well-known "docs drift out of sync with code" failure, which a mandatory ARCHITECTURE.md would be directly exposed to) was located or commissioned. The only skeptical input is internal to a pro source (Naur, §1.1 line 60: written words "ultimately fail capturing everything"). A fair reading should assume the pro-Adopt case is presented at closer to full strength than the con case.
One source is not durably captured. Two primaries are locally-stored files (re-verifiable offline); the every.to essay was fetched live on 2026-07-06 and no archival copy was stored, so the quotes in §1.3 cannot be re-checked against a fixed local anchor (EC-1 residue; see the RES-6 flag in §1.3). Storing a captured copy is a cheap follow-up if this verdict is ratified.
Two of the three decision guardrails structurally lean Defer. The proportionality gate (§3.4) and the empirical-signal check (§3.5) are constructed so that absence of demonstrated cost biases toward Defer (a deliberate, plan-locked shaping choice, plan.md:33–34). That is a defensible conservatism for adding a mandatory artifact, but it means the phrase "not a predetermined verdict" is only partly true: the union-coverage guardrail (§3.2) could have produced Adopt, but the other two could realistically only produce Defer-or-weaker on this evidence. The verdict is honestly earned on §3.2; it is not the output of three independent coin-flips.

2. Toolkit Artifact Inventory (evidence-based)¶

Each row was produced by reading the artifact's actual definition (path+line cited), per the locked shaping decision to inventory from content, not description.

Artifact	Scope (what it covers)	Persistence	Audience	Workflow position
`/vt-c-pd-pid` → `03-PRD/PID.md`	System architecture, stack+versions, data model, API conventions, security/compliance, deployment, technical risks — the "technical companion to the PRD" (pd-pid SKILL.md:9, 431–439)	Semi-persistent: versioned per project, lives in `03-PRD/`, updated on iteration (`--update`, SKILL.md:615–625)	Both — human decides at Step 2/5, agents consume for build	Design-time, per project, in the PD workflow before `/vt-c-2-plan` (SKILL.md:14)
`CLAUDE.md`	Agent operating instructions & conventions. The toolkit's own = Path Resolution + Session Start Protocol (CLAUDE.md:3–22). Per-project templates via scaffold	Long-lived, continuously edited	Agent-first	Read at session start, every session
`/vt-c-adr` → `docs/decisions/ADR-*.md`	One architecture decision per file: Context / Alternatives / Decision / Consequences (adr SKILL.md:9, 88–97), Nygard format	Permanent but point-in-time — each ADR freezes one decision; supersede-not-edit (SKILL.md:185–208)	Both	Captured during `/vt-c-3-build` when a decision deserves a durable record (SKILL.md:13)
`docs/architecture/`	Free-form; no convention. In V025 the directory does not exist — `ls docs/architecture/` → No such file or directory (not merely empty; it would have to be created)	N/A — absent	N/A	Designated-but-nonexistent home
`/vt-c-c4-diagram` → `.mmd`/PNG	Structural topology only: actors, containers, relationships from `c4:` YAML → branded Mermaid C4 (c4 SKILL.md:12–15, 105–108)	Regenerable artifact (source of truth is the `c4:` frontmatter)	Human (visual); agents can read the `c4:` YAML source	On demand, when a system note carries `c4:` frontmatter
`PRODUCT-VISION.md`	Intent, not structure: Vision, Problem Space, Target Audience, Success Definition, Strategic Context, Guiding Principles (template lines 3–26)	Long-lived	Both (mostly human)	Read at design/planning time; input to `/vt-c-pd-pid` (pd-pid SKILL.md:33, 153)

3. Gap Analysis¶

The single question (US-3): Does the toolkit have a persistent, agent-readable, structure-oriented theory-of-the-system artifact today?

The verdict is bound to a falsifiable union-coverage test (not the "no single artifact" framing of the Problem section, which would make a gap true by construction). The three role axes map onto the inventory's columns: structure-oriented ← scope, persistent ← persistence, agent-readable ← audience.

3.1 Guardrail 1 — Null-hypothesis steelman¶

Null hypothesis: the union of existing artifacts already covers the role. Steelmanning it: the PID already carries system architecture, data stores, API, security, deployment and risks (§2 row 1) — that is 6 of the template's 11 sections in one persistent, agent-consumable file. Add C4 for the system diagram (§2 row 5), ADRs for decision rationale (§2 row 3), the glossary/identification sections are trivially addable, and CLAUDE.md already gives agents a day-one entry point. On this reading the "theory of the system" is not missing — it is decomposed across PID (structure) + ADR (rationale) + C4 (diagram) + CLAUDE.md (agent entry), which is exactly the EC-2 role-decomposition scenario. The null hypothesis is not easily refuted — it survives for greenfield, design-time work.

Why this triggers EC-2's scenario but not its default verdict (reconciliation — resolves DOC-1 / RES-8). EC-2 (spec.md:151) says: if the inventory reveals overlap so severe that the role splits into 2+ existing roles, the recommendation defaults to Not needed. The decomposition above does meet EC-2's antecedent — but only for the greenfield/design-time slice. EC-2's default is deliberately overridden to Defer here because the decomposition is incomplete: it leaves the living-map-of-an-evolving/brownfield-codebase slice genuinely uncovered (established in §3.2). "Not needed" would assert the union covers the role fully; that is false. So the honest verdict is Defer (a real-but-narrow gap that is not yet worth filling), not Not needed (no gap at all). This is a considered override of a default, not an oversight — a ratifier who reads the gap as fully covered should downgrade to Not needed; a ratifier who weights the living-map slice more heavily should upgrade to Adopt (see §3.2a, both readings).

3.2 Union-coverage matrix¶

Role axis	Covered by the union?	By which artifact(s)	Residual weakness
Structure-oriented	Yes	PID (architecture/data/API/deploy), C4 (topology)	Split across two artifacts; C4 is topology-only
*Persistent — greenfield/design-time* slice**	Yes	PID (versioned per project), CLAUDE.md, PRODUCT-VISION	Covered where a project has a PID
*Persistent — living-map-of-an-evolving/brownfield-codebase* slice**	No	— (PID is design-time; ADRs are point-in-time fragments; C4 is regenerated topology)	This is the uncovered slice — no artifact is a living present-tense structural map
Agent-readable	Yes	CLAUDE.md (agent-first), PID, C4 YAML	—

Why the persistent axis is split (resolves RES-2). Reported as a single "partial," the axis smuggles a third value into a rule the spec (FR-4) requires to be binary. Splitting it into two sub-axes restores the binary: the greenfield/design-time slice is a clean Yes, the living-map/brownfield slice is a clean No. The "partial" was never a third truth value — it was two different questions averaged into one. Every structure-bearing artifact the toolkit has (PID, C4) is either design-time or a point-in-time fragment; there is no living, present-tense structural map of an existing/evolving codebase — precisely the ARCHITECTURE.md template's distinct use case (§1.2, "living… from day one"). The PID is the near-miss: forward-looking design ("recommend based on project needs," stack selection), not a current-state theory, and it does not exist for brownfield projects or for the toolkit repo itself (no PID present).

3.2a The binary verdict depends on which question US-3 is asking — stated under BOTH readings (resolves RES-7 / DOC-3)¶

US-3 (spec.md:106–108) asks: "Does the toolkit have a persistent, agent-readable, structure-oriented theory-of-the-system artifact today?" — worded with a singular "artifact." That singular wording admits two defensible readings, and they give opposite binary answers. This reversal is the crux of the whole evaluation, so it is surfaced rather than resolved silently:

Reading A — literal / singular-artifact ("is there one artifact that is the role's home?"). Answer: No — the toolkit does not HAVE it. §3.3 rules all six candidate artifacts out as the role's home; none individually is a persistent, agent-readable, structural theory. Under this reading gap exists = YES, and the natural verdict tilts toward Adopt.
Reading B — union-coverage ("do the existing artifacts, taken together, already cover the role?"). Answer: Largely yes for greenfield design (PID + C4 + ADR + CLAUDE.md), no for the living-map slice (the split above). Under this reading there is no hard gap — only the narrow living-map gap — and the natural verdict tilts toward Defer / Not needed.

This evaluation adopts Reading B (union-coverage) as the primary test, because a role that is fully served by a well-understood combination of existing artifacts is not a genuine capability gap — requiring it to live in a single file is a stylistic preference, not a missing capability. That choice is stated openly because it is outcome-determining: it favors Defer over Adopt. A ratifier who holds that the theory-of-the-system role must have a single canonical home (Reading A) should read this evaluation as recommending Adopt, not Defer — the underlying facts in §3.3 are unchanged; only the choice of test differs.

Binary verdict (Reading B, the adopted test): NO hard gap — one real, narrow gap on the living-map slice. (Under Reading A the binary verdict is instead: gap exists = YES.) Both are recorded so the verdict is not mistaken for reading-independent.

3.3 Each artifact ruled in / out as the role's home¶

PID — ruled partially in, ultimately out: closest on structure + agent-readable, but design-time and per-project; not a living current-state theory, absent for brownfield.
CLAUDE.md — out: agent-readable and persistent, but scope is conventions/operating instructions, not system structure.
ADRs — out: persistent and rationale-rich, but point-in-time fragments; the union of ADRs is a decision log, not a system map.
C4 diagram — out: structural but topology-only; no prose theory, rationale, data-store detail, security, or glossary; regenerated, not maintained as narrative.
docs/architecture/ — out: the designated home, but it does not exist in V025 (would have to be created, not merely populated) — a vacancy, not coverage.
PRODUCT-VISION.md — out: intent, explicitly not structure.

3.4 Guardrail 2 — Proportionality gate¶

Does Naur's "theory disappears when developers leave" failure mode exist at V025's scale?

Reflexivity flag (resolves RES-1). This proportionality argument is load-bearing for the Defer verdict, and it concludes that the cost of a new artifact is not yet worth bearing — a conclusion that favors the single maintainer who would bear that cost, and who is also the author/ratifier of this evaluation. That alignment of interest does not make the argument wrong, but it is a conflict worth naming: the party who benefits from "don't add process yet" is the same party judging whether the process is needed. The empirical-signal check (§3.5) is included partly as an external counterweight to this — it is designed to overrule the maintainer's cost-aversion the moment a filed incident appears.

V025 is effectively single-maintainer (Rolf). The classic team-handoff failure mode — departing developers taking the shared model with them — does not exist here. However, it re-appears in reframed form: in the LLM-era workflow the "other developer" is the agent, and every fresh session cold-starts with zero theory and rebuilds it from scattered artifacts. The toolkit already pays this cost visibly — the CLAUDE.md Session Start Protocol (CLAUDE.md: 12–22) exists precisely to re-orient an agent each session, and this session itself opened by running pwd / git worktree list to reconstruct context. So the failure mode is real but moderate: not human-departure catastrophe, but a recurring per-session orientation tax. That tax scales with codebase complexity (125 skills / 55 agents / multi-worktree), which argues the threshold is approaching, not clearly crossed.

Counter-case, weighed honestly (resolves RES-10). The "moderate, single-maintainer scale" framing above understates one case: the toolkit repo itself is the strongest pro-Adopt example in the whole inventory — it is the highest-complexity, most-agent-touched codebase here, it has no PID (so the greenfield-union coverage of §3.2 does not even apply to it), and §4's own follow-up direction picks it as the first pilot. Judged on the toolkit repo alone, the proportionality gate arguably reads "threshold crossed," not "approaching" — the low-complexity frame that yields "moderate" is drawn from the typical consumed project, not from this repo. The verdict stays at Defer rather than flipping on this because the cost is still a recurring orientation tax, not a demonstrated failure (§3.5 found no filed incident even here), and because the Session Start Protocol currently absorbs it. But this is the single fact most likely to fire re-evaluation Trigger 1, and a ratifier who weights the toolkit repo as the primary consumer (rather than as one project among many) could reasonably read this gate as already favoring Adopt.

3.5 Guardrail 3 — Empirical-signal check¶

Has any consuming project actually reported architecture drift or agent-onboarding failure? Searched: docs/change-ledger, docs/solutions/patterns/, intake/, session MEMORY. Findings: - No intake proposal or pattern doc reports "architecture drift" or a failed agent onboarding as a discrete incident. - Weak, indirect signal only: the Session Start Protocol is a codified orientation ritual, and MEMORY records repeated multi-worktree/branch-context confusion — both symptoms of agent cold-start cost, but neither filed as an architecture-theory gap.

Empirical signal is weak. Per the shaping decision, absence of a demonstrated cost biases the recommendation toward Defer, not Adopt.

4. Recommendation¶

Verdict: Defer¶

The three guardrails point consistently away from Adopt and away from a flat Not-needed:

Union coverage (§3.2) shows no hard gap — the role is largely covered for greenfield design by PID + C4 + ADR + CLAUDE.md — but a real narrow gap remains: no living, present-tense structural theory for an evolving/brownfield codebase (the template's actual niche). That the gap is partial rules out a confident "Adopt now."
Proportionality (§3.4) finds the failure mode real but moderate (reframed as agent cold-start), threshold approaching but not clearly crossed at single-maintainer scale.
Empirical signal (§3.5) is weak — no filed drift/onboarding incident. Adopting a new mandatory artifact now would be building ahead of demonstrated need, and would risk duplicating PID + C4 + CLAUDE.md rather than filling a proven hole (the SPEC-131 proportionality lesson).

Defer is therefore the honest, guardrail-consistent call: the idea is sound and the gap is real but narrow; the cost that would justify a new foundation-layer artifact is not yet demonstrated.

Re-evaluation triggers (any one flips this to Adopt)¶

Each trigger below states who checks it, when, and against what observable signal, so the Defer does not silently become permanent (resolves RES-4). Owner of all three: the toolkit maintainer. Cadence: reviewed at each /vt-c-toolkit-review pass (the same pass that would otherwise re-surface this proposal), and Trigger 2 is additionally checkable on demand by the intake/pending/ grep below.

Brownfield onboarding cost is observed (qualitative — maintainer judgement at /vt-c-toolkit-review) — a project (or the toolkit itself) onboards an agent to an existing codebase and the session demonstrably burns significant effort reconstructing structure that a living ARCHITECTURE.md would have supplied. Observable proxy: a session-journal or MEMORY entry recording repeated re-orientation/wrong-subsystem work attributed to no system map. Not mechanically countable; the proxy keeps it from being purely subjective.
≥2 projects report architecture drift (mechanical — countable) — 2+ filed drift/onboarding proposals in intake/pending/ naming the missing structural-theory role. Check: grep -rli 'architecture drift\|onboarding gap\|no system map' intake/pending/ ≥ 2 distinct files. On the threshold vs the cited bar (resolves RES-9): the Constitution's Principle III promotion bar is "3+ similar issues → Required Reading." This trigger is deliberately set one lower (≥2) because re-evaluating a deferred question is far cheaper than the promotion that bar governs — a re-open only re-runs this analysis with fresh signal; it does not itself mandate anything. Firing re-evaluation one unit below the promotion bar is intentional, not a mis-citation. (A ratifier who prefers strict alignment may raise this to 3.)
Toolkit complexity crosses a felt threshold (qualitative — maintainer judgement at /vt-c-toolkit-review) — the Session Start Protocol stops being sufficient to orient a fresh agent. Observable proxy: ≥1 filed incident or pattern doc tracing repeated wrong-subsystem edits to the absence of a system map (distinct from Trigger 1 in that it is about the toolkit repo's own growth, not a consumed project's onboarding).

Direction for the eventual follow-up (recorded so it is not re-derived)¶

If a trigger fires, the follow-up SPEC should consolidate, not add a parallel silo: adopt the 11-section template as the convention for docs/architecture/ (which does not yet exist and would be created by that follow-up, not populated), source its structure sections from the existing PID and its diagram from C4 (avoid duplication), carry decision rationale by linking ADRs rather than restating them, and pilot it on the toolkit repo itself first (the highest-complexity, PID-less, most-agent-touched codebase). That follow-up brief would stop at the "living vs regenerated" gray area — how the map stays current — and flag it for /vt-c-shape before activation (EC-4).

Loop closure (Success Criterion 4)¶

Because the verdict is Defer, the source proposal intake/processed/from-research/2026-05-12-inbox-architecture-md-template.md is updated inline with this conclusion so future /vt-c-toolkit-review / /vt-c-content-evaluate passes do not re-surface the question without a trigger.

Provisional until ratified (resolves DOC-8). This deliverable's status is recommendation-for-ratification — the Defer is offered, not enacted. The loop-closure update to the intake file is therefore provisional: it carries a "pending ratification" caveat, and a ratifier who overrides to Adopt (Reading A, §3.2a) or Not needed (§3.1) must revert the intake file's toolkit_proposal_status/evaluation_verdict fields accordingly. The intake file records the recommended disposition, not a settled one.

Appendix — `ARCHITECTURE.md` template (verbatim, for reference)¶

Reproduced verbatim (FR-7) from intake/knowledge/patterns/2026-05-12 architecture-md-system-template.md (captured from https://architecture.md/). Released under the MIT License · Created by @timajwilliams. Included as reference only; no framework comparison is implied (SPEC-138 Out-of-Scope). Illustrative example content in the source (directory tree, diagram, technology names) is generic to the template and not specific to any VisiTrans system.

Architecture Overview¶

This document serves as a living template designed to equip agents with comprehensive understanding of codebase architecture, enabling efficient navigation and effective contribution from day one.

1. Project Structure¶

High-level overview of directory and file structure, categorized by architectural layer or major functional area:
[Project Root]/
├── backend/              # Server-side code and APIs
│   ├── src/              # Main source code
│   │   ├── api/          # API endpoints and controllers
│   │   ├── client/       # Business logic and services
│   │   ├── models/       # Database models/schemas
│   │   └── utils/        # Utility functions
│   ├── config/           # Configuration files
│   ├── tests/            # Unit and integration tests
│   └── Dockerfile        # Deployment configuration
├── frontend/             # Client-side code for user interfaces
│   ├── src/              # Main source code
│   │   ├── components/   # Reusable UI components
│   │   ├── pages/        # Application pages/views
│   │   ├── assets/       # Images, fonts, static assets
│   │   ├── services/     # API interaction services
│   │   └── store/        # State management
│   ├── public/           # Publicly accessible assets
│   ├── tests/            # Unit and E2E tests
│   └── package.json      # Dependencies and scripts
├── common/               # Shared code, types, utilities
│   ├── types/            # TypeScript/interface definitions
│   └── utils/            # General utilities
├── docs/                 # Project documentation
├── scripts/              # Automation scripts
├── .github/              # CI/CD configurations
├── .gitignore            # Untracked files specification
├── README.md             # Project overview
└── ARCHITECTURE.md       # Architecture documentation
2. High-Level System Diagram¶
[User] <--> [Frontend Application] <--> [Backend Service 1] <--> [Database 1]
                              |
                              +--> [Backend Service 2] <--> [External API]
3. Core Components¶

3.1. Frontend¶

Name: Web/Mobile Application

Description: Primary user interface enabling interaction with system functionalities

Technologies: React, Next.js, Vue.js, or native frameworks

Deployment: Vercel, Netlify, Cloud CDN services

3.2. Backend Services¶

Document each significant service including: - Name and primary purpose - Technology stack employed - Deployment infrastructure

4. Data Stores¶

List and describe databases and persistent storage: - Primary data repositories (PostgreSQL, MongoDB) - Cache layers (Redis) - Message queues (Kafka, RabbitMQ)

5. External Integrations¶

Third-party services and APIs the system interacts with (Stripe, SendGrid, Google Maps, etc.)

6. Deployment & Infrastructure¶

Cloud Provider selection

Key services utilized

CI/CD pipeline implementation

Monitoring and logging solutions

7. Security Considerations¶

Authentication mechanisms (OAuth2, JWT, API Keys)

Authorization patterns (RBAC, ACLs)

Data encryption strategies

Security tools and practices

8. Development & Testing Environment¶

Local setup instructions

Testing frameworks

Code quality tooling

9. Future Considerations¶

Document architectural debt and planned enhancements.

10. Project Identification¶

Project Name

Repository URL

Primary Contact/Team

Last Update Date

11. Glossary / Acronyms¶

Define project-specific terminology.

Released under MIT License • Created by @timajwilliams

Architecture as Theory of the System — Evaluation¶

1. Source Synthesis¶

1.1 Naur / Ekrem — "Programming as Theory Building"¶

1.2 @timajwilliams — the ARCHITECTURE.md template¶

1.3 every.to — "The Culture of AI Engineering"¶

1.4 Limitations of this evidence base (stated so the verdict is read with them in view)¶

2. Toolkit Artifact Inventory (evidence-based)¶

3. Gap Analysis¶

3.1 Guardrail 1 — Null-hypothesis steelman¶

3.2 Union-coverage matrix¶

3.2a The binary verdict depends on which question US-3 is asking — stated under BOTH readings (resolves RES-7 / DOC-3)¶

3.3 Each artifact ruled in / out as the role's home¶

3.4 Guardrail 2 — Proportionality gate¶

3.5 Guardrail 3 — Empirical-signal check¶

4. Recommendation¶

Verdict: Defer¶

Re-evaluation triggers (any one flips this to Adopt)¶

Direction for the eventual follow-up (recorded so it is not re-derived)¶

Loop closure (Success Criterion 4)¶

Appendix — ARCHITECTURE.md template (verbatim, for reference)¶

Architecture Overview¶

1. Project Structure¶

2. High-Level System Diagram¶

3. Core Components¶

3.1. Frontend¶

3.2. Backend Services¶

4. Data Stores¶

5. External Integrations¶

6. Deployment & Infrastructure¶

7. Security Considerations¶

8. Development & Testing Environment¶

9. Future Considerations¶

10. Project Identification¶

11. Glossary / Acronyms¶

1.2 @timajwilliams — the `ARCHITECTURE.md` template¶

Appendix — `ARCHITECTURE.md` template (verbatim, for reference)¶