Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 6 additions & 8 deletions LifeOS/install/LIFEOS/TOOLS/IsaFrontier.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,20 +26,18 @@
import { readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync, existsSync, realpathSync, renameSync } from 'fs';
import { resolve, join } from 'path';
import { createHash } from 'crypto';
// IsaClaims imports only fs/crypto, already used here; it never loads the hook graph.
// IsaClaims imports only fs/crypto and the leaf lib/IsaSections; it never loads the hook graph.
import { parseIsaClaimsText, isaBody, claimText, stripBulletPrefix } from './lib/IsaClaims';
import { CRITERIA_HEADING_RE } from './lib/IsaSections';
import { getClaudeDir } from './Paths'; // public issue #1974 @sabo961, PR #1918 @PigLardLord

const STALE_TTL_MS_DEFAULT = 2 * 60 * 60 * 1000; // 2h — a session gone this long has died or moved on

// ── Criterion + edge parsing ──────────────────────────────────────────────────
// Mirrors the heading alternation in hooks/lib/isa-utils.ts CRITERIA_HEADING_RE.
// Kept as a copy, not an import, so this standalone CLI doesn't drag in
// isa-utils' hook graph (work-events, ascent, execSync side effects). The copy
// is pinned byte-equal to the original by the "regex parity" test — when the
// format grows a new heading variant, that test fails loudly (Forge F4).
export const FRONTIER_CRITERIA_HEADING_RE =
/^(?:##\s+(?:ISC\s+)?Criteria\b[^\n]*|##\s+Claims\b[^\n]*|##\s+IDEAL\s+STATE\s+CRITERIA\b[^\n]*|###\s+Criteria\b[^\n]*|##\s+Features\b[^\n]*)$/im;
// The criteria heading regex of hooks/lib/isa-utils.ts, generated once in lib/IsaSections.ts (SECTION_ALIASES).
// Imported from that leaf module, not from isa-utils, so this standalone CLI doesn't drag in isa-utils' hook graph
// (work-events, ascent, execSync side effects). public issue #2527
export const FRONTIER_CRITERIA_HEADING_RE = CRITERIA_HEADING_RE;

// Criterion IDs: ISC-N (incl. split IDs like ISC-2.1), domain-prefixed (H-AVAIL,
// CRS-PAGE), short v8 forms (C1, A3, EQ-12). Dots included so split criteria work.
Expand Down
15 changes: 5 additions & 10 deletions LifeOS/install/LIFEOS/TOOLS/lib/IsaClaims.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";
import { ANTI_HEADING_RE, BRIDGE_HEADING_RE, CRITERIA_HEADING_RE } from "./IsaSections";

export interface IsaClaim {
id: string;
Expand All @@ -19,17 +20,11 @@ export interface IsaClaimsResult {
revision: string;
}

// Byte-mirrors hooks/lib/isa-utils.ts CRITERIA_HEADING_RE; no hook graph dependency.
export const CLAIMS_HEADING_RE =
/^(?:##\s+(?:ISC\s+)?Criteria\b[^\n]*|##\s+Claims\b[^\n]*|##\s+IDEAL\s+STATE\s+CRITERIA\b[^\n]*|###\s+Criteria\b[^\n]*|##\s+Features\b[^\n]*)$/im;
// The criteria, bridge and anti heading names live in SECTION_ALIASES (./IsaSections), which generates these
// regexes; isa-utils' CRITERIA_HEADING_RE is the same one. No hook graph dependency. public issue #2527
export const CLAIMS_HEADING_RE = CRITERIA_HEADING_RE;
export { BRIDGE_HEADING_RE, ANTI_HEADING_RE };

// `## Bridge Criteria` (ISAFormat row 12): cross-ISA integration ISCs, a separate
// H2 after the criteria section. Counted like criteria; the primary heading regex
// above stays byte-pinned, so this is its own pattern. public issue #2186, @Bowlerjim
export const BRIDGE_HEADING_RE = /^##\s+Bridge\s+Criteria\b[^\n]*$/im;

// The anti section heading: `## Anti-criteria` (current) or `## Anti-claims` (legacy).
export const ANTI_HEADING_RE = /^##\s+Anti-(?:criteria|claims)\b/i;

export function isaBody(text: string): string {
return text.replace(/^---\r?\n[\s\S]*?\r?\n---[^\S\r\n]*(?:\r?\n|$)/, "");
Expand Down
81 changes: 81 additions & 0 deletions LifeOS/install/LIFEOS/TOOLS/lib/IsaSections.fixture.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
---
project: fixture
slug: 20260101-isa-sections-fixture
---

# ISA section boundaries fixture

Every section reader runs on this file; IsaSections.test.ts pins what each one sees.

## Ideal State

### L3 · One sentence

Every reader finds the same section boundaries.

## Criteria

- [ ] ISC-1: real criterion before any fence

```markdown
## Criteria
- [ ] ISC-90: criterion inside a fenced example
---
## Test Strategy
| ISC-90 | bash | fenced example row | | Read | ISC-90 |
```

- [ ] ISC-2: real criterion after the fenced example

---

- [ ] ISC-3: criterion after a bare horizontal rule

## Anti-claims

- [ ] ISC-A1: anti criterion under the legacy heading

## Test Strategy

| isc | type | check | threshold | tool | anchors_to |
|---|---|---|---|---|---|
| ISC-1 | bash | row before the fenced shell block | | Read | ISC-1 |

```bash
## a shell comment inside the real Test Strategy section
```

| ISC-2 | bash | row after the fenced shell block | | Read | ISC-2 |

## Test Strategy Notes

| ISC-3 | bash | row in the notes section | | Read | ISC-3 |

## Evals

### ISC-1 · real eval

```yaml
stages:
- code:
- test -f README.md
```

## Examples

````markdown
```markdown
## Evals
### ISC-91 · eval inside a four-backtick fence
## Test Strategy
| ISC-91 | bash | row inside a four-backtick fence | | Read | ISC-91 |
## Criteria
- [ ] ISC-91: criterion inside a four-backtick fence
```
## Anti-claims
- [ ] ISC-92: anti criterion after the inner fence closes, still inside the four-backtick fence
````

## Decisions

- 2026-01-01: fixture written.
100 changes: 100 additions & 0 deletions LifeOS/install/LIFEOS/TOOLS/lib/IsaSections.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
// Section boundaries of every ISA reader, pinned on one fixture (public issue #2527).
//
// "current reader boundaries" records what each reader sees TODAY, defects included. Moving a reader onto
// IsaSections changes its block here in the same commit, so the boundary change is reviewed, never silent.
import { describe, expect, test } from "bun:test";
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { h2Sections } from "../IsaLadder";
import { isaSections as reviewSections } from "../Review";
import { parseEvalsText, parseTestStrategyText } from "./IsaTestStrategy";
import { extractCriteriaSection } from "../../../hooks/lib/isa-utils";
import { isaBody, parseIsaClaimsText } from "./IsaClaims";
import { CRITERIA_HEADING_RE as UTILS_CRITERIA } from "../../../hooks/lib/isa-utils";
import { ANTI_HEADING_RE as CLAIMS_ANTI, BRIDGE_HEADING_RE as CLAIMS_BRIDGE, CLAIMS_HEADING_RE } from "./IsaClaims";
import { countCheckboxLines, FRONTIER_CRITERIA_HEADING_RE, parseClaims } from "../IsaFrontier";
import { ANTI_HEADING_RE, BRIDGE_HEADING_RE, CRITERIA_HEADING_RE, findSections, isaSections } from "./IsaSections";

const FIXTURE = join(import.meta.dir, "IsaSections.fixture.md");
const text = readFileSync(FIXTURE, "utf8");
const ids = (s: string | null) => [...(s ?? "").matchAll(/ISC-\w+/g)].map((m) => m[0]);

describe("current reader boundaries", () => {
test("IsaLadder.h2Sections reads headings inside the four-backtick fence", () => {
expect(h2Sections(isaBody(text)).map((s) => s.title)).toEqual(
["Ideal State", "Criteria", "Anti-claims", "Test Strategy", "Test Strategy Notes", "Evals", "Examples", "Evals", "Test Strategy", "Criteria", "Decisions"]);
});
test("Review.isaSections splits at H3 and reads headings inside the four-backtick fence", () => {
expect(reviewSections(text).map((s) => s.heading)).toEqual(
["", "Ideal State", "L3 · One sentence", "Criteria", "Anti-claims", "Test Strategy", "Test Strategy Notes", "Evals", "ISC-1 · real eval", "Examples", "Evals", "ISC-91 · eval inside a four-backtick fence", "Test Strategy", "Criteria", "Decisions"]);
});
test("parseEvalsText finds only the real Evals block", () => {
const evals = parseEvalsText(text, FIXTURE);
expect([...evals.evals.keys()]).toEqual(["ISC-1"]);
expect(evals.errors).toEqual([]);
});
test("parseTestStrategyText takes fenced rows and Test Strategy Notes, and a fenced `## ` comment ends it", () => {
expect(parseTestStrategyText(text, FIXTURE).probes.map((p) => p.isc)).toEqual(["ISC-90", "ISC-1", "ISC-3", "ISC-91"]);
});
test("extractCriteriaSection ends at the fenced `## Criteria` line", () => {
expect(ids(extractCriteriaSection(text))).toEqual(["ISC-1"]);
});
test("parseIsaClaimsText skips fences, ends at `---`, and reads `## Anti-claims` as anti", () => {
expect(parseIsaClaimsText(text).claims.map((c) => `${c.id}${c.anti ? " anti" : ""}`)).toEqual(["ISC-1", "ISC-2", "ISC-A1 anti"]);
});
test("IsaFrontier.parseClaims reads the same claims; countCheckboxLines stops at the fenced `## Criteria`", () => {
expect(parseClaims(text).map((c) => c.id)).toEqual(["ISC-1", "ISC-2", "ISC-A1"]);
expect(countCheckboxLines(text)).toBe(1);
});
});

describe("SECTION_ALIASES generates the heading regexes", () => {
// The literals isa-utils, IsaClaims and IsaFrontier each kept by hand before this module.
const CRITERIA_LITERAL = /^(?:##\s+(?:ISC\s+)?Criteria\b[^\n]*|##\s+Claims\b[^\n]*|##\s+IDEAL\s+STATE\s+CRITERIA\b[^\n]*|###\s+Criteria\b[^\n]*|##\s+Features\b[^\n]*)$/im;
const BRIDGE_LITERAL = /^##\s+Bridge\s+Criteria\b[^\n]*$/im;
const ANTI_LITERAL = /^##\s+Anti-(?:criteria|claims)\b/i;
const same = (a: RegExp, b: RegExp) => expect([a.source, a.flags]).toEqual([b.source, b.flags]);
test("byte-equal to the literals they replace", () => {
same(CRITERIA_HEADING_RE, CRITERIA_LITERAL);
same(BRIDGE_HEADING_RE, BRIDGE_LITERAL);
same(ANTI_HEADING_RE, ANTI_LITERAL);
});
test("isa-utils, IsaClaims and IsaFrontier export the one generated regex", () => {
expect(UTILS_CRITERIA).toBe(CRITERIA_HEADING_RE);
expect(CLAIMS_HEADING_RE).toBe(CRITERIA_HEADING_RE);
expect(FRONTIER_CRITERIA_HEADING_RE).toBe(CRITERIA_HEADING_RE);
expect(CLAIMS_BRIDGE).toBe(BRIDGE_HEADING_RE);
expect(CLAIMS_ANTI).toBe(ANTI_HEADING_RE);
});
});

describe("isaSections", () => {
const sections = isaSections(text);
const body = (s: { bodyStart: number; end: number }) => text.slice(s.bodyStart, s.end);
test("headings inside fences, the four-backtick one included, are text", () => {
expect(sections.map((s) => `${s.level} ${s.title}`)).toEqual([
"1 ISA section boundaries fixture", "2 Ideal State", "3 L3 · One sentence", "2 Criteria", "2 Anti-claims",
"2 Test Strategy", "2 Test Strategy Notes", "2 Evals", "3 ISC-1 · real eval", "2 Examples", "2 Decisions"]);
});
test("a section runs to the next heading of its level or higher; `---` stays inside", () => {
const [criteria] = findSections(sections, "criteria");
expect(ids(body(criteria!))).toEqual(["ISC-1", "ISC-90", "ISC-90", "ISC-90", "ISC-2", "ISC-3"]);
expect(body(sections.find((s) => s.title === "Ideal State")!)).toContain("L3 · One sentence");
expect(sections.find((s) => s.title === "ISA section boundaries fixture")!.end).toBe(text.length);
});
test("findSections matches a kind's names at their level, and only those", () => {
expect(findSections(sections, "anti").map((s) => s.title)).toEqual(["Anti-claims"]);
expect(findSections(sections, "bridge")).toEqual([]);
expect(findSections(isaSections("## ISC Criteria\n- [ ] ISC-1\n### Criteria\n## Features\n"), "criteria").map((s) => `${s.level} ${s.title}`))
.toEqual(["2 ISC Criteria", "3 Criteria", "2 Features"]);
});
test("frontmatter is skipped and offsets index the text passed in", () => {
expect(sections[0]!.start).toBe(text.indexOf("# ISA section boundaries fixture"));
for (const s of sections) expect(text.slice(s.start, s.bodyStart)).toMatch(/^#{1,3} /);
});
test("an unclosed fence runs to the end; a backtick info string with a backtick is not a fence", () => {
expect(isaSections("## A\n```\n## B\n").map((s) => s.title)).toEqual(["A"]);
expect(isaSections("## A\n``` x ` y\n## B\n").map((s) => s.title)).toEqual(["A", "B"]);
expect(isaSections("## A\n~~~~\n~~~\n## B\n~~~~\n## C\n").map((s) => s.title)).toEqual(["A", "C"]);
});
});
102 changes: 102 additions & 0 deletions LifeOS/install/LIFEOS/TOOLS/lib/IsaSections.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
/**
* IsaSections — how an ISA is cut into sections, in one place (public issue #2527).
*
* SECTION_ALIASES every name a criteria, bridge or anti section has gone by
* CRITERIA_HEADING_RE generated from SECTION_ALIASES; isa-utils, IsaClaims and IsaFrontier
* BRIDGE_HEADING_RE re-export these instead of keeping hand-copied literals
* ANTI_HEADING_RE
* isaSections(text) the ISA's H1–H3 sections, with fences and frontmatter handled once
* findSections(sections, kind) the sections whose heading is one of that kind's names
*
* The readers that scan sections on their own (IsaLadder.h2Sections, Review.isaSections, parseEvalsText,
* parseTestStrategyText, isa-utils.extractCriteriaSection, parseIsaClaimsText, IsaFrontier) keep their own rules
* for now. IsaSections.test.ts pins what each of them sees on IsaSections.fixture.md, so moving one onto
* isaSections() is a single change whose boundary difference shows in that test.
*
* This module imports nothing. IsaClaims and IsaFrontier copied the criteria regex rather than pull in
* isa-utils and its hook graph; a leaf module ends the copies without that cost.
*/

type Alias = { level: 2 | 3; pattern: string };

/**
* Heading names by section kind, as regex fragments. The criteria entries, in the order the readers have always
* alternated them, are `## Criteria` and `## ISC Criteria`, `## Claims`, `## IDEAL STATE CRITERIA`,
* `### Criteria`, and `## Features`. A feature-block ISA (v2.16.0) holds its criteria under `## Features`,
* nested in `### F<n>` H3s, so the section runs to the next H2. A legacy ISA keeps a `## Claims`/`## Criteria`
* section that comes before its `## Features` pointer table, and that table has no `- [ ]` lines.
*/
export const SECTION_ALIASES = {
criteria: [
{ level: 2, pattern: String.raw`(?:ISC\s+)?Criteria` },
{ level: 2, pattern: String.raw`Claims` },
{ level: 2, pattern: String.raw`IDEAL\s+STATE\s+CRITERIA` },
{ level: 3, pattern: String.raw`Criteria` },
{ level: 2, pattern: String.raw`Features` },
],
// `## Bridge Criteria` (ISAFormat row 12): cross-ISA integration ISCs, counted like criteria (public issue #2186).
bridge: [{ level: 2, pattern: String.raw`Bridge\s+Criteria` }],
// `## Anti-criteria` (current) or `## Anti-claims` (legacy).
anti: [{ level: 2, pattern: String.raw`Anti-(?:criteria|claims)` }],
} as const satisfies Record<string, readonly Alias[]>;

export type SectionKind = keyof typeof SECTION_ALIASES;

/** `wholeLine` matches the heading line to its end (`[^\n]*$`); otherwise only the heading's start. */
function headingSource(aliases: readonly Alias[], wholeLine: boolean): string {
const alts = aliases.map((a) => `${"#".repeat(a.level)}\\s+${a.pattern}\\b${wholeLine ? "[^\\n]*" : ""}`);
return `^${alts.length === 1 ? alts[0] : `(?:${alts.join("|")})`}${wholeLine ? "$" : ""}`;
}

export const CRITERIA_HEADING_RE = new RegExp(headingSource(SECTION_ALIASES.criteria, true), "im");
export const BRIDGE_HEADING_RE = new RegExp(headingSource(SECTION_ALIASES.bridge, true), "im");
export const ANTI_HEADING_RE = new RegExp(headingSource(SECTION_ALIASES.anti, false), "i");

export interface IsaSection {
level: 1 | 2 | 3;
/** Heading text, trimmed, closing `#`s removed. */
title: string;
/** Character offsets into the text passed in: the heading line's start, the first character after it, the section's end. */
start: number;
bodyStart: number;
end: number;
}

const FRONTMATTER = /^---\r?\n[\s\S]*?\r?\n---[^\S\r\n]*(?:\r?\n|$)/;
const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
const HEADING = /^ {0,3}(#{1,3})[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/;

/**
* The H1–H3 sections of an ISA. Frontmatter is skipped. A fence closes only on the same character, at least as
* long, with nothing after it, so a ``` line inside a ```` block stays inside; an unclosed fence runs to the end.
* Headings inside fences are text. A section ends at the next heading of the same or a higher level (an H2 ends at
* the next H2 or H1), or at the end of the text; a `---` rule is body text.
*/
export function isaSections(text: string): IsaSection[] {
const heads: Omit<IsaSection, "end">[] = [];
let offset = text.match(FRONTMATTER)?.[0].length ?? 0;
let fence: { char: string; size: number } | null = null;
for (const line of text.slice(offset).split("\n")) {
const start = offset;
offset += line.length + 1;
const bare = line.replace(/\r$/, "");
const f = FENCE.exec(bare);
if (fence) {
if (f && f[1]![0] === fence.char && f[1]!.length >= fence.size && !f[2]!.trim()) fence = null;
continue;
}
if (f && !(f[1]![0] === "`" && f[2]!.includes("`"))) { fence = { char: f[1]![0]!, size: f[1]!.length }; continue; }
const h = HEADING.exec(bare);
if (h) heads.push({ level: h[1]!.length as 1 | 2 | 3, title: h[2]!.trim(), start, bodyStart: Math.min(offset, text.length) });
}
return heads.map((h, i) => {
const next = heads.slice(i + 1).find((n) => n.level <= h.level);
return { ...h, end: next ? next.start : text.length };
});
}

/** The sections whose level and title match one of `kind`'s names. */
export function findSections(sections: IsaSection[], kind: SectionKind): IsaSection[] {
const names = SECTION_ALIASES[kind].map((a) => ({ level: a.level, re: new RegExp(`^${a.pattern}\\b`, "i") }));
return sections.filter((s) => names.some((n) => n.level === s.level && n.re.test(s.title)));
}
12 changes: 4 additions & 8 deletions LifeOS/install/hooks/lib/isa-utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ import { writeFileSync, readFileSync, readdirSync, statSync, existsSync, mkdirSy
import { join, basename } from 'path';
import { createHash } from 'crypto';
import { parseIsaClaimsText, isaBody, claimText, stripBulletPrefix, BRIDGE_HEADING_RE } from '../../LIFEOS/TOOLS/lib/IsaClaims';
import { CRITERIA_HEADING_RE } from '../../LIFEOS/TOOLS/lib/IsaSections';
import { lifeosPath } from './paths';
import { appendWorkEvents, diffRegistry, foldToSnapshot, readLiveRegistry, workEventsPath } from './work-events';
import { PHASE_TO_ASCENT, ascentTag, deriveAscent, isRunActive } from '../../LIFEOS/TOOLS/ascent';
Expand Down Expand Up @@ -187,14 +188,9 @@ export function writeFrontmatterField(content: string, field: string, value: str
// no criterion cards, no body-count progress, no criteria fallback on the board
// (found 2026-07-22 — the "essence of hill climbing" gap was largely this).
//
// `## Features` is LAST in the alternation and only wins when no earlier
// criteria heading exists. In feature-block ISAs (v2.16.0) `## Features` holds
// the ISCs (nested under `### F<n>` sub-headings, which are H3 so the section
// runs to the next H2); legacy ISAs keep a `## Claims`/`## Criteria` section
// that sorts before their `## Features` pointer table, so they are unaffected —
// and a legacy pointer table has no `- [ ]` lines to mis-parse regardless.
export const CRITERIA_HEADING_RE =
/^(?:##\s+(?:ISC\s+)?Criteria\b[^\n]*|##\s+Claims\b[^\n]*|##\s+IDEAL\s+STATE\s+CRITERIA\b[^\n]*|###\s+Criteria\b[^\n]*|##\s+Features\b[^\n]*)$/im;
// The criteria heading names, `## Features` among them, live in SECTION_ALIASES (LIFEOS/TOOLS/lib/IsaSections.ts),
// which generates this regex. public issue #2527
export { CRITERIA_HEADING_RE };

// Canonical heading the template emits and migrations target.
// Short, unambiguous, what most live ISAs already use.
Expand Down