[W3.1] 12-factor-agent umbrella Tier U + token-economics canonical home

[julianken]

Action ID

W3.1 · Wave 3 · Tier U · Type: satellite_authoring · Estimated: 6h

Scope

Single-file edit; ~700w; openingFraming + 22 umbrellaPointers + closingRule (token-economics meta-rule verbatim, canonical home).

Rationale

Tier U distinctiveness rests on hosting the meta-rule per Risk 7: closingRule = 'If a rule has a trigger, it belongs in a skill, not here.' All sibling satellites quote-and-link rather than duplicate. 22 umbrella pointers (≥10 required by validation; aim for all 22).

Files touched

• /Users/jul/repos/detached-node/src/data/agentic-design-patterns/patterns/12-factor-agent.ts
• /Users/jul/repos/detached-node/src/data/agentic-design-patterns/patterns/memory-management.ts (additive: resolve W1.4's omitted forward-reference)
• /Users/jul/repos/detached-node/src/data/agentic-design-patterns/patterns/context-engineering.ts (additive: resolve W1.2's omitted forward-reference)

Acceptance criteria

• pnpm test passes (Vitest validates Tier U: openingFraming non-empty + umbrellaPointers.length >= 10 + closingRule non-empty + all umbrellaPointers[].patternSlug resolve)
• tier: 'U' set
• openingFraming ~100w names 12-factor as the umbrella whose factors are realized by sibling patterns
• umbrellaPointers contains 22 rows; each row: patternSlug + oneLine ≤20 words framing pattern as a 12-factor factor
• closingRule contains the user-CLAUDE.md token-economics meta-rule verbatim: 'If a rule has a trigger (when X, each time X, before/after X), it belongs in a skill, not here.'
• Additive edits to memory-management.ts + context-engineering.ts resolve their forward-references to closingRule
• TOOL-2 (scripts/check_meta_rule_consistency.sh) passes: meta-rule byte-identical across 12-factor-agent.ts, memory-management.ts, context-engineering.ts
• Word count 600-800 (Tier U)
• No readerMove field (Tier U schema omits readerMove)

Prerequisites

• W1.4
• W1.2
• W2.1
• W2.2
• W2.4
• W2.5
• W2.6
• W2.7
• [TOOL-2] Tooling: scripts/check_meta_rule_consistency.sh #328 (TOOL-2 — scripts/check_meta_rule_consistency.sh script existence)

Blocks

(none)

Rollback plan

Revert PR. Additive edits revertible alongside.

Anti-example evidence (if applicable)

(none)

---

Tracked in: Epic #302
Source: docs/agentic-bridge/reframe/action-plan-v1.json action W3.1

---

Cycle-2 addendum (2026-05-05)

Cycle-1 finding (#issuecomment-4378408980):

• Tier U schema additions are gated on W1.0 ([W1.0] Add realizingInClaudeCode to Pattern type + RealizingDisclosure component + Vitest validator #307). The Pattern type must add umbrellaPointers, openingFraming, closingRule fields before W3.1 can execute. Add to W1.0's scope OR add as W3.1 prerequisite work. Resolution: include Tier U fields in W1.0's Pattern type extension (already prerequisite); see updated W1.0 acceptance criteria.
• TOOL-2 script (scripts/check_meta_rule_consistency.sh) doesn't yet exist. The criterion in W3.1 referencing TOOL-2 should depend on [TOOL-2] Tooling: scripts/check_meta_rule_consistency.sh #328 (TOOL-2 issue) merging first. Updated prerequisites: add #328 to prereqs.

---

Tier U field availability (cycle-2)

Tier U fields (umbrellaPointers, openingFraming, closingRule) are explicitly enumerated in the W1.0 (#307) issue body's sub-field enumeration section. The Vitest validator from #307 enforces these required fields for tier:U patterns.

[julianken]

Review verdict: APPROVED

One non-blocking ambiguity worth resolving before execution:

• SUGGESTION — "verbatim" vs the quoted closingRule text. The rationale says "token-economics meta-rule verbatim, canonical home", and AC quotes 'If a rule has a trigger (when X, each time X, before/after X), it belongs in a skill, not here.' The user-level ~/.claude/CLAUDE.md actually phrases the trigger examples differently (e.g., "when adding screenshots", "before committing", "during PR review"). If "verbatim" means byte-identical to CLAUDE.md, the AC's quoted string is wrong; if the AC string is the new canonical phrasing for the pattern files, "verbatim" is the misleading word and the AC should say "as quoted above" instead. TOOL-2 (AC-7) only checks byte-identity across the three .ts files, so the issue is internally consistent either way — but the implementer shouldn't have to guess which source-of-truth wins. Pick one phrasing in the issue body before starting.

Otherwise: AC are objectively verifiable (pnpm test thresholds, tier flag, word count band, TOOL-2 byte-identity), scope is bounded (one primary file + two additive forward-reference resolutions), prerequisites correctly include W1.4 and W1.2 whose forward-references this resolves plus the W2.x sibling satellites the umbrellaPointers will reference, labels (wave:3 + tier:U) match, no [draft], no authorship framing, body ~270 words.

-- julianken-bot

[julianken]

Review verdict: NEEDS_CHANGES

IMPORTANT: TOOL-2 script not yet created; acceptance criterion is unverifiable as stated.

The acceptance criterion TOOL-2 (scripts/check_meta_rule_consistency.sh) passes names a script that does not exist at /Users/jul/repos/detached-node/scripts/check_meta_rule_consistency.sh (verified by ls — only check-affiliate-links.ts and typecheck-sketches.ts are present). The issue treats TOOL-2 as a gate the implementer runs, but there is no owner for creating it. Either the issue should name who creates it (a prerequisite issue or a deliverable within W3.1 itself), or the criterion should be rewritten as a manual byte-identical grep check until the script exists. Blocking because a criterion that references a non-existent tool cannot be objectively verified at PR review time.

IMPORTANT: Tier U schema fields absent from Pattern type and Vitest suite; "pnpm test passes" criterion is vacuously true today.

src/data/agentic-design-patterns/types.ts has no umbrellaPointers, openingFraming, closingRule, or tier fields (verified by reading the file end-to-end). The Vitest file at tests/unit/lib/schema/agentic-patterns.test.ts tests only JSON-LD schema generation and has zero assertions on Tier U shape. This means the pnpm test passes criterion passes vacuously right now and will pass vacuously after W3.1 if no test is added. W1.0 (issue #307) adds realizingInClaudeCode to the type + validator — Tier U needs the same pattern. The issue should either (a) make a type + test addition an explicit deliverable of W3.1, or (b) add a prerequisite issue that creates the Tier U validator before W3.1 executes. As written the criterion gives false confidence.

-- julianken-bot

[julianken]

Review verdict (cycle 2): NEEDS_CHANGES

IMPORTANT: #328 not added to prerequisites section.

The Cycle-2 addendum states "Updated prerequisites: add #328 to prereqs" but the issue body's Prerequisites section still lists only W1.4, W1.2, W2.1, W2.2, W2.4, W2.5, W2.6, W2.7. #328 is absent. The addendum documented intent but the body was never edited. The TOOL-2 gate criterion (scripts/check_meta_rule_consistency.sh must pass) is unverifiable until #328 merges; without #328 in prerequisites the ordering is not enforced and an implementer can start W3.1, hit the TOOL-2 AC, and have no script to run. Requires a body edit to add #328 before this issue is actionable.

IMPORTANT: openingFraming and closingRule absent from W1.0 (#307) scope.

The addendum claims the Cycle-1 IMPORTANT finding (Tier U schema fields gated on W1.0) is resolved by including them in W1.0's Pattern type extension. W1.0's "Files touched" names only CcWorkedExample, CcReaderMove, CcSeeAlso, CcUmbrellaPointer — neither openingFraming nor closingRule appears in W1.0's body or AC. src/data/agentic-design-patterns/types.ts today has neither field. The schema prerequisite is only half-resolved: umbrellaPointers has coverage (via CcUmbrellaPointer) but the other two Tier U fields are not named anywhere in W1.0's scope. Add explicit openingFraming: string and closingRule: string to W1.0's type list and Vitest AC, or open a dedicated prerequisite issue.

Cycle-1 SUGGESTION ("verbatim" vs quoted closingRule string) remains unresolved; still worth a one-line clarification before the implementer starts.

-- julianken-bot

[julianken]

Review verdict (cycle 3): APPROVED

Cycle-2 findings addressed.

• Prerequisites section now includes #328 (TOOL-2 — scripts/check_meta_rule_consistency.sh script existence) at the bottom of the prereq list. (Issue [W3.1] 12-factor-agent umbrella Tier U + token-economics canonical home #322 body, Prerequisites section, final bullet.)
• Tier U fields (umbrellaPointers, openingFraming, closingRule) are enumerated in W1.0 ([W1.0] Add realizingInClaudeCode to Pattern type + RealizingDisclosure component + Vitest validator #307) body's Sub-field enumeration section added 2026-05-05, lines 77-79 of the type definition block. The additional acceptance criterion in [W1.0] Add realizingInClaudeCode to Pattern type + RealizingDisclosure component + Vitest validator #307 also explicitly names all three Tier-U fields.
• Body word count: 419w (limit 800w). Within budget.

SUGGESTION (non-blocking): The two Cycle-2 addendum checkboxes (lines 56-57 in body) remain unchecked [ ] even though both findings are now resolved. Checking them would prevent implementers from mistaking them for open work items, but this is cosmetic — the resolution text immediately follows each checkbox.

-- julianken-bot