Cross-session continuity - No deterministic enforcement of SessionProgress.ts?

[tzioup]

SessionProgress.ts + LoadContext reader exist but no enforcement trigger connects them

Summary

SessionProgress.ts (the writer) and LoadContext.hook.ts → getProjectProgress() (the reader) form a complete multi-session continuity system — but nothing in the Algorithm, CLAUDE.md, or any hook mandates creating a progress file when multi-session work begins. The infrastructure is built in two halves with no enforcement layer connecting them.

What exists (working correctly)

Writer: PAI/TOOLS/SessionProgress.ts

• Creates/updates progress files at MEMORY/STATE/progress/<project>-progress.json
• Tracks: objectives, decisions, work completed, blockers, handoff notes, next steps
• CLI with create, work, decision, next, handoff, resume, complete commands

Reader: hooks/LoadContext.hook.ts → getProjectProgress()

• Fires at SessionStart
• Reads ALL files in MEMORY/STATE/progress/ with no time cutoff
• Injects project objectives, handoff notes, and next steps into the DA's context
• Flags stale projects (>14 days since last update)

Short-term bridge: getRecentWorkSessions() in the same hook scans MEMORY/WORK/ ISAs from the last 48h. Non-completed ISAs appear automatically. This covers same-day/next-day continuity but expires after 48h.

What's missing

No enforcement trigger connects the writer to the workflow. Specifically:

1. Algorithm v6.3.0 — does not reference SessionProgress.ts. The LEARN phase Learning Router routes state to PROJECTS.md (human-readable layer) but not to progress files (machine-readable layer that LoadContext actually reads programmatically).

2. CLAUDE.md — no operational rule mandates progress file creation for multi-session work.

3. Hooks — no hook fires at SessionEnd (or ISA creation, or phase transition) that detects "multi-session work exists without a corresponding progress file" and either auto-creates one or blocks/reminds.

4. ISA Skill — the Scaffold workflow doesn't check whether the work it's scaffolding is multi-session and prompt for progress file creation.

Reproduction

1. Fresh V5 install. Fifth session.
2. User requests work that clearly spans multiple sessions (e.g., multi-step onboarding plan with 6 phases).
3. DA creates ISA, executes first phase, marks ISA phase: complete.
4. Session ends. No progress file created. No handoff notes. No next steps in LoadContext.
5. New session starts. LoadContext injects nothing about the multi-session plan.
6. User must manually remind the DA that a plan exists and where it is.

The DA "should have known" to create a progress file — but "should have known" is DA-discipline-dependent, which violates Founding Principle #6 ("As Deterministic as Possible").

Impact

For expert users, this is likely a non-issue — you know the tool exists and invoke it consciously. For new users whose DA is also encountering the system for the first time, this creates a silent continuity failure. Work gets done but the handoff between sessions doesn't happen unless the user chases it up. The system feels unreliable on first contact.

This is especially sharp because the reader (LoadContext) is already wired and waiting — the user will never see a progress injection because nothing upstream creates the file.

Proposed fix

Option A (deterministic, preferred): A hook at SessionEnd that:

1. Checks if an ISA was active this session with effort: E3+ or with explicit multi-session indicators (next_steps in decisions, plan with future phases)
2. Checks if a corresponding progress file exists in MEMORY/STATE/progress/
3. If not: auto-creates one from ISA frontmatter + decisions, or emits a blocking reminder

Option B (doctrine): Add to Algorithm LEARN phase Learning Router:

| `continuity` | `MEMORY/STATE/progress/<project>-progress.json` via SessionProgress.ts | **Inline create/update.** |

With a mandate: "If this Algorithm run is part of multi-session work, a progress file MUST exist before phase: complete."

Option C (ISA Skill integration): When ISA Scaffold creates an ISA at E3+, prompt: "Is this multi-session? If yes, create progress file." Or detect it heuristically from the Features table (features with depends_on pointing to things not yet done).

Option A is most aligned with Founding Principle #6 (deterministic enforcement). Options B and C are DA-discipline-dependent but lightweight.

Design question for maintainer

Was the gap between SessionProgress.ts and LoadContext intentional (expert users invoke the tool consciously when they know work spans sessions) or an oversight (the enforcement hook was planned but not built)? The answer determines whether the fix is "add enforcement" or "document the manual invocation point more prominently."

