Prompt architecture: single-owner rule for instruction content across the ~45k-word prompt surface

[waleedkadous]

Problem

The shipped prompt surface (CLAUDE.md/AGENTS.md, hot-tier governance docs, protocol definitions, porch phase prompts, role docs, skills) measures roughly 45,000 words, and a duplication probe (2026-07-25) found the same rules repeated across 4–6 surfaces each. Consequences:

• Drift: an edit lands in one copy while the others go stale. Only the CLAUDE.md ↔ AGENTS.md pair is actively policed; the other duplicates are not.
• Token cost: duplicated rules ride into every phase prompt, every spawn prompt, every session.
• Ambiguity: a builder can encounter two differently-worded variants of the same rule and not know which is authoritative.

Read-out context: codev is strong on progressive disclosure (hot/cold governance tiers, on-demand skills) but weak on cross-layer duplication.

Proposed direction (to refine in spec)

1. Single-owner rule: every instruction has exactly one owning surface; all other surfaces reference or summarize it, never restate it. The spec should produce an inventory of the prompt surfaces and an ownership map before any restructuring.
2. Multi-model fleet tiering: tier prompt content by the consuming model's capability — smaller/cheaper models get fuller scaffolding, stronger models get the compressed form.
3. Scar rules exempt: hard-won prohibition rules (data-loss scars, gate rules) stay verbatim and always-on wherever they apply — deduplication never applies to them.

Protocol

SPIR — this needs a spec phase (surface inventory + ownership map + measurement of the win) before restructuring anything.

[waleedkadous]

Architect guidance for the spec phase (from Waleed, 2026-07-27)

Basis: this work is grounded in Anthropic's post The new rules of context engineering for Claude-5-generation models. Read it before writing the spec — the single-owner rule and fleet tiering in this issue's body are applications of its guidance.

Scope reminder — the full prompt surface, not just CLAUDE.md. The trims must cover:

• CLAUDE.md / AGENTS.md (and the hot-tier governance injections)
• the architect role docs
• the builder prompt surfaces (spawn prompts, porch phase prompts, protocol docs delivered to builders)
• the consult prompts (what each CMAP lane model receives)
  Both trees where applicable (codev/ and codev-skeleton/).

The hard problem is measurement. A particular challenge: how do we know a trim helped (or at least didn't hurt)? The spec must propose a measurement approach for the impact of prompt changes, not just an inventory and a restructuring plan. Think about what is observable per-surface (e.g. instruction-compliance incidents, gate-rejection rates, CMAP round counts, tokens per phase, duplication counts) and what a before/after comparison would look like. A trim proposal without a way to evaluate it is not accepted.

Field input from a production Fable-5-generation deployment (an external adopter running long multi-lane programs; details scrubbed, signal preserved) — treat these as evidence for the spec, not requirements:

• Fable-class models are uncalibrated for cost by default, not less capable: they maximize verification depth and delegation breadth unless given an explicit budget — and they honor stated constraints precisely; they just never invent them. Unbudgeted prompts produced unbounded process (audits-of-audits, compounding review layers); a budget stated in the prompt was honored immediately.
• Two externally-imposed rules that worked on first contact and are candidates for default role-prompt content: 'ceremony is priced per artifact' (full audit apparatus only where the artifact warrants it; otherwise one time-boxed review pass) and 'escalate, don't widen' (disclose out-of-brief findings with receipts; fixing them unasked is the failure mode even when the fix is right).
• Prompt templates should carry budget fields (scope boundary, review-pass count, time-box) — this maps to the fleet-tiering axis: stronger models need budgets more, not less.
• Strong models mint dense internal vocabularies (finding codes, round letters) that make reports opaque — an explicit legibility contract in role prompts is a candidate rule.
• (Their infra recommendations — verification primitives, status truthfulness, liveness detection — are Tower/porch feature work, out of this issue's scope.)

[waleedkadous]

Outcome: harvested, not fully merged

What shipped (PR #1281, the minimal harvest — merged as aa534081):

• The 17-file drift reconciliation — the one live bug this project surfaced. The codev/ shadow copies (which outrank the installed skeleton in the four-tier resolver) had drifted from codev-skeleton/ in 17 files, so the served SPIR/ASPIR builder prompts were missing their entire Multi-PR Mechanics and Verify Phase sections. All 17 are now byte-identical to the skeleton, with architect rulings E1 (max_iterations: 3) and E2 (check cwds moved to .codev/config.json porch.checks) applied.
• The knowledge artifacts: the 77-row shadow-tree audit with per-file rulings, the word-count baseline + after-measurement (N1: 21,856 → 20,324 served always-on words, −7.0%), the behavioral baseline (B1: 51.88% REQUEST_CHANGES, n=160, self-excluded), the measurement tooling (scripts/measure-prompt-surface.sh + prompt-behavior-metrics lib/CLI/test), and the full project review at codev/reviews/1252-prompt-architecture-single-own.md.

What did NOT ship, and why: the structural enforcement machinery — shadow-tree deletion with equivalence proofs, the scar-rule registry with line-exact CI enforcement, the ownership map with completeness contract, dedup via shared partials — was built, fully reviewed (PR #1278, closed unmerged, preserved on builder/spir-1252), and then deliberately declined at the pr gate on risk/reward: a successor project will first shrink the prompt surface radically (judgment-style rewrite, >50% reduction target, frontier-models-only), and enforcement should be rebuilt fit-for-purpose around the post-shrink surface rather than carried across it.

Pointers:

• Successor charter: issue Prompt surface: judgment-not-rules rewrite targeting >50% always-on reduction (frontier-model fleet) #1280 (radical prompt-surface shrink; carries forward the scar-registry concept, the eight ratified rule wordings, the ownership-map design, and this project's audit + baselines as its "before" measurement).
• Porch bug found during close-out: issue porch: .codev/config.json command override is silently ignored for forge-intercepted checks (pr_exists) #1282 (.codev/config.json porch.checks command override silently discarded for the forge-intercepted pr_exists check — checks.ts:262 intercepts after the override merge; only cwd/skip survive).
• Reference branch: builder/spir-1252 with PR [Spec 1252] Prompt architecture: single-owner rule across the prompt surface #1278 (closed unmerged) — the complete machinery and its review history.