Skip to content

refactor(crew-log): rename the store's ledger identifiers to crew log - #11907

Merged
bolichen97 merged 1 commit into
mainfrom
refactor/crew-log-identifiers-phase2
Sep 19, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
refactor/crew-log-identifiers-phase2

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Four different things in this repository are called a ledger. Reading a name does not tell you which one.

Phase 1 (#11549) renamed this store's package, its directory on disk and every doc that describes it to crew log. The identifiers stayed behind. So LedgerError in a traceback, ledger_dir() in a review diff and a thread named mc-ledger in a stack dump each still name the crew log, while the session work ledger (session_ledger.py), the taskq wait ledger (WaitLedger) and two builtin apps' accounting ledgers answer to the same word.

Why it matters

A reader has to open the file to learn which ledger a name means. That is not hypothetical: the Phase 1 prose sweep renamed nine comments that named OTHER ledgers, every one of them had to be reverted, and one of them had un-fenced the work ledger's directory from the sandbox mask.

What changed (motivation → approach → change)

The store's own vocabulary now matches the name on its package and on disk. Nothing else moves: 1036 lines change and 1033 lines change back, and the three extra lines are one new test.

renamed to
LedgerError CrewLogError
class Ledger class CrewLog
ledger_root / ledger_dir / ledger_path crew_log_root / crew_log_dir / crew_log_path
ledger_executor, _MAX_LEDGER_WORKERS, thread prefix mc-ledger in src/kiro_crew/executors.py crew_log_executor, _MAX_CREW_LOG_WORKERS, mc-crewlog
_ensure_ledger_root in src/kiro_crew/config/paths.py, _cleanup_expired_ledgers in src/kiro_crew/history.py _ensure_crew_log_root, _cleanup_expired_crew_logs
_session_ledger_drain in src/kiro_crew/dashboard/server.py, _remove_session_ledger in src/kiro_crew/dashboard/handlers/sessions.py _crew_log_drain, _remove_session_crew_log
_ledger_model / _ledger_lineage / _ledger_sid / _ledger_turn_no and siblings in src/kiro_crew/dashboard/chat_runner.py _crew_log_*
keyword ledger_kind in src/kiro_crew/llm_helpers.py and its callers src/kiro_crew/dashboard/chat_title.py, src/kiro_crew/dashboard/chat_summary.py, src/kiro_crew/history_consolidation.py; ledger_sid in src/kiro_crew/session_lifecycle.py crew_log_kind, crew_log_sid
_ledger_enabled in src/kiro_crew/acp/_dispatch.py; _ledger() and _MAX_OPEN_LEDGERS in src/kiro_crew/crew_log/emit.py _crew_log_enabled, _crew_log(), _MAX_OPEN_CREW_LOGS
log prefix "session ledger: " in src/kiro_crew/subagent_manager/admission/gate.py, src/kiro_crew/subagent_manager/continuation.py, src/kiro_crew/subagent_manager/terminal.py "crew log: "
crew-log test names and helpers, docs/reference/crew-log/, the three crew-log-* specs crew-log wording

Four names are deliberately kept, because each is a different mechanism or a frozen value:

kept why
CODE_NO_LEDGER and its value "no_ledger" an error code is API surface; errors.py states codes are additive-only and never renamed
session_ledger, work_ledger, ledger_sweep, WaitLedger, the app ledgers different mechanisms, deliberately untouched
SCHEMA_VERSION, entry-type names, header fields, .lease / .lock on-disk format
docs/request-for-change/rfc-append-only-ledger.md external links point at it

Renaming an identifier was done by rewriting NAME tokens only, so no string, comment or docstring could be hit by accident, and the prose was then judged one site at a time. One comment survives on purpose: test_crew_log_emit.py says "injected ledger context" about the WORK ledger's snapshot, which is a different mechanism in a crew-log file.

Free-standing inline comments in chat_runner.py, slack/gateway.py and subagent_manager/ are left alone. Those files host three of the four ledgers, and a sweep there is what went wrong in Phase 1; docstrings, which belong to a named function, were safe to do.

Backwards compatibility

Breaking: every renamed identifier above. No wire value, config key, route, on-disk name or entry type changes, so no stored crew log and no reader of one is affected. Writer sweep on origin/main @ 1ae8f6ee48: every reference to every renamed symbol across src, test, docs and scripts is in this diff. The one match outside it, builtin_skills/kirocrew-dev/prepare-pr/references/rationale.md, is a sentence about a 2026 incident naming the pre-Phase-1 filename test/test_ledger_kinds.py, not a use of any symbol.

One observable string changes: the crew-log writer pool's threads are now named mc-crewlog. Nothing read that name, and test_executors.py now pins it the way it already pins mc-maint, mc-subproc and mc-cron.

Tests

test/test_executors.py::test_thread_name_prefixes_distinguish_pools gains one assertion, pinning the crew-log pool's thread prefix so the rename is a stated contract rather than a silent change. That is the only behavioural line in the diff.

One test names a renamed identifier as a STRING rather than importing it: test/test_chat_runner_early_recovery_actor.py AST-parses chat_runner.py and asserts the turn actor is bound before any try that queues a recovery, so the name it looks for moves with the local.

Every other test is renamed, not rewritten. 2077 tests pass locally across the crew-log suite, the dashboard callers and, and as the regression check that they were not touched, test_session_ledger.py, test_work_ledger.py and test_ledger_sweep.py.

Gates green on the final head: isort, flake8, scripts/check_black_formatting.py, scripts/check_subprocess_encoding.py, scripts/docs_lint.py, and mypy on the 25 source files it reaches (its two remaining errors are pre-existing boto3-stub drift in transcribe.py, which this diff does not touch).

Manual verification

N/A. A rename with no behaviour change, and the one observable string is pinned by a test.

Related Issues

Refs #11549

@chenmingwei23
chenmingwei23 requested review from a team and bolichen97 September 18, 2026 23:01
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 18, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Intent: make this store's identifiers say crew log, the name Phase 1 (#11549) already gave its package, its directory and its docs, so that reading a name tells you which of the four ledgers in this repository it means.

Not a goal: changing any behaviour, any on-disk name, any wire value or any error code; renaming the session work ledger, the taskq wait ledger or the builtin apps' accounting ledgers; sweeping free-standing inline comments in the three files that host several of those ledgers.

@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of ecde316e27cca5b9debdf613340e28c8487460fa — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify no out-of-tree consumers import Ledger/LedgerError from kiro_crew.crew_log — the rename ships no deprecation alias, as the description acknowledges.

[DESIGN-REVIEWED] ecde316

@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of ecde316e27cca5b9debdf613340e28c8487460fa — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify no out-of-repo consumer imports Ledger/LedgerError from PyPI builds — the declared-breaking rename ships no alias and the writer sweep counted only this repo.

What this change ships

Inventory (6 items) — 6 justified

Intent: finish Phase 1's crew-log rename (#11549) so the store's identifiers stop colliding with the repo's four other "ledger" mechanisms — a FIX for a name ambiguity with a recorded prior step (the package/directory already say crew_log on base).

  1. The store's public names now say CrewLog (Ledger→CrewLog, LedgerError→CrewLogError, ledger_root/dir/path→crew_log_*) — justified
  2. Stack dumps show the writer pool's threads as mc-crewlog instead of mc-ledger — justified
  3. Subagent-manager debug lines open with "crew log:" instead of "session ledger:" — justified
  4. Internal helpers and the ledger_kind keyword renamed across dashboard, executors, config, history — justified
  5. One new test assertion pins the mc-crewlog thread prefix — justified
  6. Crew-log specs and reference docs renamed in the same commit — justified

I verified: zero old-name stragglers remain in src/test/docs (grepped LedgerError|ledger_executor|mc-ledger|ledger_kind|ledger_root|_MAX_OPEN_LEDGERS|"session ledger: " — the only hits are WorkLedgerError and the untouched sibling ledgers, ≥4 distinct mechanisms counted); no deleted or weakened test pin; no on-disk, wire, or config value changes. The description's "+3 lines" arithmetic is off (patch is +1070/−1061), but the delta is prose rewrap, not behavior.

[FIRST-PRINCIPLES-REVIEWED] ecde316

@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of ecde316e27cca5b9debdf613340e28c8487460fa and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ecde316

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ecde316e27cca5b9debdf613340e28c8487460fa: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed ecde316e27cca5b9debdf613340e28c8487460fa — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] ecde316

