Kiroku

Kiroku

The record of what actually happened.

Kiroku (記録, Japanese: record/documentation) manages the evidence trail that makes autonomous work observable. It is the implementation layer for Principle 2 (Observable Autonomy).

Why this exists

Autonomy without evidence is not delegation — it is abdication. When an agent (human or AI) does work autonomously, the question is never "did it do something?" but "can someone who wasn't there reconstruct what happened, why, and whether to trust it?"

A trail that answers this question earns the right to more autonomy. A trail that doesn't answer it — or doesn't exist — means autonomy must be constrained regardless of how competent the work was.

This is the core dependency:

Evidence → Trust → Autonomy

More evidence → more trust → more autonomy earned. Less evidence → trust decays → autonomy must be constrained. Zero evidence → zero trust → autonomy must be revoked.

What good evidence looks like

Multi-resolution

Not everyone has the same time budget. A 50-page transcript is unreadable to the person with 2 minutes. A 1-paragraph summary is insufficient for the person with an afternoon. Good evidence exists at multiple resolutions simultaneously:

Resolution	What it answers	Time budget
Digested	Where are we? What just happened? Should I be concerned?	30 seconds
Indexed	What decisions were made? What was the reasoning? What changed?	5–15 minutes
Full	What exactly happened, step by step?	Unlimited

A single-resolution trail satisfies one observer while silently excluding the rest. That exclusion violates the principle even when the trail itself is honest.

Honest about its own limitations

Evidence has a fidelity level. A verbatim tool output and a reconstructed-from-memory summary are both evidence, but they are different trust levels. Conflating them is dishonest. The trail must mark its fidelity explicitly so observers can calibrate their trust.

Where the agent authors its own summary, this must be marked. A summary written by the audited party is evidence, but it is not independent evidence.

Records reasoning, not just results

"Removed 1 file" is a result. "Removed utils/helpers.py because no module imports it and its tests are orphaned" is reasoning. The why is what makes the action observable and challengeable. Without it, an observer can see what happened but cannot judge whether it was correct.

Three markers capture the most valuable moments in autonomous reasoning:

• [!DECISION] — A choice that could have gone differently. Always include rationale and alternatives considered.
• [!REALIZATION] — Something discovered during the work that changed understanding.
• [!REVERSAL] — A decision that was made and then undone. Reversals are more valuable than decisions — they show the reasoning evolved.

[!DECISION] Move GENBA.md into TRAIL/ directory
Rationale: GENBA is evidence, not a project-level artifact. It belongs with the rest of the trail.
Alternatives: Keep at root (rejected — inconsistent with TRAIL/ being the single evidence location).

[!REALIZATION] The debug log captures zero conversation content — only session_start metadata.

[!REVERSAL] Initially recommended kiroku as tooling, not a skill. Reversed after recognizing it has
a "when" (every session) and a "how" (the scripts), which qualifies it as a skill.

Traces intent

The most important question a trail can answer is: was the work that was done actually what was asked for? Every session captures intent before work begins:

• Human intent (verbatim): What was actually asked for. Quote directly.
• Agent interpretation: How that request was parsed into a plan. What assumptions were made.
• Scope & constraints: Boundaries stated or inferred.

The trail structure

Every target project gets one TRAIL/ directory. All evidence lives there:

target-project/
  TRAIL/
    README.md    — Observer entry point (what is this, how to read it)
    SUMMARY.md   — Executive digest (digested resolution)
    INDEX.md     — Decision index, auto-generated (indexed resolution)
    sessions/    — Full session transcripts (full resolution)

The observer looks at one directory. Everything is there.

Other skills may add their own artifacts to TRAIL/ (e.g., Kata adds GENBA.md as a run ledger). Kiroku manages the core evidence layer; methodology-specific artifacts belong to the skill that needs them.

When to use this

Every session where substantive work happens. If the work produces decisions, changes, or findings, it produces a trail. No session is invisible.

This includes any autonomous work:

• Software development, refactoring, bug fixes
• Design conversations that produce architectural decisions
• Reviews, audits, investigations
• Planning sessions, hiring discussions, legal reviews
• Improvement cycles (kata, kaizen, kaikaku) — these add their own artifacts to TRAIL/

Target resolution

The trail belongs to the target, not to the mechanism that invoked kiroku.

• Work on repository X → writes to X/TRAIL/
• Kata targeting repository X → writes to X/TRAIL/
• Self-targeting the skills suite → writes to skills/TRAIL/

If different activities target the same repository, they share one trail. The session records who initiated the work; the trail location is keyed by the target.

The scripts

Four PowerShell scripts manage the trail lifecycle:

kiroku-start.ps1 — Begin a session

.\kiroku-start.ps1 -Slug "fix-parser-precedence" -Project "C:\git\mathkit" -Fidelity reconstructed

Creates TRAIL/sessions/YYYY-MM-DD-{slug}.md with YAML frontmatter. On first use in a project, also creates TRAIL/README.md as the observer entry point.

Parameters:

• -Slug (required): Short identifier for the session
• -Project: Target project path (default: current directory)
• -Participants: Who's involved (default: "human, Claude Opus 4.6")
• -Fidelity: verbatim | reconstructed | mixed (default: reconstructed)
• -AllowConcurrentOpen: Optional escape hatch. By default, start is blocked if another in-progress session exists to prevent silent evidence gaps.

kiroku-close.ps1 — End a session

.\kiroku-close.ps1 -Project "C:\git\mathkit"

Updates session status to closed, adds timestamp, counts markers, rebuilds INDEX.md. Use -All to close all orphaned in-progress sessions at once:

.\kiroku-close.ps1 -Project "C:\git\mathkit" -All

kiroku-index.ps1 — Rebuild the decision index

.\kiroku-index.ps1 -Project "C:\git\mathkit"

Scans all session files for [!DECISION] markers. Extracts decision text, rationale, and alternatives. Generates TRAIL/INDEX.md. Preserves manually-maintained retroactive entries (DEC-R prefix).

kiroku-validate.ps1 — Check trail consistency

.\kiroku-validate.ps1 -Project "C:\git\mathkit"

Validates 8 checks:

1. Trail structure (SUMMARY, INDEX, sessions/, README exist)
2. Session headers and scope correctness (fidelity/source/project target)
3. Decision count consistency (sessions vs INDEX)
4. Summary/index freshness and self-authorship warning
5. Open-session safety (single open session, non-empty Trigger/Intent, stale session detection)
6. Fidelity honesty (verbatim or mixed claims require verbatim markers)
7. Secret hygiene (high-confidence credential patterns)
8. Validation performance guardrail (runtime visibility)

Fidelity honesty

VS Code Copilot Chat does not expose an API for exporting conversation transcripts. All session content is at reconstructed fidelity unless tool outputs are pasted verbatim. This is an honest constraint, not a defect. The session template, SKILL.md, and README all mark this explicitly.

After a session

1. Run kiroku-close.ps1 to finalize the session
2. Update TRAIL/SUMMARY.md with current status
3. Run kiroku-validate.ps1 to check consistency
4. Commit the TRAIL/ changes alongside any code changes