From 5f696b25e1d3ea09ca89a33bc850d30165e11bca Mon Sep 17 00:00:00 2001 From: alex anikin <60673011+anikinsasha@users.noreply.github.com> Date: Sat, 25 Jul 2026 16:16:29 -0700 Subject: [PATCH] =?UTF-8?q?docs(isa):=20sanction=20a=20remaining-work=20se?= =?UTF-8?q?ction=20=E2=80=94=20recording=20an=20item=20there=20is=20a=20co?= =?UTF-8?q?mplete=20disposition?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ISA format specifies fourteen sections and none of them holds future work. So an ISA that finishes a phase with known remaining items has nowhere sanctioned to put them: it invents a per-instance heading no reader can rely on, or the item leaves the artifact and becomes a card. The second path is the expensive one — it turns "I noticed something" into "I must file, title, tag and route a card," and a system that charges that much for noticing gets fewer things noticed. Adds section 15, '## Remaining Work' (after Verification), with two semantics: 1. Recording an item there is a COMPLETE disposition. No card, issue, or tracker row is also required. A format that accepts the line and still demands a card has not removed any work — it has added a section. 2. An ISA's backlog is the UNION of its unchecked ISCs and its unchecked Remaining Work items, so 'what does this still owe' is computable from the artifact alone. Unchecked ISCs stay in Criteria — the ID-Stability Rule forbids moving them, and a criterion that migrates into a prose list stops being a criterion. Companion doctrine, the hand-off test, decides the exceptions: another tree, blocked on someone else, or picked up on its own schedule earns a card; everything else — and anything you are unsure about — is an ISA line. The asymmetry is deliberate. A line that should have been a card is still found by anyone reading the ISA; a card that should have been a line is a permanent tax on a thought. Also states the distinction the section makes possible: deferred is not dropped. A dropped criterion is a tombstone under the ID-Stability Rule; a deferred item is a live Remaining Work line. And a closing gate: an ISA reaching phase: complete with unchecked ISCs must tombstone them or account for them here, so silent abandonment stops being expressible. Conditional-required at E4/E5 on the same pattern as Dependencies and Bridge Criteria — mandatory when the ISA closes owing work, omitted when it owes none. Drive-by in the same sentence: the Body Sections lead-in still said 'Twelve sections in fixed order' after v2.13.0 took the body to fourteen. No Algorithm change. --- .../LIFEOS/DOCUMENTATION/Isa/IsaFormat.md | 82 +++++++++++++++++-- 1 file changed, 76 insertions(+), 6 deletions(-) diff --git a/LifeOS/install/LIFEOS/DOCUMENTATION/Isa/IsaFormat.md b/LifeOS/install/LIFEOS/DOCUMENTATION/Isa/IsaFormat.md index f358bb4aba..6569e15f8d 100644 --- a/LifeOS/install/LIFEOS/DOCUMENTATION/Isa/IsaFormat.md +++ b/LifeOS/install/LIFEOS/DOCUMENTATION/Isa/IsaFormat.md @@ -2,7 +2,9 @@ version: 1.5.19 --- -# LifeOS ISA Format Specification v2.13.0 (Algorithm v6.25.0) +# LifeOS ISA Format Specification v2.14.0 (Algorithm v6.25.0) + +> **v2.14.0 — a sanctioned home for remaining work.** The body grows from fourteen sections to **fifteen**: `## Remaining Work` (after Verification) holds the work an ISA knows about and is not doing in this run, one checkbox line each. Two semantics carry the section. First, **recording an item there is a complete disposition** — it does not also require a card or a tracker row. Second, an ISA's backlog is the **union** of its unchecked ISCs and its unchecked Remaining Work items, so "what does this still owe" is computable from the artifact alone. Companion doctrine: the **hand-off test** decides the exceptions — another tree, blocked on someone else, or picked up on its own schedule earns a card; everything else, and anything you are unsure about, is an ISA line. Conditional-required at E4/E5: mandatory when the ISA reaches `phase: complete` owing work, omitted when it owes none. **No Algorithm change** — this is a format addition; the parenthetical pairing above is unchanged from v2.13.0. > **v2.13.0 (Algorithm v6.25.0) — ISA scale + a real deletion.** The body grows from twelve sections to **fourteen**: `## Dependencies` (after Constraints) declares cross-ISA needs machine-readably; `## Bridge Criteria` (after Criteria) holds cross-ISA integration ISCs verified at VERIFY across the seam. New optional frontmatter `parent:` / `children:` links ISAs into a tree with **constraint inheritance** (a child cannot violate an ancestor Constraint). **The hard numeric ISC count floors (≥16/≥32/≥128/≥256) are DELETED** and replaced by the **Coverage Gate** — every subsystem named in Vision/Goal has a container ISC decomposed via the Splitting Test to single-probe leaves; coverage is the gate, count never is. Full doctrine in Algorithm v6.25.0 § *ISA Hierarchy & Cross-ISA Integration* and § *ISC Quality System*. The harness executor (`isa run`, reads `## Test Strategy`) is the paired build, tracked separately. @@ -288,7 +290,7 @@ algorithm_config: ## Body Sections (v2.7) -**Twelve sections in fixed order.** Each appears only when populated — never create empty placeholder sections (Bitter Pill discipline preserved). The Tier Completeness Gate determines which sections are required at which effort tier. +**Fifteen sections in fixed order.** Each appears only when populated — never create empty placeholder sections (Bitter Pill discipline preserved). The Tier Completeness Gate determines which sections are required at which effort tier. | # | Section | Purpose | Written At | |---|---------|---------|------------| @@ -306,8 +308,9 @@ algorithm_config: | 12 | `## Decisions` | Timestamped log including dead ends; `refined:` prefix | any phase | | 13 | `## Changelog` | Conjecture / refuted-by / learned / criterion-now entries | LEARN | | 14 | `## Verification` | Evidence per ISC (leaf + bridge) | VERIFY | +| 15 | `## Remaining Work` | **NEW v2.14.0** — work this ISA knows about and is not doing in this run, one checkbox line each. Recording an item here is a **complete disposition**. Omit when the ISA closes owing nothing. | VERIFY → LEARN | -(Optimize mode adds `## Experiments` between Test Strategy and Features. `## Dependencies` and `## Bridge Criteria` appear only when the ISA participates in a hierarchy — a single-ISA task omits both, exactly like any other empty section.) +(Optimize mode adds `## Experiments` between Test Strategy and Features. `## Dependencies` and `## Bridge Criteria` appear only when the ISA participates in a hierarchy — a single-ISA task omits both, exactly like any other empty section. `## Remaining Work` appears only when the ISA closes owing something.) ### Tier Completeness Gate (HARD at every tier, NEW v2.7) @@ -316,10 +319,10 @@ algorithm_config: | **E1** | Goal, Criteria | | **E2** | Problem, Goal, Criteria, Test Strategy | | **E3** | Problem, Vision, Out of Scope, Constraints, Goal, Criteria, Features, Test Strategy | -| **E4** | All fourteen* | -| **E5** | All fourteen* + active Interview workflow run before BUILD | +| **E4** | All fifteen* | +| **E5** | All fifteen* + active Interview workflow run before BUILD | -\* `## Dependencies` and `## Bridge Criteria` are **conditional-required**: mandatory when the ISA has any `parent:`/`children:`/cross-ISA relationship, omitted (like any empty section) for a standalone single-ISA task. A hierarchical ISA that omits them fails the gate; a standalone one that omits them passes. +\* `## Dependencies`, `## Bridge Criteria`, and `## Remaining Work` are **conditional-required**: the first two are mandatory when the ISA has any `parent:`/`children:`/cross-ISA relationship, omitted (like any empty section) for a standalone single-ISA task; `## Remaining Work` is mandatory when the ISA reaches `phase: complete` owing work, omitted when it owes none. An ISA that omits a section its condition demands fails the gate; one whose condition doesn't apply passes. Project ISA override: any `/ISA.md` requires E3+ structure regardless of task tier. Enforced by `Skill("ISA", "check completeness")`. @@ -511,6 +514,73 @@ Evidence for each criterion. Written during VERIFY phase. - ISC-3: Confirmed no PII in output via rg ``` +### ## Remaining Work (NEW v2.14.0) + +Work this ISA knows about and is **not** doing in this run. Written at VERIFY, finalized at LEARN. + +Every ISA that runs long enough discovers work it will not finish. Before v2.14.0 the format had +no place to put it: fourteen sections, none of which holds future work. So it went into a +per-instance invented heading that no reader — human or machine — could rely on, or it left the +ISA entirely and became a task in whatever tracker the principal runs. The second path is worse +than it looks: it turns "I noticed something" into "I must now file, title, tag, and route a +card," and a system that charges that much for noticing gets fewer things noticed. + +```markdown +## Remaining Work + +- [ ] Digest section for stale ISAs — deferred, the digest module is mid-refactor in another run. +- [ ] Property tests for the merge function — ISC-7 covers it by example; universal form is owed. +- [ ] Upstream PR for the section spec — gated on the principal ratifying the built design. +``` + +**An item recorded here is completely dispositioned.** It does not also require a card, an issue, +or a row in a tracker. This is the whole point of the section: one line, written where the context +already is, is a *sufficient* answer to "what about X?" A format that accepts the line and still +demands a card has not removed any work — it has added a section. + +**Backlog is the union of two things**, and a reader computing "what does this ISA still owe" +must take both: + +1. unchecked ISCs in `## Criteria` (and `## Bridge Criteria`), and +2. unchecked items in `## Remaining Work`. + +Unchecked ISCs stay where they are — the ID-Stability Rule forbids moving or renumbering them, and +a criterion that migrates into a prose list stops being a criterion. `## Remaining Work` is for +work that was never an ISC of this run. + +**Deferred is not dropped.** A dropped criterion becomes a tombstone under the ID-Stability Rule +(`- [ ] ISC-N: [DROPPED — see Decisions]`) and the reason goes in `## Decisions`. A deferred item +becomes a `## Remaining Work` line and stays live. The distinction is whether anyone still intends +to do it. + +**Closing gate.** An ISA reaching `phase: complete` with unchecked ISCs must either tombstone them +or account for them here. Silent abandonment — a complete ISA with unexplained empty checkboxes — +is the failure this section exists to make impossible. + +#### When an item needs a card instead + +`## Remaining Work` is the default home. An item earns its own card, issue, or tracker row only +when it fails the **hand-off test** — when it is genuinely someone or something else's to pick up: + +- it belongs to **another tree** (a different repo, project, or subsystem); +- it is **blocked on someone else** — an external dependency, another person, another run; +- it will be **picked up on its own schedule**, not as part of this work. + +Otherwise it is an ISA line. **When unsure, it is an ISA line** — the asymmetry is deliberate: a +line that should have been a card is found by anyone reading the ISA, while a card that should +have been a line is a permanent tax on a thought. + +When an item does earn a card, the `## Remaining Work` line stays and names it, so the ISA remains +a complete account of what it owes: + +```markdown +- [ ] Migrate the legacy importer — owned by the data-platform repo, tracked as #4127. +``` + +This is the companion half of the doctrine. The section without the hand-off test yields ISAs that +quietly absorb work belonging to other trees; the hand-off test without the section yields a card +for every stray thought. Neither is useful alone. + ## File Location ```