Verdict parsed from the review's SHA-scoped output markers for commit ecde316e27cca5b9debdf613340e28c8487460fa.

False positive or not applicable? A repository writer can comment:
/ai-review override fable ecde316e27cca5b9debdf613340e28c8487460fa: <one-sentence reason>

Phase 1 (#11549) renamed the package, the paths and the user-facing text. The
identifiers stayed, so the code still said ledger for a mechanism the docs and
the disk now call the crew log -- while three other live mechanisms are also
called a ledger.

Renames, behaviour unchanged: LedgerError -> CrewLogError, class Ledger ->
CrewLog, ledger_root/ledger_dir/ledger_path -> crew_log_*, and the caller-side
helpers and locals that name this store. The work ledger, the accounting
ledgers and every frozen wire value keep their names.
@chenmingwei23
chenmingwei23 force-pushed the refactor/crew-log-identifiers-phase2 branch from 6168c35 to ecde316 Compare September 18, 2026 23:40
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 18, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Red classification on ecde316e27 -- both macOS failures are main-owned and already tracked

PR Readiness is success on this head, and the two remaining failures are the only reds on a board of 90. Neither is this PR's. Each is one test in a shard that otherwise passes in full.

macOS Tests / Backend Tests (macOS) (1) -- tracked as #11884

1 failed, 38503 passed.

FAILED test/test_cloud_login_paths.py::TestPrivateLoginDir::test_guard_reads_mode_back_through_bsd_stat_with_bash
AssertionError: refusing to use login directory .../.kirocrew: cannot make it private (mode 0700)

#11884 is open and titled for exactly this: the login-dir guard test refuses a 0700 directory on macOS shard 1 on every PR since #11825. That commit is the last change to the file and is already in this branch's base, so a rebase cannot clear it.

Not this PR's, on three independent grounds: test/test_cloud_login_paths.py and the cloud login source are absent from this diff; the file contains zero occurrences of any identifier this PR renames; and the test passes on Linux at this exact head, so the failure is platform-specific rather than rename-related.

macOS Tests / Backend Tests (macOS) (3) -- tracked as #11918

1 failed, 37360 passed.

FAILED test/test_theme_install.py::TestCopyInstalledTheme::test_dest_case_variant_ancestor_rejected_on_case_insensitive_fs
AssertionError: assert ('refusing to install unreadable/unsafe file: theme.json' is not None
  and 'inside the install destination' in 'refusing to install unreadable/unsafe file: theme.json')

#11918 is open and describes this assertion precisely: the case-variant ancestor test hits the unsafe-file refusal before reaching the #11704 guard it is asserting on. #11704 is likewise the file's last change and is already in this base.

Same three grounds: the theme test and the theme install source are absent from this diff; zero renamed identifiers in the file; and the test is skipped on Linux because it requires a case-insensitive filesystem, so it only ever executes on macOS and cannot be reached by anything in a rename of Python identifiers.

What changed since the previous head

The two macOS families that were red on 6168c35f4d are gone from this board: the xdist worker-budget group (#11618) and the ACP launch goldens group (#11635). Both were cleared by main-side fixes without a push here, which is the expected behaviour when CI measures the merge ref.

Rest of the board

All 8 Linux and all 8 Windows backend shards pass, Backend Tests (Windows) (1) included after its attempt-2 rerun cleared a cancel-and-recover flake. GPT 5.6, Opus 4.8, Design Review and First Principles Review are all green and fresh on this head with zero blocking findings, and there are no unresolved review threads. Coverage Gate, Testpaths Coverage Gate and PR Readiness are green.

No push accompanies this comment: neither red can be changed from this branch, and a new head would re-roll four passing review lanes for nothing.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition: the no-alias question from Design and First Principles, and a correction to my own description

Both lanes PASS on ecde316e27 and both ask the same thing, so it gets one answer: verify no out-of-tree consumer imports Ledger / LedgerError, because this rename ships no deprecation alias.

The question is well-formed rather than spurious, and worth saying so first. On the base commit these really are exported names, not private ones: crew_log/__init__.py sets __all__ = sorted(_EXPORTS), and _EXPORTS maps "Ledger" to store and "LedgerError" to errors. A reviewer is right to ask who could be holding them.

Three facts answer it.

No released artifact has ever exposed the import path. Of the 79 v* release tags in this repository, zero contain src/kiro_crew/crew_log/. So from kiro_crew.crew_log import Ledger is not importable from any published version, which is the only way an out-of-repo consumer could have acquired it.

The path is 25 hours old. kiro_crew.crew_log came into existence with Phase 1 (#11549, merged 2026-09-18T00:29Z). Nothing outside this repository has had a release to write against, and a consumer would have had to pin an unreleased commit from the last day.

The aliasing decision was already made at Phase 1 and merged. That commit deleted src/kiro_crew/ledger/__init__.py outright, 158 lines, with no shim; kiro_crew/ledger has zero entries on main today. Any out-of-tree importer was broken then, by the module path, not now by the class name inside it. Adding an alias here would preserve a class name at a path no released consumer can import, while the path break it sits behind stays unaliased -- which is less consistent than shipping neither, not more.

In-repo coverage is already on the record: the First Principles lane ran its own sweep and reports zero old-name stragglers across src, test and docs, with the only hits being WorkLedgerError and the untouched sibling mechanisms.

Correction to the description

First Principles is right that the arithmetic in the body is off, and the specific number is worth stating. The body says "1036 lines change and 1033 lines change back, and the three extra lines are one new test". That was true of the first head, 6168c35f4d, at 56 files. It went stale on the second push: this head is 57 files, +1070 / -1061, so the net is +9, not +3. The extra six are the follow-up fix itself -- a test that names the renamed identifier as a quoted string, plus two documentation references.

The substance the sentence was making -- that the only behavioural line in the diff is the one new mc-crewlog thread-prefix assertion -- is unchanged, and the lane reached the same conclusion independently.

I am leaving the body as it stands rather than editing it, and the reason is mechanical: codex-review.yml and code-review.yml both list edited in their pull_request types, so editing the description re-rolls the GPT lane. Trading a passing non-deterministic review verdict for a corrected line count on an otherwise green board is the wrong side of that bargain. The correct figures are here instead, where they are visible next to the claim they fix.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved after verification: PR Readiness success on this head, no active change requests or unresolved threads, mergeable against current main.

@bolichen97
bolichen97 merged commit 88537a9 into main Sep 19, 2026
126 of 129 checks passed
@bolichen97
bolichen97 deleted the refactor/crew-log-identifiers-phase2 branch September 19, 2026 05:03
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 19, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…kirodotdev#11907)

Phase 1 (kirodotdev#11549) renamed the package, the paths and the user-facing text. The
identifiers stayed, so the code still said ledger for a mechanism the docs and
the disk now call the crew log -- while three other live mechanisms are also
called a ledger.

Renames, behaviour unchanged: LedgerError -> CrewLogError, class Ledger ->
CrewLog, ledger_root/ledger_dir/ledger_path -> crew_log_*, and the caller-side
helpers and locals that name this store. The work ledger, the accounting
ledgers and every frozen wire value keep their names.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants