Pairs with: Lecture 05 — Why Long-Running Tasks Lose Continuity. Time: ~75 min. Difficulty: Intermediate. Prerequisites: Module 04 checkpoint.

Module 05. Multi-Session Continuity

Why this module

A single agent session can hold an entire small task in its head. Real work spans many sessions, often by different agents or by you on different days. Without durable handoff artifacts each new session pays a rebuild cost — minutes (sometimes hours) of poking at the codebase to figure out what the previous session did. Lecture 05 puts a hard target on rebuild cost: under three minutes from cold start to executable next action. This module gets you there.

You will write PROGRESS.md and DECISIONS.md, practice clock-in / clock-out, and add a noted status command that prints the same handoff information machine-readably.

Concepts

Continuity artifacts — durable files that record what was verified, what is in flight, and what is next. Two files do most of the work: PROGRESS.md (recent) and DECISIONS.md (durable).
Rebuild cost — wall-clock time a fresh agent session needs to reach a verified state where it can pick up the next action. Target: under three minutes.
Drift — gap between an agent's understanding and the actual repo state. Drift compounds across sessions; continuity artifacts are how you reset it to zero.
Clock-in / clock-out — explicit start- and end-of-session routines: read continuity artifacts at the start; update and commit them at the end.
Context anxiety — premature convergence (calling a task done) when the agent senses its context window filling up. Continuity artifacts let the agent stop because the next session can pick up, not because it is running out of room.

→ Read Lecture 05 for the long-form treatment, including the rebuild-cost measurement protocol and the empirical drift study.

Lab

Step 1 — Create `PROGRESS.md`

Copy ../../resources/templates/claude-progress.md into your repo as PROGRESS.md. Replace the placeholders with real content:

# PROGRESS.md

## Current State

- Last verified: Module 04 checkpoint (lint OK, `pnpm test` passes 1/1).
- Active feature: none (Module 06 will introduce the bootstrap).
- Last command run: `git commit -q -m "module-04: split AGENTS.md…"`.
- Known issues: none.
- Definition of Done: `docs/PRODUCT.md`.

## Session Log

### 2025-MM-DD — finishing Module 04
- Split `AGENTS.md` into a routing file plus topic docs under `docs/`.
- Verified citation rule is now duplicated at top and bottom of routing file.
- Reproduced lost-in-the-middle and the fix; results in `docs/cold-start-log.md`.

## Next Action

Open Module 05 and add `DECISIONS.md`, then add `noted status`.

Step 2 — Create `DECISIONS.md`

PROGRESS.md is recent and rolls over. DECISIONS.md is durable: design decisions that survive across the whole project. One entry per decision, ADR-style.

# DECISIONS.md

Decisions kept here outlive any single session. Each entry: date, decision,
context, consequences. Append-only — strike through, never delete.

## D-001 — JSON in `.noted/` is the only persistence layer
- Date: 2025-MM-DD (Module 02)
- Context: A real notes app might use SQLite or a vector store. Course
  scope rules them out (`docs/PRODUCT.md`). JSON keeps state grep-able and
  diff-able, which makes verification labs trivial.
- Consequence: Token index is rebuilt from scratch each `noted index`.
  Acceptable while the corpus is small.

## D-002 — Citation rule is load-bearing
- Date: 2025-MM-DD (Module 04)
- Context: `noted ask` could return clean output without paths. The course
  uses citations to make verification machine-checkable.
- Consequence: Every change to `runAsk` must preserve the `cite:` line.
  Module 09's e2e test will assert it.

Step 3 — Add `noted status`

src/commands/status.ts:

import { readFile } from "node:fs/promises";
import { readNotes } from "../store/io.ts";

