agentleFS
dragoscvdragoscv/axiom/.github/skills/debug-apply-journal/SKILL.md

debug-apply-journal

Skill0 starsChanged 54 days agoMITView on GitHub

Diagnose a failed, interrupted or suspicious `apply` on a target root by reading the .axiom/ journal, staging and backup directories — determine the phase it died in, what was written, and whether rollback/recover is safe. Use when a user reports "apply left my tree half-written", ERR_LOCKED, a journal in `committing`, or wants to prove a rollback restored the pre-image.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Freeze the scene: Do not run apply again yet.

    line 28
  2. Very specific:

    Add a line to /memories/repo/axiom-overview.md if the failure mode is new.

    line 63

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Debug an apply journal

@codai/axiom-apply is a two-phase commit. Everything it knows is on disk under <root>/.axiom/ — read that first, reason second, mutate last (and only via rollback()/recoverIfNeeded(), never by hand-deleting).

Layout (from packages/apply/src/apply.ts + journal.ts + lock.ts):

<root>/.axiom/
  lock                         single writer: { pid, startedAt } — stale after 60 min
  journal/<digest-hex>.json    Journal { manifestDigest, phase, steps[], startedAt, pid }
  stage/<digest-hex>/…         phase-1 blobs, sha256-verified, not yet in place
  backup/<digest-hex>/…        pre-images of files phase 2 overwrote/deleted
  applied/<digest-hex>         marker written after a successful commit (idempotency)

Phases (JournalPhaseSchema, packages/schema/src/apply.ts): staged → committing → committed, or committing → rolling-back → rolled-back.

Steps

  1. Freeze the scene. Do not run apply again yet. git status --short in the root (if it is a git tree) and list .axiom/journal/. Copy the whole .axiom/ dir to .copilot-tmp/axiom-forensics-<ts>/ before touching anything.
  2. Read the journal: Get-Content <root>/.axiom/journal/<hex>.json | ConvertFrom-Json. Note phase, pid, startedAt, and for each step path, op, backup, done. done: false steps in committing = files phase 2 never reached.
  3. Match it to the manifest: the file name is manifestDigest minus sha256:. If the caller still has the bundle, axiom_manifest_verify (or verifyBundle in @codai/axiom-plan) confirms it is the same digest — a mismatch means someone applied a different bundle than they think.
  4. Check the lock: is pid alive? (Get-Process -Id <pid>). Alive → another apply is genuinely running; wait. Dead + startedAt older than LOCK_STALE_MS (60 min) → acquireLock will reclaim it on the next call; younger → ERR_LOCKED is correct, do not delete the file by hand.
  5. Classify:
    • staged — nothing in the tree changed; stage dir can be discarded. Safe.
    • committing, some done: true — the tree is mixed. Every done step has a backup entry → rollback is possible and byte-exact.
    • committed — apply finished; if the user sees "wrong content", compare sha256 of each path against artifacts[].sha256 in the manifest before blaming apply (an editor or another agent may have written after).
    • rolling-back — a rollback was interrupted; recoverIfNeeded(root) finishes it idempotently.
  6. Verify pre-images before rolling back: for each done step, Get-FileHash <root>/.axiom/backup/<hex>/<path> should equal the pre-image hash the journal/manifest recorded (ArtifactPre in the bundle). A mismatch is a TOCTOU finding — record it, it is the bug, not the symptom.
  7. Recover: rollback(root, "sha256:<hex>") from @codai/axiom-apply (or MCP axiom_rollback). Then re-hash the touched paths against the backups: identical → VERIFIED restored. A second rollback must be a no-op.
  8. Reproduce in a test, not in the user's tree: packages/apply/src/apply.test.ts has fault-injection at step i — add the failing step index/shape you found as a new case, assert result.code and the byte-identical tree.
  9. Report: phase found, steps done/undone, whether backups matched, what restored it, and the root cause (ERR_* code) — with the command output. Add a line to /memories/repo/axiom-overview.md if the failure mode is new.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.