/workspace-discipline

name: workspace-discipline
description: Disk is truth. Never trust your in-memory belief about what's done; check disk. Idempotent operations, checkpoint before risky moves, append-only event logs, observable done criteria. The discipline that makes John recoverable across compaction, crashes, and fresh sessions.
metadata:
  triggers:
    - is it really done
    - check disk
    - verify state
    - workspace state
    - disk is truth

workspace-discipline

Five rules. Internalize each. They're not optional, and they're not "if you have time" — they're the operating contract for working in a John session.

Rule 1: Disk is truth

When you need to know if something is done, **check disk**. Do not trust:

• Your memory of what you did three messages ago.
• A subagent's report ("I extracted 47 entries").
• A tool result that came back successful 10 minutes ago.
• The Log section of PLAN.md alone (it might say "Phase 3 done" but the artifact directory could be empty).

Check disk means: use `ls`, `find`, `cat`, file existence checks. The phase done-criteria in PLAN.md are disk-verifiable for a reason. Verify them.

This rule is the single most important discipline in John. It is the cleanest learned lesson from KC, a sibling verification harness: agents will assert work is done that isn't, and the engine has to verify from filesystem. You ARE the engine here, so the verifying is on you.

Rule 2: Idempotent operations

Every operation you take should be re-runnable. If you run it twice in a row, the second run should either:

• Produce the same disk state as the first run, OR
• Be a clean no-op (notices the work is already done and exits)

NOT: corrupt state, double-write, error out, or produce different output.

This matters because:

• Sessions get interrupted; the next session may re-run a phase.
• Subagents may be re-dispatched after partial failures.
• The reducer ([[event-log-and-reducer]]) runs many times during a phase.
• The user may `/clear` mid-flight; recovery should be straightforward.

How to be idempotent:

• **Read before write.** Check if the file/dir/entry exists before producing it. If it does, decide: skip, overwrite, or merge.
• **Use deterministic IDs.** A knowledge entry's ID should be derivable from its source (chunk + position), not random. Re-running extraction on the same chunk yields the same entry IDs.
• **Append-only logs.** Never edit an event file after writing it. Add a new one to supersede.
• **Compute, don't accumulate.** Canonical state is computed from events; don't accumulate it in place across runs.

Rule 3: Checkpoint before risky moves

Before doing something destructive, irreversible, or hard-to-redo, leave a checkpoint on disk:

• About to rewrite the whole knowledge inventory based on a schema change? Write the current state to `<project>/.john/checkpoints/<phase>/pre-rewrite-<timestamp>.json` first.
• About to delete a directory of stale artifacts? Move it to `<project>/.john/checkpoints/<phase>/archived-<timestamp>/` instead — recovery is possible.
• About to overwrite PLAN.md with a major restructure? Save the prior version as `<project>/.john/checkpoints/plan/PLAN-<timestamp>.md`.

John's PreCompact hook does this automatically before a supported runtime compacts context. Do it manually at analogous moments when hooks are unavailable or untrusted.

Rule 4: Append-only event logs

Events ([[event-log-and-reducer]]) are append-only. Once written, an event file is immutable history. To "correct" an event, write a new event that supersedes it (e.g., `{event_type: "entry_replaced", supersedes: "abc-123", ...}`), and let the reducer fold the supersession.

Why immutable:

• Replay. You can re-run the reducer with any subset of events to see prior states.
• Audit. The full record of what every subagent did, in order.
• Recovery. If the reducer is buggy, you fix the reducer; you don't lose events.

If you find yourself wanting to edit an event file, you're probably trying to hide a mistake. Don't. Emit a corrective event instead.

Rule 5: Verify observable done criteria

Authoring good done criteria is [[phase-design]]'s job. Verifying that they're met is yours. The two roles are distinct — when you read PLAN.md and the Done criteria looks vague, push the user to tighten it via phase-design's methodology rather than guessing what "feels right."

Every phase in PLAN.md has a "Done criteria" line. It must be observable on disk. Examples:

• ✓ "All chunks in `chunks_index.json` have a corresponding entry in `<project>/.john/checkpoints/extract/state.json` (verified by ID match)."
• ✓ "Matching `<project>/.claude/skills/<skill-name>/SKILL.md` and `<project>/.agents/skills/<skill-name>/SKILL.md` exist for every packaged entry, and each has YAML frontmatter with `name` and `description`."
• ✓ "`<app-output>/<entry-point-file>` returns HTTP 200 when served via the test runner."

NOT:

• ✗ "The extraction looks good."
• ✗ "Most entries are covered."
• ✗ "The app works."

If the user wrote a vague done criterion in PLAN.md, push back. Get it specific before advancing.

To verify a done criterion: run the check (Bash `ls`, `wc -l`, `python -c '...'`, etc.), confirm the result, then mark the phase done in PLAN.md.

What to check, mechanically

A short list you should be able to execute in any iteration:

# Where are we in the plan?
cat <project>/PLAN.md | head -50

# What's John's working state?
ls -la <project>/.john/

# What artifacts has this phase produced?
ls <project>/.john/checkpoints/<phase>/ 2>/dev/null

# What events came in?
ls <project>/.john/events/<phase>/<work-unit-type>/ | wc -l

# What's been packaged?
ls <project>/.claude/skills/ <project>/.agents/skills/ 2>/dev/null

# Recent activity (workspace git, if tracked)
cd <project> && git log --oneline -5 2>/dev/null

You don't need to run all of these every iteration. You DO need to run the relevant subset when verifying a done criterion or recovering from compac