Environment

• PAI 5.0.0
• Algorithm v6.3.0
• Fresh install, fifth session

[DolphusCY]

Confirming this manifests on an actively-used 5.0.0 install — and adding two technical observations that I think strengthen the proposed fix.

We are suffering from this

On our setup, the writer-reader split has produced exactly the silent failure you describe:

• SessionProgress.ts installed (May 1)
• LoadContext.hook.ts → getProjectProgress() installed and firing every session
• MEMORY/STATE/progress/ does not exist — the directory has never been created
• Six ISAs in MEMORY/WORK/ from the last week stalled mid-flight (phase: execute, phase: verify, phase: observe — none phase: complete), none of which have a progress file
• LoadContext reports Status: UNKNOWN for those active sessions because the writer never wrote anything for the reader to read

The reader has been polling an empty directory for a week. New sessions cold-start with no continuity context for any of the in-flight work.

On the proposed fix — modify Option A to drop the "blocking reminder" half

Option A: A hook at SessionEnd that... If not: auto-creates one from ISA frontmatter + decisions, or emits a blocking reminder

I'd argue the blocking-reminder variant is wrong, even though Founding Principle #6 (deterministic) seems to call for it. Reasoning: blocking enforcement on ISA-related artefacts produces the same operator friction as a hard phase: complete gate. If the principal user is mid-work and the hook refuses because no progress file exists, the failure mode is "operator either bypasses or learns to avoid E3+ ISAs to skip the rule" — both worse than the silent gap.

The right shape is auto-create only, never block:

