Skip to content

feat(tools): add Pending.ts, open criteria across all ISAs - #2680

Open
henrique-franze wants to merge 1 commit into
danielmiessler:mainfrom
henrique-franze:feat/pending-core
Open

henrique-franze wants to merge 1 commit into
danielmiessler:mainfrom
henrique-franze:feat/pending-core

Conversation

@henrique-franze

Copy link
Copy Markdown

Implements the idea from #2352, under the four conditions in the reply there. One small read-only CLI with tests on synthetic ISAs, rebased on 8.761.0.

What it does. bun LIFEOS/TOOLS/Pending.ts [--json] reads the ISAs Pursuit reads and reports, per ISA, open / closed / dropped criteria and unchecked ## Remaining Work items (the ISAFormat v2.19.0 backlog union), with phase, age and a group label. It flags two generic anomalies: a closed phase with open criteria, and open work idle past --idle-days (default 14).

The user never types it: they ask their DA "what is still open across my work?", and the DA finds the tool through its Tools.md entry, runs it with --json, and answers in chat.

The four conditions, each in code:

Condition Where
On demand only, no hook or SessionStart wiring Nothing registers it: no settings*.json entry, no hook, no schedule. It runs only from the command line.
Reuses parseClaims and the existing phase sets import { parseClaims } from './IsaFrontier'; closed = isaClosed from Pursuit.ts (the cairn bracket from ascent.ts plus Pursuit's stopped phases). There is no phase literal in Pending.ts.
Default roots match Pursuit.ts import { isaDirs } from '../IDEALSTATE/Pursuit', so the defaults are MEMORY/WORK plus the LIFEOS dir (or IDEALSTATE_ISA_DIR). Discovery is <root>/<child>/ISA.md, the shape liveIsas() reads, so both tools see the same ISAs.
Output says criteria Human output, --help, anomaly kinds (closed_with_open_criteria, idle_with_open_criteria) and docs all say criteria. JSON keys are open / closed / dropped / remaining.

One detail on parseClaims. It calls parseIsaClaimsText with includeParents: true because the frontier needs parent nodes for dependency edges. For counting, Pending keeps only the leaves (a criterion whose next criterion is not indented deeper), which matches what lib/IsaClaims.ts counts without that option. Without this, a fully closed split ISA would read as open.

The one change outside the new files: Pursuit.ts gains export on isaClosed and isaDirs (2 lines), so Pending imports them instead of copying. Behaviour is unchanged.

Files

  • LIFEOS/TOOLS/Pending.ts: the CLI (--json, --root, --group-field, --idle-days; exit 0 on a scan, 2 on a bad argument)
  • LIFEOS/TOOLS/Pending.test.ts: 42 tests, every fixture a synthetic ISA in a temp dir. Includes each closed phase through isaClosed, Pursuit's default roots (in-process and through the CLI, isolated with CLAUDE_CONFIG_DIR), one-level discovery, split criteria counted through their leaves, Anti/Bridge criteria, fences, tables, CRLF, and every bad argument.
  • LIFEOS/DOCUMENTATION/Pending/PendingSystem.md: what it reuses, how criteria are counted (each line pinned by a test), config, anomalies, JSON shape
  • LIFEOS/DOCUMENTATION/Tools/Tools.md: one entry

Checked: bun test LifeOS/install/LIFEOS/TOOLS/Pending.test.ts → 42 pass, 0 fail. bun .github/scripts/leak-scan.ts → no blocking findings, none in these files. Mutation checks on the load-bearing lines: replacing isaClosed with phase === "complete" fails 3 tests, replacing isaDirs() with a fixed list fails 2, and dropping the leaf filter fails 2.

One question for later. I use a Pulse tab built on the same scan every day. Would a follow-up PR for a Pulse view be welcome, as a page that runs the scan only when it is opened (no background refresh, so condition 1 still holds)? If not, this PR stands on its own.

Happy to rename, move or trim anything to fit how you'd port it into the private tree.

On-demand, read-only CLI that counts open, closed and dropped criteria
(plus unchecked Remaining Work items) across the ISAs Pursuit reads.

Per discussion danielmiessler#2352:
- runs only when called: no hook, no SessionStart wiring, no schedule
- criteria come from IsaFrontier's parseClaims; closed phases from
  Pursuit's isaClosed (no new phase list)
- default roots are Pursuit's isaDirs(): MEMORY/WORK plus system ISAs,
  read with the same <root>/<child>/ISA.md shape as liveIsas()
- output says criteria

Pursuit.ts: export isaClosed and isaDirs so Pending imports them
instead of copying. Tests run on synthetic ISAs in temp dirs.

@isihussain isihussain left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Architectural & Quality Review

Nice work @henrique-franze. Adding Pending.ts as a read-only cross-ISA status aggregator fills a real gap from discussion #2352. Reusing existing primitives (isaClosed and isaDirs from Pursuit, and parseClaims from IsaFrontier) rather than duplicating ISA parsing logic is great engineering practice.

Here is an architectural review, including an important cross-platform edge case:


1. Portability / Bug: Windows CRLF Line Endings in Frontmatter

In Pending.ts:

/** Flat top-level `key: value` frontmatter, trailing comments and quotes stripped. Expects LF input. */
function parseFrontmatter(content: string): Record<string, string> | null {
  const match = content.match(/^---\n([\s\S]*?)\n---/);
  if (!match) return null;

On Windows machines, or git environments where core.autocrlf is active, markdown files often have CRLF (\r\n) line endings. Because the regex strictly tests ^---\n, it will fail to match on any file with CRLF delimiters, returning null and falsely recording a no_frontmatter anomaly on otherwise valid ISAs.

Recommendation: Allow optional carriage returns in the delimiter regex and line splitting:

const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
if (!match) return null;
const fm: Record<string, string> = {};
for (const line of match[1].replace(/\r/g, '').split('\n')) {
  const kv = line.match(/^([A-Za-z_][\w-]*):(.*)$/);
  if (kv) fm[kv[1]] = stripTrailingYamlComment(kv[2].trim()).replace(/^["']|["']$/g, '');
}

The same optional \r should be permitted in countRemaining when matching the section end:

const end = rest.match(/\r?\n(?:#{1,2}\s|---\s*(?:\r?\n|$))/);

2. Architecture & Code Reuse

Exporting isaDirs() and isaClosed() from Pursuit.ts maintains single-source-of-truth semantics for what constitutes a closed ISA across both Pursuit and Pending.


3. Style / Conventions

Consider adopting the node: protocol import prefix (import { ... } from 'node:fs', import { join } from 'node:path') to match modern Node/Bun conventions across the rest of the LIFEOS/TOOLS/ codebase.


The test coverage in Pending.test.ts on synthetic ISAs is very thorough. Once CRLF handling is guarded, this will be completely solid across all platforms.

@henrique-franze

Copy link
Copy Markdown
Author

Note

🤖 Cida (AI assistant) responding on behalf of Henrique Mateus Franze

@isihussain Thanks for the review. CRLF is already handled: scan() normalizes \r\n to \n when it reads each file (Pending.ts:136), and Pending.test.ts has a CRLF fixture covering frontmatter, claims and Remaining Work. I've kept the bare fs/path imports to match the files around it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants