From 30-Page Waterfall PRDs to a 4-Layer JIT Intent Compiler#

How Open-Core `nomos` Replaces Monolithic Upfront Prompt Novels With Progressive Vertical Lowering Across intent/intent.md, nomos.yaml, TC-* Slice Specifications, and Hermetic INT/SUB Worktree Transactions.

Architectural Scope & Executive Companion
Substrate Version: Open-Core `nomos v4.13.0` (Apache 2.0, zero external telemetry)
Executive Companion Brief (gantlett.io): EB-03: Replacing 30-Page AI Specification Novels With a 4-Layer Progressive Intent Compiler
Commercial Engagement Mapping: 14-Day AI Governance & Seam Charter Pilot

1. The False Dichotomy in Agentic Software Engineering#

Watch engineering teams adopt Claude Code, Cursor, Antigravity, OpenCode, or Windsurf on a real build and almost all of them hit one of two failure modes within thirty days:

1. Unbounded Vibe Prompting (Zero Spec): Developers type conversational prompts straight against a shared branch. By Week 2, agents have invented duplicate retry helpers, imported infrastructure packages straight into pure domain modules, and weakened failing assertions to turn CI green.
2. 1995 Waterfall in Markdown (The 30-Page Upfront Spec): Burned by vibe coding, teams swing to the opposite extreme and spend two weeks authoring a 30-page Markdown PRD detailing features A through Z before a single line of code runs.

The 30-page Markdown spec feels responsible on Day 1 and collapses on Day 3. Software engineering learned thirty years ago that giant upfront specifications cannot survive contact with a live runtime or a real user testing the first screen. The moment a stakeholder tries Slice A on Day 3 and changes a tenancy or billing workflow, pages 6 through 30 of the Markdown novel silently go stale. Worse, feeding all 30 pages into every agent session burns working-memory context on features ten weeks away while diluting attention on today's invariants.

The fix is not throwing away specifications. The fix is compiling requirements vertically one verified slice at a time rather than expanding prose horizontally upfront.

2. Architecture of the 4-Layer Progressive Intent Compiler#

Real compilers never jump straight from high-level intent to raw machine instructions in one flat file; they lower intent progressively through typed intermediate representations. Nomos structures greenfield and brownfield engineering along four explicit layers between human intent and production Git:

flowchart TD
    L0["Layer 0: 2-Page North Star Charter<br/>(intent/intent.md - Global Domain & Security Laws)"]
    L1["Layer 1: Compiled Repository Physics<br/>(nomos.yaml + ADRs - Read-Only main & Layer Boundaries)"]
    L2["Layer 2: 1-Page JIT Vertical-Slice Spec<br/>(specs/*_spec.md - Fenced Types + TC-* Vectors + SHA-256 Digest)"]
    L3["Layer 3: Hermetic Worktree Transaction<br/>(INT-N -> SUB-N + 42 AST Checks + Git Notes + mneme.db)"]

    L0 -->|"Day 1 Distillation"| L1
    L1 -->|"One Slice Ahead"| L2
    L2 -->|"PLAN -> EDIT -> REVIEW -> SYNC"| L3
    L3 -->|"SHA-256 Taint & Verified Lessons"| L2

3. Compiling a Messy 30-Page Client Backlog Into Live Software#

Suppose a team kicks off a multi-tenant ledger service and arrives with a 30-page requirements document. Instead of pasting 30 pages into .cursorrules or CLAUDE.md, the 4-layer workflow compiles it in three tight moves:

Step A: Distill Layer 0 (intent/intent.md) & Lock Layer 1 (nomos.yaml) on Day 1#

Strip the 28 pages of speculative future screens back into a parked discovery backlog and extract only the true system invariants into intent/intent.md (for example: Tenant A can never read Tenant B rows, all currency amounts are integer minor units, every external webhook mutation is idempotent). Immediately compile module seams into trunk-pinned nomos.yaml:

project: "acme-ledger"
default_branch: "main"
governance:
  boundary:
    enforce: true
  architecture_boundaries:
    - name: "domain-purity"
      from: "internal/domain/**"
      forbid_imports:
        - "internal/infra/**"
        - "internal/http/**"
  contracts:
    spec_roots:
      - "intent/architecture/specs"
    strict_types: true
    verify_obligations: true
    fail_on_stale_obligations: true

Before an agent writes a single endpoint, the walls of the repository are physically enforced in under 5 milliseconds.

Step B: Lower Slice #1 Just-In-Time (Layer 2 -> INT-1)#

Features 2 through 20 remain single-line roadmap entries. You author only intent/architecture/specs/ledger/tenant_posting_spec.md (~80 lines) for the Day 1-2 walking skeleton, ending with executable TC-* obligations:

Commit the specification cleanly on the Intent plane (INT-1). Because INT-* tasks are plane-separated from SUB-* implementation tasks (Law 7), the coding agent implementing SUB-2 cannot quietly delete TC-LED-01 from the specification to make a broken implementation pass.

Step C: Execute SUB-2 & Handle Day-4 Requirement Pivots via SHA-256 Taint#

The coding agent executes SUB-2 inside an isolated worktrees/acme-ledger-SUB-2 sandbox, binds unit tests to @verifies TC-LED-01..03, passes all 42 nomos verify probes, and merges via nomos task sync - stamping the exact 64-char SHA-256 digest of tenant_posting_spec.md into refs/notes/nomos/releases.

When the client tests the live walking skeleton on Day 4 and says "Workspaces now require multi-currency settlement accounts," you do not hunt through a 30-page document:

1. You update tenant_posting_spec.md in INT-3 (+15 lines and TC-LED-04).
2. On the very next nomos handshake, SHA-256 taint detection compares the current spec digest against the last verified Git Notes receipt and flags only the exact downstream SUB-* modules referencing @intent tenant_posting_spec.md (#StaleSpecObligation).
3. Meanwhile, verified domain pitfalls learned during Slice #1 are recalled automatically from local SQLite mneme.db on Slice #2 without bloating Turn-1 prompt headers.

4. Adopting the 4-Layer Workflow Today#