export async function runStatus(): Promise<number> {
  const { notes } = await readNotes();
  let progress = "PROGRESS.md not found";
  try {
    const lines = (await readFile("PROGRESS.md", "utf8")).split("\n");
    const i = lines.findIndex((l) => l.trim() === "## Next Action");
    if (i >= 0) progress = lines.slice(i, i + 4).join("\n");
  } catch {}

  console.log(`notes:    ${notes.length}`);
  console.log(`storage:  .noted/notes.json`);
  console.log(`---`);
  console.log(progress);
  return 0;
}

Wire it in src/cli.ts:

import { runStatus } from "./commands/status.ts";
// ...
    case "status":
      process.exit(await runStatus());

Update the help text.

Step 4 — Practice the clock-in routine

Close every editor tab. Open a fresh terminal in your repo. Walk through clock-in out loud, citing files:

pwd — confirm you are in noted-cli/.
cat AGENTS.md — read the routing file (under 80 lines now).
cat PROGRESS.md — find the ## Next Action.
cat DECISIONS.md — skim for anything tagged "load-bearing."
git log --oneline -5 — see the last five commits.
pnpm test — confirm baseline still passes.
./bin/noted status — confirm the same Next Action surfaces machine-readably.

Time it. If you are over three minutes, the artifacts are not pulling their weight. The most common cause: PROGRESS.md says "implementing Module 04" instead of "Module 04 done; next: Module 05" — be specific about what is verified, not just what was attempted.

Step 5 — Practice clock-out

Pretend you have just finished Module 05. Update PROGRESS.md:

## Current State
- Last verified: Module 05 checkpoint (`pnpm test` 1/1, `./bin/noted status` exits 0).
- Active feature: none.
- Last command run: `git commit -q -m "module-05: PROGRESS, DECISIONS, status"`.
- Known issues: none.

## Session Log
### 2025-MM-DD — finishing Module 05
- Added `PROGRESS.md` and `DECISIONS.md`.
- Added `noted status` command.
- Practised clock-in routine; rebuild cost ≈ 90s.

## Next Action
Open Module 06 and write `init.sh` so a fresh clone reaches a verified start.

Append a line to DECISIONS.md only if you actually made a new decision this session. Most clock-outs touch PROGRESS.md only.

Step 6 — Commit and tag the rebuild cost

git add .
git commit -q -m "module-05: continuity artifacts and noted status"

Append to docs/cold-start-log.md:

## 2025-MM-DD (after Module 05)

Rebuild cost: ~90 seconds from terminal-open to identifying next action.
Knowledge visibility gap (5 questions): Q1–Q4 fully sourced; Q5 still
points at "Module 08 will add `feature_list.json`." Gap = 20%.

Verification

test -f PROGRESS.md && \
test -f DECISIONS.md && \
grep -q "## Next Action" PROGRESS.md && \
./bin/noted status | grep -q "Next Action" && \
echo "M05 OK"

Expected:

M05 OK

Common pitfalls

PROGRESS.md becomes a diary. It is not a journal. Keep "Current State" surgical: what is verified, what is broken, what is next. Move narrative to DECISIONS.md only if it survives a year.
Updating PROGRESS.md only at the end of a session. Update the Next Action first, when you start a session — the agent has more context then. Confirm or replace it at clock-out.
Letting "active feature" stay set across sessions. If a feature is mid-flight at clock-out, write down exactly what verification failed and what would turn it green. Otherwise next session re-discovers the same blocker.
Rebuilding noted status to read from feature_list.json. Module 08 adds it; do not pre-build that integration.

Module 06 — Bootstrap Phase. You have continuity artifacts but a fresh clone still requires you to know the exact pnpm install && pnpm test incantation. Module 06 puts that in init.sh and verifies the bootstrap contract holds.

Module 05. Multi-Session Continuity ​

Why this module ​

Concepts ​

Lab ​

Step 1 — Create PROGRESS.md ​

Step 2 — Create DECISIONS.md ​

Step 3 — Add noted status ​

Step 4 — Practice the clock-in routine ​

Step 5 — Practice clock-out ​

Step 6 — Commit and tag the rebuild cost ​

Verification ​

Common pitfalls ​

Next ​