1. PostToolUse on Edit|Write of MEMORY/WORK/*/ISA.md (not SessionEnd — too coarse, fires once for everything that happened)
2. Trigger condition: ISA frontmatter shows effort: E3+ AND phase != complete
3. Action: idempotently create or update MEMORY/STATE/progress/{slug}-progress.json from ISA frontmatter + decisions. No prompt, no refusal.

This is the same architectural pattern as inverting a PreToolUse-block to a PostToolUse-trigger: the artefact gets written, the operator never sees friction, the reader has something to read next session. Mechanical, deterministic, non-blocking.

PostToolUse on ISA edits is also more accurate than SessionEnd because it captures the moment the multi-session intent was declared (when the ISA was scaffolded with E3+) rather than batching at session end.

Symmetric close-side gap

The issue describes the create side. There's a parallel close side that the proposed fix should cover:

Even if progress files start getting created, nothing closes them when the underlying ISA finally completes. Without a close-side trigger:

• Progress files accumulate indefinitely
• getProjectProgress() reads more and more stale entries
• The >14 days stale flag becomes the only differentiator between active and abandoned, which is a band-aid

Symmetric fix:

• Open trigger: PostToolUse on ISA edit with phase != complete + effort: E3+ → create/update progress file (status: active)
• Close trigger: PostToolUse on ISA edit where the diff includes phase: complete → mark progress file status: complete, optionally set archive timestamp

Both triggers can live in a single new hook (hooks/SessionProgressGate.hook.ts or similar) keyed on the same path filter. The diff inspection is identical to what the existing ISASync.hook.ts already does — that hook is a reasonable model for the implementation pattern, but as a separate hook so the two responsibilities don't tangle.

On "expert users invoke consciously" framing

The issue notes that expert users probably don't suffer from this. Counter-evidence: even with full awareness of SessionProgress.ts and intentional adoption of the v5 algorithm, the friction of remembering to invoke the writer at the right moment ensures it doesn't happen. We knew the tool existed and still produced six in-flight ISAs with zero progress files. Memory-based enforcement of operational tooling fails for the same reason feedback_*.md rules in the LEARNING tree get forgotten — the cost of remembering is paid every session, the cost of forgetting is silent.

Mechanical enforcement (whether via hook, ISA Skill integration, or both) is the only durable fix. The hook approach is most aligned with the existing infrastructure shape.

---

UPDATE 2026-05-07: relevant data point and an honesty correction

Following up after digging deeper into our local setup. Two findings worth recording on the issue:

Finding A — there's a half-built version of this in private hooks

We have a hook in our private extension layer (not upstream PAI) called WorkStateTracker.hook.ts that is almost the missing piece, but two bugs prevented it from doing the job:

Bug 1 (v4→v5 rename was incomplete in the hook source):

// As shipped (broken under v5):
if (!filePath.includes('/MEMORY/WORK/') || basename(filePath) !== 'PRD.md') {
  process.exit(0);
}

The hook was hardcoded to fire only on PRD.md writes, but in v5 the work-tree artefact is ISA.md. So under v5 the hook never matched, never fired, and registering it without patching would have been dead code. A 3-line fix:

const fname = basename(filePath);
if (!filePath.includes('/MEMORY/WORK/') || (fname !== 'ISA.md' && fname !== 'PRD.md')) {
  process.exit(0);
}

Worth scanning upstream PAI hooks for similar leftover 'PRD.md' literals from the v4 era — same class of bug could be hiding in other hooks.

Bug 2 (wrong target path — even after the v4→v5 fix, this hook does not actually close issue #1192):

WorkStateTracker writes to MEMORY/STATE/current-work-{session_id}.json (session-bound, one file per session ID).

LoadContext.getProjectProgress() reads MEMORY/STATE/progress/*-progress.json (project-bound, one file per project, persists across sessions).

Different filenames, different shapes, different lifecycles. Even with WorkStateTracker patched and firing on every ISA edit, LoadContext.getProjectProgress() still finds nothing — because nothing writes the project-progress file format the reader expects.

Finding B — honesty correction on my earlier framing

In my original comment I said the right fix shape is "PostToolUse on ISA edit → create progress file." That direction is still correct. But I implied that registering an ISA-watching state-tracker hook would close this issue — which my own data above disproves. The two artefacts are different:

Artefact	Writer	Reader	Lifecycle
STATE/current-work-{session_id}.json	a session-state hook (e.g. patched WorkStateTracker)	not consumed by getProjectProgress	per-session, ephemeral
STATE/progress/<slug>-progress.json	nothing currently — this is the gap	LoadContext.getProjectProgress()	per-project, persists across sessions

So the issue stands as written. The fix needs a hook that writes the progress-file format specifically — not session-state, but project-bound progress with a stable <slug> identifier carried across sessions.

Concrete implementation pattern for the upstream fix:

// hook/SessionProgressGate.hook.ts (proposed)
//
// Triggers on PostToolUse of Write|Edit when path matches /MEMORY/WORK/*/ISA.md.
// Reads the ISA frontmatter; extracts: slug, task, effort, phase, decisions.
//
//   if (effort >= E3 AND phase !== 'complete'):
//     idempotently write/update STATE/progress/{slug}-progress.json
//     with status: 'active', objectives, decisions, next_steps from ISA
//
//   if (phase === 'complete'):
//     mark existing progress file status: 'complete', set archived_at,
//     do NOT delete (LoadContext's stale flag handles cleanup)
//
// Same path filter as the proposed PreToolUse gate; just inverted to PostToolUse.

That's the actual minimum work to close the issue end-to-end. Estimated ~30 lines of TypeScript modeled on the existing ISASync.hook.ts shape.

Why the data point matters

The fact that someone (us) attempted this independently with WorkStateTracker and almost got there suggests the gap is intuitive enough that downstream users keep building partial fixes for it locally. That's both validation of the issue AND argument for the fix landing upstream — otherwise every PAI install will keep half-implementing this in private extension layers with subtly different shapes.

[catchingknives]

This looks like the same pattern one level over, on the ISA itself. Noting it here since a fix would probably cover both.

The ISA pipeline splits the same way:

• Sync side: ISASync.hook.ts reads a written ISA and syncs its frontmatter/criteria to work.json for the dashboard and phase tab. (That half was unwired until v5.0.0: ISASync / CheckpointPerISC / ToolFailureTracker hooks ship but aren't registered in settings.json #1134, fixed for 5.1.0.)
• Creation side: the model is expected to invoke the ISA skill Scaffold workflow at the OBSERVE phase.

What I couldn't find is anything that connects an ALGORITHM-classified task to an ISA actually existing. PromptProcessing.hook.ts emits MODE: ALGORITHM | TIER: ... as an advisory additionalContext note, and no hook creates or requires an ISA (ISASync is read-only by its own header: "the AI writes all ISA content directly"). So creation comes down to DA discipline, the same gap described here for progress files, just applied to the ISA.

Flagging in case it's useful when this gets addressed.