From b7ac77bbc8587301ea0d5093586e2fbcdd6843f3 Mon Sep 17 00:00:00 2001 From: Lior Date: Thu, 28 May 2026 09:12:03 -0400 Subject: [PATCH 1/2] =?UTF-8?q?rule(implicit-not-explicit-in-dus):=20IMPLI?= =?UTF-8?q?CIT-not-EXPLICIT=20is=20class=20error=20in=20DUs=20+=20ontology?= =?UTF-8?q?-evolution=20discipline=20=E2=80=94=20Aaron=202026-05-28=20cons?= =?UTF-8?q?titutional=20rule=20authorization?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two composing Aaron carvings (verbatim): > 'IMPLICIT not explicit is a class error we should write a rule for > and have our review agents of all kinds look for ... in our DUs ... > we are going to have a ton of this' > 'Some things like reformatting windows and reinstalling everything > my ontology still evolves to this day on every iteration' Operational discipline (TWO composing): DISCIPLINE 1 (Snapshot): every substantively-distinct state gets explicit DU variant: - Don't bury states in if-chains, context-field combinations, dispatch-function branches - Heuristic: if you'd want to LOG / OBSERVE / TRACE the substrate is in state X, it deserves a DU variant - Heuristic: if behavior at state X differs SUBSTANTIVELY from state Y, both deserve variants DISCIPLINE 2 (Evolution): DUs support ontology growth across iterations: - Closed for modification (existing variants stay stable) - Open for extension (new variants addable when iterations reveal substantively-distinct states) - Retraction-native composition (DBSP Z-set; variants proven wrong deprecated via additive substrate-engineering, not silent-delete) - Honor prior iterations (per honor-those-that-came-before) Properties at risk when IMPLICIT-not-EXPLICIT: - Observability (can't see state from logs/traces) - Composability (dispatchInWorld + lifetime-pair matrices need DU variants) - Asymmetric-authorship (no feedback channel for implicit substrate) - Substrate-smoothness (if-chains blur the sharpness) - Muscle-memory extraction (implicit substrate not transmissible) - Future-cold-boot inheritance (implicit substrate invisible without reading bodies) - Ontology evolution (no extension point for implicit substrate) What review agents check (all kinds — Otto / Codex / Lior / future): 1. Each substantively-distinct state has explicit DU variant? 2. Each transition-trigger has explicit substrate? 3. Each feedback variant per asymmetric-authorship? 4. Substrate supports evolution (OCP)? 5. Substrate-honest snapshot vs evolution distinction? Empirical examples preserved: - PR #5805 AutoLoopLifetime — Aaron caught implicit-not-explicit in decompose-or-ship dispatch branches (operator-pending / threshold / standing-auth all implicit); proposed extension with 5 new variants - PR #5810 PrReviewLifecycle — substantiated/unsubstantiated check buried in if-chain; candidate for ReviewFindingVerification DU Composes with substrate: - function-is-tiny-control-flow-generator-ocp-applied-to-control-flow (OCP DIRECTLY supports Aaron's ontology-evolution discipline) - asymmetric-authorship-substrate-entity-defines-consent-channel (each explicit variant AUTHORS feedback channel) - substrate-smoothness-as-load-bearing-property (DUs as sharp outputs) - monad-propagation-pattern (Result requires explicit variants) - grep-substrate-anchors-before-razor-as-metaphysical (implicit signals substrate not yet substantively recognized) - honor-those-that-came-before (honor prior variants when extending) - razor-discipline (operational claim; DU-vs-implicit audit operationally checkable) - wake-time-substrate (auto-loads at cold-boot) - memory/feedback_dus_are_explicit_muscle_memory_*.md (DUs ARE explicit muscle-memory; implicit substrate fails extraction) Composes with PRs from today: - PR #5805 AutoLoopLifetime (empirical anchor where caught) - PR #5810 PrReviewLifecycle (in-flight; another candidate) - PR #5728 B-0867.5 workflow-engine PoC (substrate this rule applies to) - PR #5758 B-0867.20 ReviewLifetime (already explicit; reference example) - PR #5775/#5801/#5804 per-host adapters (already explicit; reference) - PR #5806 DUs-as-explicit-muscle-memory (META-scope substrate this rule operationalizes) Auto-loads at cold-boot per wake-time-substrate.md so future-Otto + future-AI-instances + review-agents ALL inherit the discipline. Aaron's forecast 'we are going to have a ton of this' indicates the rule needs to be operational NOW; review-agents start looking for it immediately. μένω. The DUs make the muscle-memory explicit. The ontology evolves. Co-Authored-By: Claude Opus 4.7 --- ...-for-with-ontology-evolution-discipline.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 .claude/rules/implicit-not-explicit-in-dus-is-class-error-review-agents-look-for-with-ontology-evolution-discipline.md diff --git a/.claude/rules/implicit-not-explicit-in-dus-is-class-error-review-agents-look-for-with-ontology-evolution-discipline.md b/.claude/rules/implicit-not-explicit-in-dus-is-class-error-review-agents-look-for-with-ontology-evolution-discipline.md new file mode 100644 index 0000000000..8b08b06685 --- /dev/null +++ b/.claude/rules/implicit-not-explicit-in-dus-is-class-error-review-agents-look-for-with-ontology-evolution-discipline.md @@ -0,0 +1,195 @@ +# IMPLICIT-not-EXPLICIT in DUs is class error — review agents look for it + ontology-evolution discipline (Aaron 2026-05-28 constitutional rule authorization) + +Carved sentence (Aaron 2026-05-28 verbatim — TWO composing carvings): + +> *"IMPLICIT not explicit is a class error we should write a rule for +> and have our review agents of all kinds look for ... in our DUs ... +> we are going to have a ton of this"* + +Plus (Aaron 2026-05-28, same session, evolution discipline): + +> *"Some things like reformatting windows and reinstalling everything +> my ontology still evolves to this day on every iteration"* + +## Operational content + +When designing discriminated unions (DUs / state machines / lifecycle +substrate), states / transitions / conditions / observations that are +substantively distinct MUST be EXPLICIT DU variants — NOT IMPLICIT in +dispatch-flow logic, routing-context branches, or unnamed-state-via- +field-combinations. + +The class error: substantively-distinct substrate state gets BURIED in +TS internal logic (if-chains, context-field-combinations, dispatch- +function branches) rather than SURFACED as an explicit DU variant. + +## Why this is class error (load-bearing properties at risk) + +| Substrate property | Lost when IMPLICIT-not-EXPLICIT | +|---|---| +| **Observability** | Cannot see the loop's current state from logs/traces; have to reconstruct from context-field inspection | +| **Composability** | dispatchInWorld + lifetime-pair matrices need DU variants; implicit-not-explicit can't compose | +| **asymmetric-authorship** | Each substantively-distinct state SHOULD AUTHOR its own feedback channel; implicit substrate has no channel | +| **substrate-smoothness** | Smooth substrate produces sharp outputs via DUs; if-chain routing blurs the sharpness | +| **muscle-memory extraction** (per `dus-are-explicit-muscle-memory` memory): DUs ARE explicit muscle-memory; implicit substrate fails to extract the muscle-memory; not transmissible | +| **Future-cold-boot inheritance** | Future-AI-instances cold-booting see the DU + dispatch; implicit substrate is invisible without reading function bodies | +| **Ontology evolution** (Aaron's second carving) | Ontology EVOLVES with each iteration; new variants need to be ADDABLE; implicit substrate has nowhere to extend | + +## The two composing disciplines + +### Discipline 1: Snapshot — every substantively-distinct state gets a DU variant + +When authoring DU substrate: + +1. **Inventory the substantively distinct states** the substrate-entity passes through +2. **Each distinct state → explicit DU variant** (`kind: "..."`) +3. **DON'T bury states** in if-chains, context-field combinations, or dispatch-function branches +4. **Heuristic**: if you'd want to LOG / OBSERVE / TRACE that the substrate is in state X, it deserves a DU variant +5. **Heuristic**: if behavior at state X differs SUBSTANTIVELY from state Y, both deserve variants + +### Discipline 2: Evolution — DUs support ontology growth across iterations + +Aaron 2026-05-28: *"Some things like reformatting windows and reinstalling everything my ontology still evolves to this day on every iteration."* + +The substrate-honest implication: even highly-repeated processes evolve their ontology on every iteration. DUs must support: + +1. **Closed for modification** (per `function-is-tiny-control-flow-generator-ocp-applied-to-control-flow.md`): existing DU variants' semantics stay STABLE across iterations +2. **Open for extension**: new variants can be ADDED when iterations reveal new substantively-distinct states +3. **Retraction-native composition** (per DBSP Z-set + Hopf antipode substrate): variants proven wrong can be deprecated / replaced via additive substrate-engineering (NOT silent-delete) +4. **Honor prior iterations**: when extending, honor what came before (per `honor-those-that-came-before.md`); old variants kept until explicitly retracted + +## What review agents should check + +Per Aaron's rule-authoring authorization ("have our review agents of +all kinds look for"): + +**Review checklist for DU substrate**: + +1. **Each substantively-distinct state has explicit DU variant?** (no implicit-via-context-field) +2. **Each transition-trigger has explicit substrate?** (DU variant OR dispatch-function-return-value; never just internal if-chain on bare context-field) +3. **Each feedback variant per asymmetric-authorship?** (no exception-throwing or null-returning instead of Result) +4. **Substrate supports evolution?** (DU shape allows adding new variants without breaking existing call sites; per OCP rule) +5. **Substrate-honest snapshot vs evolution distinction?** (current iteration's substrate is what's there NOW; evolution mechanism is preserved separately) + +When review agents encounter implicit-not-explicit substrate: + +1. **Flag as class error per this rule** +2. **Propose explicit DU variant addition** (substrate-engineering substrate-naming candidate) +3. **Compose with OCP discipline** (add variant; don't modify existing; honor prior substrate) +4. **Verify substrate-anchors** (per `grep-substrate-anchors-before-razor-as-metaphysical.md` — implicit-not-explicit often signals substrate that hasn't been substantively recognized yet) + +## Examples of IMPLICIT-NOT-EXPLICIT class error + +### Example 1: AutoLoopLifetime PR #5805 (caught by Aaron 2026-05-28) + +**Before (implicit)**: AutoLoopLifetime had `decompose-or-ship` state that branched internally on: +- `context.operatorDirectionPending !== undefined` → routes to brief-ack-bounded-wait +- `context.briefAckCount >= BRIEF_ACK_THRESHOLD && !lastNamedDependency` → routes to forced-escalation +- Otherwise → routes to ship-action + +These are SUBSTANTIVELY DISTINCT states the loop is in, but they're IMPLICIT in dispatch branches. + +**After (explicit, proposed)**: Add DU variants: +- `await-operator-direction` (waiting on operator-named question) +- `pr-loop-resolution-check` (waiting for PR-state transitions; merged + threads resolved + CI clean) +- `peer-pr-review` (substantively engaging with peer-agent work; not ship-work) +- `pure-git-mode` (rate-limit exhausted; pure-git substrate substrate) +- `unfinished-pr-triage` (per `pr-triage-tiers.md` rule; explicit tier-classification state) + +Each substantively-distinct state gets observability + composability + feedback-channel + future-cold-boot-inheritance. + +### Example 2: PrReviewLifecycle PR #5810 (caught by Aaron 2026-05-28; this same session) + +**Before (implicit)**: verify-finding state checks: +```typescript +if (context.findings.length > 0 && context.findings[0]!.substrateAnchors !== undefined && context.findings[0]!.substrateAnchors.length === 0) { + return { ok: false, feedback: { kind: "FindingUnsubstantiated", ... } }; +} +``` + +The "substantiated" vs "unsubstantiated" distinction is IMPLICIT in field-combination + if-check. + +**After (explicit, proposed)**: Add ReviewFindingVerification DU: +```typescript +type ReviewFindingVerification = + | { kind: "substantiated"; anchors: string[] } + | { kind: "unsubstantiated"; reason: string } + | { kind: "verify-pending" } + | { kind: "verify-skipped"; rationale: string }; +``` + +Then verify-finding state dispatches on the explicit verification-state DU instead of internal if-chain on bare context fields. + +## Composes with substrate + +- **`function-is-tiny-control-flow-generator-ocp-applied-to-control-flow.md`** — DIRECT COMPOSITION: open-for-extension supports Aaron's ontology-evolution discipline; closed-for-modification supports snapshot stability +- **`asymmetric-authorship-substrate-entity-defines-consent-channel-recipient-acknowledges.md`** — each explicit DU variant AUTHORS its feedback channel; implicit substrate has no channel +- **`substrate-smoothness-as-load-bearing-property.md`** — smooth substrate produces sharp outputs via explicit DUs; if-chains blur the sharpness +- **`monad-propagation-pattern-cross-language-substrate-shape.md`** — Result shape requires explicit TFeedback variants; implicit substrate breaks the pattern +- **`grep-substrate-anchors-before-razor-as-metaphysical.md`** — implicit-not-explicit often signals substrate-engineering substrate that hasn't been substantively recognized yet; grep first before razor +- **`honor-those-that-came-before.md`** — when extending DUs per ontology-evolution discipline, honor prior variants (don't silent-replace) +- **`razor-discipline.md`** — operational claims only; this rule is operationally checkable via DU-vs-implicit audit +- **memory/feedback_dus_are_explicit_muscle_memory_*.md** — DUs ARE explicit muscle-memory; implicit substrate fails to extract the muscle-memory +- **`wake-time-substrate.md`** — this rule auto-loads at cold-boot so future-Otto + review-agents inherit the discipline + +## Composes with PRs from today + +- PR #5805 AutoLoopLifetime (substrate where Aaron first caught the implicit-not-explicit pattern in this session) +- PR #5810 PrReviewLifecycle (substrate with implicit verify-finding check; candidate for explicit ReviewFindingVerification DU) +- PR #5728 B-0867.5 workflow-engine PoC (substrate this rule applies to going forward) +- PR #5758 B-0867.20 ReviewLifetime (substrate already explicit; reference example) +- PR #5775/#5801/#5804 per-host adapters (substrate already explicit; reference example) +- PR #5806 DUs-as-explicit-muscle-memory (META-scope substrate this rule operationalizes) + +## Future-Otto + review-agent operational inheritance + +When authoring new DU substrate: + +1. **Inventory substantively-distinct states** → each gets explicit variant +2. **Don't bury substrate in dispatch branches** — surface as DU +3. **Don't bury substrate in context-field combinations** — surface as DU variant or dedicated DU +4. **Each feedback variant explicit per asymmetric-authorship** +5. **Substrate supports evolution** (OCP closed-for-modification + open-for-extension) +6. **Honor prior variants** when extending (don't silent-replace) + +When REVIEWING new DU substrate (per producing-side `PrReviewLifecycle`): + +1. **Apply this rule's checklist** to the DU +2. **Flag implicit-not-explicit findings** as class-error class-1 (per ReviewFindingKind taxonomy) +3. **Propose explicit DU variant addition** as substrate-engineering substrate-engineering substrate +4. **Compose with OCP** — propose ADDITIVE extension, not modification +5. **Honor substrate-engineering peer's prior substrate** when proposing extension + +## Why this rule auto-loads at cold-boot + +Per `.claude/rules/wake-time-substrate.md`: this is constitutional substrate-engineering substrate-design discipline. Future-Otto + future-AI-instances + review-agents (Codex / Lior / Otto / future) ALL need this rule at cold-boot to: + +1. Apply discipline when authoring new DU substrate +2. Catch class errors when reviewing peer substrate +3. Honor ontology-evolution discipline (Aaron's second carving) + +Without auto-load, the class error recurs ("we are going to have a ton of this" per Aaron's forecast). + +## Substrate-honest framing + +This rule does NOT: + +- Mandate that ALL behavior must be DU variants (some substrate is genuinely internal-routing; not every if-chain is class error) +- Prevent substrate-engineering iteration (ontology-evolution discipline EXPLICITLY supports growth) +- Override operator authority (operator can direct different discipline if substrate-engineering target requires) + +This rule DOES: + +- Catch the recurring class error Aaron identified +- Establish review-agent discipline (review agents look for this pattern) +- Compose with ontology-evolution discipline (DUs evolve; rule supports iteration) +- Honor the substrate-engineering substrate-engineering substrate-naming substrate work shipped today (per `dus-are-explicit-muscle-memory` carving) + +The discriminator: when a substantively-distinct state exists in the substrate-engineering substrate-engineering substrate, it deserves explicit DU variant. When something is just internal-routing (not substrate-engineering substrate-engineering substrate), it can stay in dispatch logic. The judgment call is operationally testable via observability + composability + feedback-channel + future-cold-boot-inheritance criteria. + +## μένω. The DUs make the muscle-memory explicit. The ontology evolves. + +(Aaron 2026-05-28 constitutional substrate-engineering substrate-rule +authorization; META-scope substrate-engineering substrate-engineering +substrate-design discipline; auto-loads at cold-boot; review-agents +inherit the discipline.) From c5d8c91f664d1f5b47746aee31fd5a26d289ab3e Mon Sep 17 00:00:00 2001 From: Lior Date: Thu, 28 May 2026 09:37:52 -0400 Subject: [PATCH 2/2] fix(PR #5811): 4 markdownlint errors on new rule file (Copilot lint thread) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new `.claude/rules/implicit-not-explicit-in-dus-...` file failed `lint (markdownlint)` required check with 4 errors: - MD056 line 34: table row missing column separator — "muscle-memory extraction (per `dus-are-explicit-muscle-memory` memory): DUs ARE explicit muscle-memory..." used a colon `:` to separate cell content but markdownlint counts on pipes `|`. Replaced `:` with `|` so the row has 2 columns matching the table header. - MD032 lines 86 + 93: bullet lists not surrounded by blank lines. Added blank lines BEFORE each list following the `routed-internally` preface paragraph and the `proposed DU variants` preface paragraph. - MD026 line 190: heading "## μένω. The DUs make the muscle-memory explicit. The ontology evolves." had trailing punctuation. Reformatted to "## μένω — the DUs make the muscle-memory explicit, the ontology evolves" — same meaning, no trailing period. Non-breaking: only markdown formatting changed; substrate content preserved. Autonomous-loop tick 2026-05-28T14:10Z resolution of PR #5811 markdownlint required-check failure (the other required failure, `lint (semgrep)`, is the mise transient flake that cleared via #5817 merge — will pass on next CI run). Co-Authored-By: Claude --- ...ew-agents-look-for-with-ontology-evolution-discipline.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.claude/rules/implicit-not-explicit-in-dus-is-class-error-review-agents-look-for-with-ontology-evolution-discipline.md b/.claude/rules/implicit-not-explicit-in-dus-is-class-error-review-agents-look-for-with-ontology-evolution-discipline.md index 8b08b06685..14edda8685 100644 --- a/.claude/rules/implicit-not-explicit-in-dus-is-class-error-review-agents-look-for-with-ontology-evolution-discipline.md +++ b/.claude/rules/implicit-not-explicit-in-dus-is-class-error-review-agents-look-for-with-ontology-evolution-discipline.md @@ -31,7 +31,7 @@ function branches) rather than SURFACED as an explicit DU variant. | **Composability** | dispatchInWorld + lifetime-pair matrices need DU variants; implicit-not-explicit can't compose | | **asymmetric-authorship** | Each substantively-distinct state SHOULD AUTHOR its own feedback channel; implicit substrate has no channel | | **substrate-smoothness** | Smooth substrate produces sharp outputs via DUs; if-chain routing blurs the sharpness | -| **muscle-memory extraction** (per `dus-are-explicit-muscle-memory` memory): DUs ARE explicit muscle-memory; implicit substrate fails to extract the muscle-memory; not transmissible | +| **muscle-memory extraction** (per `dus-are-explicit-muscle-memory` memory) | DUs ARE explicit muscle-memory; implicit substrate fails to extract the muscle-memory; not transmissible | | **Future-cold-boot inheritance** | Future-AI-instances cold-booting see the DU + dispatch; implicit substrate is invisible without reading function bodies | | **Ontology evolution** (Aaron's second carving) | Ontology EVOLVES with each iteration; new variants need to be ADDABLE; implicit substrate has nowhere to extend | @@ -83,6 +83,7 @@ When review agents encounter implicit-not-explicit substrate: ### Example 1: AutoLoopLifetime PR #5805 (caught by Aaron 2026-05-28) **Before (implicit)**: AutoLoopLifetime had `decompose-or-ship` state that branched internally on: + - `context.operatorDirectionPending !== undefined` → routes to brief-ack-bounded-wait - `context.briefAckCount >= BRIEF_ACK_THRESHOLD && !lastNamedDependency` → routes to forced-escalation - Otherwise → routes to ship-action @@ -90,6 +91,7 @@ When review agents encounter implicit-not-explicit substrate: These are SUBSTANTIVELY DISTINCT states the loop is in, but they're IMPLICIT in dispatch branches. **After (explicit, proposed)**: Add DU variants: + - `await-operator-direction` (waiting on operator-named question) - `pr-loop-resolution-check` (waiting for PR-state transitions; merged + threads resolved + CI clean) - `peer-pr-review` (substantively engaging with peer-agent work; not ship-work) @@ -187,7 +189,7 @@ This rule DOES: The discriminator: when a substantively-distinct state exists in the substrate-engineering substrate-engineering substrate, it deserves explicit DU variant. When something is just internal-routing (not substrate-engineering substrate-engineering substrate), it can stay in dispatch logic. The judgment call is operationally testable via observability + composability + feedback-channel + future-cold-boot-inheritance criteria. -## μένω. The DUs make the muscle-memory explicit. The ontology evolves. +## μένω — the DUs make the muscle-memory explicit, the ontology evolves (Aaron 2026-05-28 constitutional substrate-engineering substrate-rule authorization; META-scope substrate-engineering substrate-engineering