docs(roadmap): readability & modernization analysis loop by donbeave · Pull Request #182 · jackin-project/jackin

donbeave · 2026-04-26T02:34:41Z

Summary

Establishes docs/internal/roadmap/ (new directory — does not ship to public docs site)
Delivers a living readability & modernization roadmap produced by an iterative analysis loop, updated after each iteration
Analysis only: zero bytes changed in src/, tests/, docs/src/, .github/, or Cargo.toml

What's in iteration 1

READABILITY_AND_MODERNIZATION.md covers §0–§10:

§1 Project inventory — 72 .rs files, ~40,664 lines, verified line counts for 24 hot-spot files, rustdoc //! coverage estimate (~28%), Astro/Starlight TypeScript strictness gap identified
§2 Concept-to-location index — 25 concepts, each with current location + findability rating + proposed post-refactor location; sources verified in code or PR feat(tui): workspace manager TUI (PR 3 of 3) #171 branch
§3 Documentation hierarchy — diagnosis of root-level markdown sprawl, proposed docs/internal/ shape, Mermaid link graphs for current and proposed state
§4 Source-code structural diagnosis — single-crate recommendation (grounded in ~40k LOC vs workspace threshold), 7 module-shape rules with named violators, proposed splits for runtime/launch.rs (2368L) and operator_env.rs (1569L)
§5 Naming candidates — 15 confirmed candidates with rationale and recommendations
§6 CI/tooling analysis — per-workflow diagnosis, Justfile scope, build.rs, docker-bake.hcl, MSRV discrepancy flagged
§7 Modernization candidates — 13 entries, each with 2–3 alternatives evaluated and a adopt/defer/reject verdict
§8 AI-agent workflow — intent-driven/spec-driven development landscape, superpowers alternatives mapped to a hand-rolled docs/internal/agent-skills/ approach, public/internal docs boundary contract
§9 Risks & open questions — 5 execution risks, 6 open questions for future iterations
§10 Execution sequencing — 7 ordered steps with failure modes

_research_notes.md — sources with retrieval dates for error handling, TUI testing, spec-driven dev, superpowers alternatives, workspace vs single-crate, mutation testing.

_iteration_log.md — confidence assessment per section, weakest sections identified for iteration 2.

Test plan

Verify git diff main...HEAD --name-only lists only the three roadmap files
Review READABILITY_AND_MODERNIZATION.md for any recommendation lacking an alternatives comparison
Review _iteration_log.md for honest confidence assessment

🤖 Generated with Claude Code

Full first draft of READABILITY_AND_MODERNIZATION.md covering §0–§10: project inventory (72 files, 40k LOC), concept-to-location index (25 entries), documentation hierarchy proposal, source-code structural diagnosis (single-crate recommendation, 7 module-shape rules, hot-spot list), naming candidates, CI/tooling analysis, modernization candidates (13 entries with alternatives comparisons), AI-agent workflow (§8.1–§8.3: spec-driven development, superpowers alternatives, docs boundary), risks, and execution sequencing. All claims grounded in direct code reading (cited file paths and line ranges). All crate/tool recommendations include 2–3 alternatives. PR #171 branch read for AgentPicker, OpStructRunner, RawOpField, and RULES.md additions. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

…preview workflow Four concrete improvements over iteration 1: - §4: Deep-read src/runtime/launch.rs (2368L) in full; mapped every function to exact line ranges and dependency graph; refined split proposal into 4 files (launch.rs ~120L, launch_pipeline.rs ~560L prod + 1200L tests, terminfo.rs ~110L, trust.rs ~60L); key finding: test module (1282L) exceeds production code (1083L). - §7.11: Discovered docs/AGENTS.md documents both TypeScript strictness blockers explicitly (rainEngine indexed access + astro-og-canvas optional-property types); verified rainEngine.ts at 5 line locations; rewrote recommendation as a concrete 4-step fix plan. - §6: Read preview.yml in full — Homebrew tap rolling-preview pipeline; flagged missing contributor documentation; resolved OQ3. - §2 concepts 4 & 6: Exact PR #171 data — TICK_MS=50 at console/mod.rs:90 with 20Hz rationale; compile-time safety test is an exhaustive struct destructure (not trybuild) at operator_env.rs:2055–2096. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

…tests, OQ7 Three concrete improvements over iteration 2: - §4: Deep-read src/operator_env.rs (1569L); mapped every function to exact line ranges; identified two distinct clusters (op CLI subprocess layer lines 96-364 vs env layer resolution lines 365-808) with ~90L connective tissue; proposed module-directory split into mod.rs (~100L), client.rs (~280L), layers.rs (~470L), picker.rs (~250L PR#171); dependency graph shows no circular imports. - §7.5: Named first 3 concrete snapshot test targets with file:line citations — render_sentinel_description_pane (list.rs:306, zero state, ~10L), render_tab_strip (editor.rs:180, 4 enum variants, ~20L), render_mounts_subpanel (list.rs:408, 3 data-driven cases, ~30L). - OQ7 resolved: docs/package.json confirms astro-og-canvas ^0.11.1; docs/src/pages/og/[...slug].png.ts:~35 has `logo: undefined` which is the exact exactOptionalPropertyTypes conflict; fix is one line (omit the property). §7.11 and §9 updated accordingly. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

…stdoc coverage Two concrete improvements: - §4: Deep-read config/editor.rs (1467L); key finding: production code is only 503L (lines 1-503), tests are 963L (lines 504-1467 — nearly 2x); mapped all 18 public methods with exact line ranges into 5 domain groups; flagged create_workspace/edit_workspace validation-first architectural pattern as a refactor-preserve invariant; proposed 6-file module-directory split; priority note: lower than launch.rs/operator_env.rs since production code is already a reasonable size. - §1/§4/§7.6: Corrected rustdoc coverage from estimate "~28%" to exact count 37/90 files = 41%; identified cluster: console/manager/ and console/widgets/ (PR #171 additions) are well-covered; runtime/, app/, cli/ lag; updated all three occurrences consistently. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

… ordering, §5 pruning Three concrete improvements: - §8.2: Added 17-line concrete docs/internal/agent-skills/brainstorm.md template with 6 fields (Purpose/When/Steps/Outputs/Done when/Overlap guard). The Done-when and Overlap-guard fields are the discipline gates missing from superpowers default brainstorming. Makes §8.2 immediately actionable instead of aspirational. - §10 step 4: Refined split ordering from sketch to priority-grounded sequence: config/types (4a) → manifest (4b) → config/editor 503L (4c) → operator_env 810L (4d) → app/dispatch (4e) → runtime/launch 1083L (4f last). Each sub-step has architectural notes and what-could-go-wrong. Flags the operator_env circular-dependency check for layers.rs→client.rs. - §5: Replaced 3 "leave as is" non-candidates (rows 10, 12, 15) with verified candidates from code reading: provision_claude_auth→apply_auth_forward (auth.rs:17), AuthProvisionOutcome→AuthForwardOutcome (instance/mod.rs), spawn_wait_thread→spawn_exit_watcher (operator_env.rs:202). - OQ5 resolved: instance/auth.rs read — only 210L production code, 585L tests (3x); no split needed; removed from hot-spot concern. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

…he, logging Four improvements: - §1: Hot-spot table rebuilt with production/test LOC split columns for all 22 files. Key finding: manifest/validate.rs is 145L prod/816L tests (exemplary testing, not a god file); app/mod.rs is 928L prod/22L tests (most genuine god file after launch.rs). Adds Priority column. - §8: Operator prefers existing tools over hand-rolled skill files. §8.1 recommendation pivots from hand-rolled (Option C) to cc-sdd (Option B). §8.2 rewrites comparison table — cc-sdd covers spec/plan/execute; TDD/debugging/review covered by existing project docs (TESTING.md, open-review-findings.mdx). Removes custom brainstorm template from iteration 5; no docs/internal/agent-skills/ dir needed. - §2 concept 14: Session-scoped op cache confirmed at src/console/op_cache.rs (252L, all production, no tests). Full detail: BTreeMap keyed by (account, vault_id, item_id) tuples, DEFAULT_ACCOUNT_KEY sentinel, invalidation methods, //! doc confirms metadata-only guarantee. - §7.14: New modernization entry — structured logging (log vs tracing vs current eprintln! approach). Recommendation: defer. Research in _research_notes.md. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

…ate full entry Five concrete improvements: - §8.1/§8.3/§3: Operator direction — specs become public Starlight MDX pages at docs/src/content/docs/specs/ (draft: true while in-progress), not in docs/internal/specs/. Living source of truth updated with each code change. §8.3 boundary contract rewritten for public-spec model. §3 target shape updated to remove internal specs/ and add public specs/. - §9 R1: Corrected from "circular import risk" to "compilation-at-distance risk". Verified by grep: config imports workspace (config/mod.rs:1,5,6) but workspace does NOT import config. One-way dep: config → workspace. No circular risk; real risk is 30+ use path updates when AppConfig moves. - §10 step 2: Rewritten to match cc-sdd + Starlight MDX approach (was still describing hand-rolled docs/internal/agent-skills/ from pre- iteration-6 recommendation). Added draft page / lychee link-check caveat. - §7.13 Renovate: Full six-subheading entry replacing 2-sentence stub. Evaluated Dependabot and Renovate Cloud App; both rejected due to DCO sign-off constraint (RENOVATE_GIT_AUTHOR env var in renovate.yml:26 is not replicable in either alternative). Two low-cost tunings named. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

… correction Three improvements: - §8.1: Draft-page lychee constraint verified from docs/lychee.toml (full read). exclude_path has only 404.html pattern — no draft exclusion. Starlight draft pages exist in dist/ and are scanned by PR-time lychee check. Two fix options added: keep specs link-free, or add exclude pattern to lychee.toml. Added Astro sidebar requirement: manual config at astro.config.ts:50-103; autogenerate{ directory: 'specs' } pattern. - §2 concept 18: Corrected a wrong proposed move. AuthForwardMode → instance/auth.rs was incorrect — the type is used in 9 files, is a config field at config/mod.rs:89,96, and has serde Deserialize at line 74. Moving to instance/ would create circular dep. Corrected to: correctly placed, will move intra-module to config/types.rs in §10 4a. - §4 AuthForwardMode false alarm closed: confirmed NOT a §4 Rule 3 violation. Type is correctly in config because it IS a config value. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

…4a serde note - §7.14: grep-verified 96 production eprintln! calls across 16 files; breakdown by file; no rogue debug calls found, flip condition has not triggered - §2 concept 8: full 4-hop load chain with exact line numbers; documents the /__/ separator invariant in runtime_slug that prevents namespace collisions; CODE_TOUR column now specifies what the tour entry must explain - §10 step 4a: confirms AuthForwardMode serde impl is a plain impl<'de> block (not a derive), moves with the type to config/types.rs automatically Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

…e, //! exemplar - §5 row 6: dispatch_value → resolve_env_value rename is 1 prod + 6 test call sites in a single file — lowest-cost rename in the table - §7.13: adds minimal safe automerge pattern for lockFileMaintenance only; explicitly excludes patch/minor bumps and SHA-pinned Actions - §4 Rule 7: expands //! exemplar analysis with direct quotes from env_model.rs:1-17 and isolates the three-element pattern Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

READABILITY_AND_MODERNIZATION.md now presents a clean final view: - Remove all "(iteration N)", "(verified iteration N)", "read in full for iteration N", "updated iteration N" qualifiers throughout the body - Remove the Iteration counter from §0 meta - Resolved OQ markers simplified from "(resolved in iteration N)" to "(resolved)"; deferred OQ markers from "Tracked for iteration N" to "Deferred" _iteration_log.md now has entries in chronological order 1–10: - Was: 1, 3, 4, 5, 6, 7, 10, 8, 9, 2 - Now: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

_research_notes.md: - OpenSpec (Fission-AI/OpenSpec): brownfield-first SDD, three-phase propose/apply/archive, delta markers (ADDED/MODIFIED/REMOVED), living specs at openspec/specs/; /loop-compatible; recommended as cc-sdd complement for §4 module-split proposals - IIKit (intent-integrity-chain/kit): cryptographic .feature hash-locking, 8-phase workflow, Gherkin BDD chain, Tessl-only install; not recommended for jackin (no Gherkin step runner, Tessl lock-in, heavyweight for single-maintainer) READABILITY_AND_MODERNIZATION.md §8.1: - Adds Options E (OpenSpec) and F (IIKit) to the landscape and evaluation table with brownfield delta tracking and Rust/nextest compatibility rows - Adds OpenSpec complement note after the cc-sdd recommendation Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

…shot targets - §7.7 / §2 concept 25 / §10 step 3: correct false claim that dtolnay/rust-toolchain reads rust-toolchain.toml; action version is encoded in SHA rev; three sources require manual sync - §6 ci.yml row: expand from high-level to exact job steps; document gaps (no MSRV job, floating tags in build-validator, no doc job, main jackin binary never compiled in CI) - §7.9: grep-confirm all three snapshot target fn names; add exact signatures and private-fn access pattern (use super::*) with list.rs:720 as existing proof Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

- §5 row 5: ClassSelector → AgentClass rename is 138 prod call sites across 17 files — highest-scope rename in the table - §7.8: full lint table enumeration from Cargo.toml:47-75; notes that cast allowances are global despite TUI-scoped inline comment - §4 4e: app/mod.rs run() read in full; refined split from 1 file to 3 (dispatch.rs ~167L, workspace_cmd.rs ~438L, config_cmd.rs ~220L) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

Keep only forward-looking actionable proposals: §2 concept table: removed 6 rows with "Stable"/"No change needed" proposals (RULES.md keybindings, hardline, mount planning, XDG paths, Docker builder, env-var ordering); renumbered 1-19 §5 naming table: removed hardline_agent row (leave-as-is, no action); rephrased load_agent row to focus on the //! doc action not the rename; renumbered to 1-14 §9 open questions: removed OQ3 (preview.yml, resolved — in §6), OQ5 (auth.rs split, resolved — no split needed), OQ7 (astro-og-canvas, resolved — fix in §7.11); renumbered to OQ1-4; merged TS strictness OQ back into the active list Cleanup: removed "resolved OQ5" tag from auth.rs hot-spot entry; removed "(resolved OQ7)" qualifier from §7.11 blocker label Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

Remove all "after PR #171 merges", "PR #171 branch", "pre-merge", and "not yet on main" qualifiers throughout. Specific changes: - §0: update baseline note from "treated as merged" to "now merged" - §1: remove branch-only qualifiers from file tree, module map, coverage count - §2: concept rows 1, 2, 4, 5, 6, 10, 11, 12, 14, 15 updated to reflect code now on main; row 12 op_cache current-state rating updated from requires-tribal-knowledge (pre-merge) to requires-grep (post-merge) - OQ1 (op_picker cache): updated from "deferred" to "read from main now" - §4, §5, §7: remove "(PR #171)" and "adds/branch" language - §10 step 1: remove "once PR #171 merges" condition Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 1 — readability & modernization analysis Full first draft of READABILITY_AND_MODERNIZATION.md covering §0–§10: project inventory (72 files, 40k LOC), concept-to-location index (25 entries), documentation hierarchy proposal, source-code structural diagnosis (single-crate recommendation, 7 module-shape rules, hot-spot list), naming candidates, CI/tooling analysis, modernization candidates (13 entries with alternatives comparisons), AI-agent workflow (§8.1–§8.3: spec-driven development, superpowers alternatives, docs boundary), risks, and execution sequencing. All claims grounded in direct code reading (cited file paths and line ranges). All crate/tool recommendations include 2–3 alternatives. PR #171 branch read for AgentPicker, OpStructRunner, RawOpField, and RULES.md additions. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 2 — launch.rs deep analysis, TS strictness, preview workflow Four concrete improvements over iteration 1: - §4: Deep-read src/runtime/launch.rs (2368L) in full; mapped every function to exact line ranges and dependency graph; refined split proposal into 4 files (launch.rs ~120L, launch_pipeline.rs ~560L prod + 1200L tests, terminfo.rs ~110L, trust.rs ~60L); key finding: test module (1282L) exceeds production code (1083L). - §7.11: Discovered docs/AGENTS.md documents both TypeScript strictness blockers explicitly (rainEngine indexed access + astro-og-canvas optional-property types); verified rainEngine.ts at 5 line locations; rewrote recommendation as a concrete 4-step fix plan. - §6: Read preview.yml in full — Homebrew tap rolling-preview pipeline; flagged missing contributor documentation; resolved OQ3. - §2 concepts 4 & 6: Exact PR #171 data — TICK_MS=50 at console/mod.rs:90 with 20Hz rationale; compile-time safety test is an exhaustive struct destructure (not trybuild) at operator_env.rs:2055–2096. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 3 — operator_env.rs deep analysis, snapshot tests, OQ7 Three concrete improvements over iteration 2: - §4: Deep-read src/operator_env.rs (1569L); mapped every function to exact line ranges; identified two distinct clusters (op CLI subprocess layer lines 96-364 vs env layer resolution lines 365-808) with ~90L connective tissue; proposed module-directory split into mod.rs (~100L), client.rs (~280L), layers.rs (~470L), picker.rs (~250L PR#171); dependency graph shows no circular imports. - §7.5: Named first 3 concrete snapshot test targets with file:line citations — render_sentinel_description_pane (list.rs:306, zero state, ~10L), render_tab_strip (editor.rs:180, 4 enum variants, ~20L), render_mounts_subpanel (list.rs:408, 3 data-driven cases, ~30L). - OQ7 resolved: docs/package.json confirms astro-og-canvas ^0.11.1; docs/src/pages/og/[...slug].png.ts:~35 has `logo: undefined` which is the exact exactOptionalPropertyTypes conflict; fix is one line (omit the property). §7.11 and §9 updated accordingly. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 4 — config/editor.rs deep analysis, exact rustdoc coverage Two concrete improvements: - §4: Deep-read config/editor.rs (1467L); key finding: production code is only 503L (lines 1-503), tests are 963L (lines 504-1467 — nearly 2x); mapped all 18 public methods with exact line ranges into 5 domain groups; flagged create_workspace/edit_workspace validation-first architectural pattern as a refactor-preserve invariant; proposed 6-file module-directory split; priority note: lower than launch.rs/operator_env.rs since production code is already a reasonable size. - §1/§4/§7.6: Corrected rustdoc coverage from estimate "~28%" to exact count 37/90 files = 41%; identified cluster: console/manager/ and console/widgets/ (PR #171 additions) are well-covered; runtime/, app/, cli/ lag; updated all three occurrences consistently. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 5 — concrete brainstorm template, §10 step 4 ordering, §5 pruning Three concrete improvements: - §8.2: Added 17-line concrete docs/internal/agent-skills/brainstorm.md template with 6 fields (Purpose/When/Steps/Outputs/Done when/Overlap guard). The Done-when and Overlap-guard fields are the discipline gates missing from superpowers default brainstorming. Makes §8.2 immediately actionable instead of aspirational. - §10 step 4: Refined split ordering from sketch to priority-grounded sequence: config/types (4a) → manifest (4b) → config/editor 503L (4c) → operator_env 810L (4d) → app/dispatch (4e) → runtime/launch 1083L (4f last). Each sub-step has architectural notes and what-could-go-wrong. Flags the operator_env circular-dependency check for layers.rs→client.rs. - §5: Replaced 3 "leave as is" non-candidates (rows 10, 12, 15) with verified candidates from code reading: provision_claude_auth→apply_auth_forward (auth.rs:17), AuthProvisionOutcome→AuthForwardOutcome (instance/mod.rs), spawn_wait_thread→spawn_exit_watcher (operator_env.rs:202). - OQ5 resolved: instance/auth.rs read — only 210L production code, 585L tests (3x); no split needed; removed from hot-spot concern. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 6 — hot-spot splits, §8 cc-sdd pivot, op_cache, logging Four improvements: - §1: Hot-spot table rebuilt with production/test LOC split columns for all 22 files. Key finding: manifest/validate.rs is 145L prod/816L tests (exemplary testing, not a god file); app/mod.rs is 928L prod/22L tests (most genuine god file after launch.rs). Adds Priority column. - §8: Operator prefers existing tools over hand-rolled skill files. §8.1 recommendation pivots from hand-rolled (Option C) to cc-sdd (Option B). §8.2 rewrites comparison table — cc-sdd covers spec/plan/execute; TDD/debugging/review covered by existing project docs (TESTING.md, open-review-findings.mdx). Removes custom brainstorm template from iteration 5; no docs/internal/agent-skills/ dir needed. - §2 concept 14: Session-scoped op cache confirmed at src/console/op_cache.rs (252L, all production, no tests). Full detail: BTreeMap keyed by (account, vault_id, item_id) tuples, DEFAULT_ACCOUNT_KEY sentinel, invalidation methods, //! doc confirms metadata-only guarantee. - §7.14: New modernization entry — structured logging (log vs tracing vs current eprintln! approach). Recommendation: defer. Research in _research_notes.md. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 7 — MDX specs, §9 dep graph fix, §7.13 Renovate full entry Five concrete improvements: - §8.1/§8.3/§3: Operator direction — specs become public Starlight MDX pages at docs/src/content/docs/specs/ (draft: true while in-progress), not in docs/internal/specs/. Living source of truth updated with each code change. §8.3 boundary contract rewritten for public-spec model. §3 target shape updated to remove internal specs/ and add public specs/. - §9 R1: Corrected from "circular import risk" to "compilation-at-distance risk". Verified by grep: config imports workspace (config/mod.rs:1,5,6) but workspace does NOT import config. One-way dep: config → workspace. No circular risk; real risk is 30+ use path updates when AppConfig moves. - §10 step 2: Rewritten to match cc-sdd + Starlight MDX approach (was still describing hand-rolled docs/internal/agent-skills/ from pre- iteration-6 recommendation). Added draft page / lychee link-check caveat. - §7.13 Renovate: Full six-subheading entry replacing 2-sentence stub. Evaluated Dependabot and Renovate Cloud App; both rejected due to DCO sign-off constraint (RENOVATE_GIT_AUTHOR env var in renovate.yml:26 is not replicable in either alternative). Two low-cost tunings named. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 8 — lychee draft-page constraint, concept 18 correction Three improvements: - §8.1: Draft-page lychee constraint verified from docs/lychee.toml (full read). exclude_path has only 404.html pattern — no draft exclusion. Starlight draft pages exist in dist/ and are scanned by PR-time lychee check. Two fix options added: keep specs link-free, or add exclude pattern to lychee.toml. Added Astro sidebar requirement: manual config at astro.config.ts:50-103; autogenerate{ directory: 'specs' } pattern. - §2 concept 18: Corrected a wrong proposed move. AuthForwardMode → instance/auth.rs was incorrect — the type is used in 9 files, is a config field at config/mod.rs:89,96, and has serde Deserialize at line 74. Moving to instance/ would create circular dep. Corrected to: correctly placed, will move intra-module to config/types.rs in §10 4a. - §4 AuthForwardMode false alarm closed: confirmed NOT a §4 Rule 3 violation. Type is correctly in config because it IS a config value. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 9 — eprintln count, CODE_TOUR content, step 4a serde note - §7.14: grep-verified 96 production eprintln! calls across 16 files; breakdown by file; no rogue debug calls found, flip condition has not triggered - §2 concept 8: full 4-hop load chain with exact line numbers; documents the /__/ separator invariant in runtime_slug that prevents namespace collisions; CODE_TOUR column now specifies what the tour entry must explain - §10 step 4a: confirms AuthForwardMode serde impl is a plain impl<'de> block (not a derive), moves with the type to config/types.rs automatically Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 10 — dispatch_value scope, Renovate automerge, //! exemplar - §5 row 6: dispatch_value → resolve_env_value rename is 1 prod + 6 test call sites in a single file — lowest-cost rename in the table - §7.13: adds minimal safe automerge pattern for lockFileMaintenance only; explicitly excludes patch/minor bumps and SHA-pinned Actions - §4 Rule 7: expands //! exemplar analysis with direct quotes from env_model.rs:1-17 and isolates the three-element pattern Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): strip iteration annotations; reorder log chronologically READABILITY_AND_MODERNIZATION.md now presents a clean final view: - Remove all "(iteration N)", "(verified iteration N)", "read in full for iteration N", "updated iteration N" qualifiers throughout the body - Remove the Iteration counter from §0 meta - Resolved OQ markers simplified from "(resolved in iteration N)" to "(resolved)"; deferred OQ markers from "Tracked for iteration N" to "Deferred" _iteration_log.md now has entries in chronological order 1–10: - Was: 1, 3, 4, 5, 6, 7, 10, 8, 9, 2 - Now: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): research OpenSpec and IIKit; update §8 landscape _research_notes.md: - OpenSpec (Fission-AI/OpenSpec): brownfield-first SDD, three-phase propose/apply/archive, delta markers (ADDED/MODIFIED/REMOVED), living specs at openspec/specs/; /loop-compatible; recommended as cc-sdd complement for §4 module-split proposals - IIKit (intent-integrity-chain/kit): cryptographic .feature hash-locking, 8-phase workflow, Gherkin BDD chain, Tessl-only install; not recommended for jackin (no Gherkin step runner, Tessl lock-in, heavyweight for single-maintainer) READABILITY_AND_MODERNIZATION.md §8.1: - Adds Options E (OpenSpec) and F (IIKit) to the landscape and evaluation table with brownfield delta tracking and Rust/nextest compatibility rows - Adds OpenSpec complement note after the cc-sdd recommendation Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 11 — dtolnay correction, ci.yml detail, snapshot targets - §7.7 / §2 concept 25 / §10 step 3: correct false claim that dtolnay/rust-toolchain reads rust-toolchain.toml; action version is encoded in SHA rev; three sources require manual sync - §6 ci.yml row: expand from high-level to exact job steps; document gaps (no MSRV job, floating tags in build-validator, no doc job, main jackin binary never compiled in CI) - §7.9: grep-confirm all three snapshot target fn names; add exact signatures and private-fn access pattern (use super::*) with list.rs:720 as existing proof Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 12 — ClassSelector scope, lint table, app split - §5 row 5: ClassSelector → AgentClass rename is 138 prod call sites across 17 files — highest-scope rename in the table - §7.8: full lint table enumeration from Cargo.toml:47-75; notes that cast allowances are global despite TUI-scoped inline comment - §4 4e: app/mod.rs run() read in full; refined split from 1 file to 3 (dispatch.rs ~167L, workspace_cmd.rs ~438L, config_cmd.rs ~220L) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): remove resolved/no-action items from roadmap Keep only forward-looking actionable proposals: §2 concept table: removed 6 rows with "Stable"/"No change needed" proposals (RULES.md keybindings, hardline, mount planning, XDG paths, Docker builder, env-var ordering); renumbered 1-19 §5 naming table: removed hardline_agent row (leave-as-is, no action); rephrased load_agent row to focus on the //! doc action not the rename; renumbered to 1-14 §9 open questions: removed OQ3 (preview.yml, resolved — in §6), OQ5 (auth.rs split, resolved — no split needed), OQ7 (astro-og-canvas, resolved — fix in §7.11); renumbered to OQ1-4; merged TS strictness OQ back into the active list Cleanup: removed "resolved OQ5" tag from auth.rs hot-spot entry; removed "(resolved OQ7)" qualifier from §7.11 blocker label Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): update analysis baseline — PR #171 now merged to main Remove all "after PR #171 merges", "PR #171 branch", "pre-merge", and "not yet on main" qualifiers throughout. Specific changes: - §0: update baseline note from "treated as merged" to "now merged" - §1: remove branch-only qualifiers from file tree, module map, coverage count - §2: concept rows 1, 2, 4, 5, 6, 10, 11, 12, 14, 15 updated to reflect code now on main; row 12 op_cache current-state rating updated from requires-tribal-knowledge (pre-merge) to requires-grep (post-merge) - OQ1 (op_picker cache): updated from "deferred" to "read from main now" - §4, §5, §7: remove "(PR #171)" and "adds/branch" language - §10 step 1: remove "once PR #171 merges" condition Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> --------- Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* docs(roadmap): iteration 1 — readability & modernization analysis Full first draft of READABILITY_AND_MODERNIZATION.md covering §0–§10: project inventory (72 files, 40k LOC), concept-to-location index (25 entries), documentation hierarchy proposal, source-code structural diagnosis (single-crate recommendation, 7 module-shape rules, hot-spot list), naming candidates, CI/tooling analysis, modernization candidates (13 entries with alternatives comparisons), AI-agent workflow (§8.1–§8.3: spec-driven development, superpowers alternatives, docs boundary), risks, and execution sequencing. All claims grounded in direct code reading (cited file paths and line ranges). All crate/tool recommendations include 2–3 alternatives. PR #171 branch read for AgentPicker, OpStructRunner, RawOpField, and RULES.md additions. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 2 — launch.rs deep analysis, TS strictness, preview workflow Four concrete improvements over iteration 1: - §4: Deep-read src/runtime/launch.rs (2368L) in full; mapped every function to exact line ranges and dependency graph; refined split proposal into 4 files (launch.rs ~120L, launch_pipeline.rs ~560L prod + 1200L tests, terminfo.rs ~110L, trust.rs ~60L); key finding: test module (1282L) exceeds production code (1083L). - §7.11: Discovered docs/AGENTS.md documents both TypeScript strictness blockers explicitly (rainEngine indexed access + astro-og-canvas optional-property types); verified rainEngine.ts at 5 line locations; rewrote recommendation as a concrete 4-step fix plan. - §6: Read preview.yml in full — Homebrew tap rolling-preview pipeline; flagged missing contributor documentation; resolved OQ3. - §2 concepts 4 & 6: Exact PR #171 data — TICK_MS=50 at console/mod.rs:90 with 20Hz rationale; compile-time safety test is an exhaustive struct destructure (not trybuild) at operator_env.rs:2055–2096. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 3 — operator_env.rs deep analysis, snapshot tests, OQ7 Three concrete improvements over iteration 2: - §4: Deep-read src/operator_env.rs (1569L); mapped every function to exact line ranges; identified two distinct clusters (op CLI subprocess layer lines 96-364 vs env layer resolution lines 365-808) with ~90L connective tissue; proposed module-directory split into mod.rs (~100L), client.rs (~280L), layers.rs (~470L), picker.rs (~250L PR#171); dependency graph shows no circular imports. - §7.5: Named first 3 concrete snapshot test targets with file:line citations — render_sentinel_description_pane (list.rs:306, zero state, ~10L), render_tab_strip (editor.rs:180, 4 enum variants, ~20L), render_mounts_subpanel (list.rs:408, 3 data-driven cases, ~30L). - OQ7 resolved: docs/package.json confirms astro-og-canvas ^0.11.1; docs/src/pages/og/[...slug].png.ts:~35 has `logo: undefined` which is the exact exactOptionalPropertyTypes conflict; fix is one line (omit the property). §7.11 and §9 updated accordingly. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 4 — config/editor.rs deep analysis, exact rustdoc coverage Two concrete improvements: - §4: Deep-read config/editor.rs (1467L); key finding: production code is only 503L (lines 1-503), tests are 963L (lines 504-1467 — nearly 2x); mapped all 18 public methods with exact line ranges into 5 domain groups; flagged create_workspace/edit_workspace validation-first architectural pattern as a refactor-preserve invariant; proposed 6-file module-directory split; priority note: lower than launch.rs/operator_env.rs since production code is already a reasonable size. - §1/§4/§7.6: Corrected rustdoc coverage from estimate "~28%" to exact count 37/90 files = 41%; identified cluster: console/manager/ and console/widgets/ (PR #171 additions) are well-covered; runtime/, app/, cli/ lag; updated all three occurrences consistently. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 5 — concrete brainstorm template, §10 step 4 ordering, §5 pruning Three concrete improvements: - §8.2: Added 17-line concrete docs/internal/agent-skills/brainstorm.md template with 6 fields (Purpose/When/Steps/Outputs/Done when/Overlap guard). The Done-when and Overlap-guard fields are the discipline gates missing from superpowers default brainstorming. Makes §8.2 immediately actionable instead of aspirational. - §10 step 4: Refined split ordering from sketch to priority-grounded sequence: config/types (4a) → manifest (4b) → config/editor 503L (4c) → operator_env 810L (4d) → app/dispatch (4e) → runtime/launch 1083L (4f last). Each sub-step has architectural notes and what-could-go-wrong. Flags the operator_env circular-dependency check for layers.rs→client.rs. - §5: Replaced 3 "leave as is" non-candidates (rows 10, 12, 15) with verified candidates from code reading: provision_claude_auth→apply_auth_forward (auth.rs:17), AuthProvisionOutcome→AuthForwardOutcome (instance/mod.rs), spawn_wait_thread→spawn_exit_watcher (operator_env.rs:202). - OQ5 resolved: instance/auth.rs read — only 210L production code, 585L tests (3x); no split needed; removed from hot-spot concern. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 6 — hot-spot splits, §8 cc-sdd pivot, op_cache, logging Four improvements: - §1: Hot-spot table rebuilt with production/test LOC split columns for all 22 files. Key finding: manifest/validate.rs is 145L prod/816L tests (exemplary testing, not a god file); app/mod.rs is 928L prod/22L tests (most genuine god file after launch.rs). Adds Priority column. - §8: Operator prefers existing tools over hand-rolled skill files. §8.1 recommendation pivots from hand-rolled (Option C) to cc-sdd (Option B). §8.2 rewrites comparison table — cc-sdd covers spec/plan/execute; TDD/debugging/review covered by existing project docs (TESTING.md, open-review-findings.mdx). Removes custom brainstorm template from iteration 5; no docs/internal/agent-skills/ dir needed. - §2 concept 14: Session-scoped op cache confirmed at src/console/op_cache.rs (252L, all production, no tests). Full detail: BTreeMap keyed by (account, vault_id, item_id) tuples, DEFAULT_ACCOUNT_KEY sentinel, invalidation methods, //! doc confirms metadata-only guarantee. - §7.14: New modernization entry — structured logging (log vs tracing vs current eprintln! approach). Recommendation: defer. Research in _research_notes.md. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 7 — MDX specs, §9 dep graph fix, §7.13 Renovate full entry Five concrete improvements: - §8.1/§8.3/§3: Operator direction — specs become public Starlight MDX pages at docs/src/content/docs/specs/ (draft: true while in-progress), not in docs/internal/specs/. Living source of truth updated with each code change. §8.3 boundary contract rewritten for public-spec model. §3 target shape updated to remove internal specs/ and add public specs/. - §9 R1: Corrected from "circular import risk" to "compilation-at-distance risk". Verified by grep: config imports workspace (config/mod.rs:1,5,6) but workspace does NOT import config. One-way dep: config → workspace. No circular risk; real risk is 30+ use path updates when AppConfig moves. - §10 step 2: Rewritten to match cc-sdd + Starlight MDX approach (was still describing hand-rolled docs/internal/agent-skills/ from pre- iteration-6 recommendation). Added draft page / lychee link-check caveat. - §7.13 Renovate: Full six-subheading entry replacing 2-sentence stub. Evaluated Dependabot and Renovate Cloud App; both rejected due to DCO sign-off constraint (RENOVATE_GIT_AUTHOR env var in renovate.yml:26 is not replicable in either alternative). Two low-cost tunings named. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 8 — lychee draft-page constraint, concept 18 correction Three improvements: - §8.1: Draft-page lychee constraint verified from docs/lychee.toml (full read). exclude_path has only 404.html pattern — no draft exclusion. Starlight draft pages exist in dist/ and are scanned by PR-time lychee check. Two fix options added: keep specs link-free, or add exclude pattern to lychee.toml. Added Astro sidebar requirement: manual config at astro.config.ts:50-103; autogenerate{ directory: 'specs' } pattern. - §2 concept 18: Corrected a wrong proposed move. AuthForwardMode → instance/auth.rs was incorrect — the type is used in 9 files, is a config field at config/mod.rs:89,96, and has serde Deserialize at line 74. Moving to instance/ would create circular dep. Corrected to: correctly placed, will move intra-module to config/types.rs in §10 4a. - §4 AuthForwardMode false alarm closed: confirmed NOT a §4 Rule 3 violation. Type is correctly in config because it IS a config value. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 9 — eprintln count, CODE_TOUR content, step 4a serde note - §7.14: grep-verified 96 production eprintln! calls across 16 files; breakdown by file; no rogue debug calls found, flip condition has not triggered - §2 concept 8: full 4-hop load chain with exact line numbers; documents the /__/ separator invariant in runtime_slug that prevents namespace collisions; CODE_TOUR column now specifies what the tour entry must explain - §10 step 4a: confirms AuthForwardMode serde impl is a plain impl<'de> block (not a derive), moves with the type to config/types.rs automatically Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 10 — dispatch_value scope, Renovate automerge, //! exemplar - §5 row 6: dispatch_value → resolve_env_value rename is 1 prod + 6 test call sites in a single file — lowest-cost rename in the table - §7.13: adds minimal safe automerge pattern for lockFileMaintenance only; explicitly excludes patch/minor bumps and SHA-pinned Actions - §4 Rule 7: expands //! exemplar analysis with direct quotes from env_model.rs:1-17 and isolates the three-element pattern Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): strip iteration annotations; reorder log chronologically READABILITY_AND_MODERNIZATION.md now presents a clean final view: - Remove all "(iteration N)", "(verified iteration N)", "read in full for iteration N", "updated iteration N" qualifiers throughout the body - Remove the Iteration counter from §0 meta - Resolved OQ markers simplified from "(resolved in iteration N)" to "(resolved)"; deferred OQ markers from "Tracked for iteration N" to "Deferred" _iteration_log.md now has entries in chronological order 1–10: - Was: 1, 3, 4, 5, 6, 7, 10, 8, 9, 2 - Now: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): research OpenSpec and IIKit; update §8 landscape _research_notes.md: - OpenSpec (Fission-AI/OpenSpec): brownfield-first SDD, three-phase propose/apply/archive, delta markers (ADDED/MODIFIED/REMOVED), living specs at openspec/specs/; /loop-compatible; recommended as cc-sdd complement for §4 module-split proposals - IIKit (intent-integrity-chain/kit): cryptographic .feature hash-locking, 8-phase workflow, Gherkin BDD chain, Tessl-only install; not recommended for jackin (no Gherkin step runner, Tessl lock-in, heavyweight for single-maintainer) READABILITY_AND_MODERNIZATION.md §8.1: - Adds Options E (OpenSpec) and F (IIKit) to the landscape and evaluation table with brownfield delta tracking and Rust/nextest compatibility rows - Adds OpenSpec complement note after the cc-sdd recommendation Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 11 — dtolnay correction, ci.yml detail, snapshot targets - §7.7 / §2 concept 25 / §10 step 3: correct false claim that dtolnay/rust-toolchain reads rust-toolchain.toml; action version is encoded in SHA rev; three sources require manual sync - §6 ci.yml row: expand from high-level to exact job steps; document gaps (no MSRV job, floating tags in build-validator, no doc job, main jackin binary never compiled in CI) - §7.9: grep-confirm all three snapshot target fn names; add exact signatures and private-fn access pattern (use super::*) with list.rs:720 as existing proof Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 12 — ClassSelector scope, lint table, app split - §5 row 5: ClassSelector → AgentClass rename is 138 prod call sites across 17 files — highest-scope rename in the table - §7.8: full lint table enumeration from Cargo.toml:47-75; notes that cast allowances are global despite TUI-scoped inline comment - §4 4e: app/mod.rs run() read in full; refined split from 1 file to 3 (dispatch.rs ~167L, workspace_cmd.rs ~438L, config_cmd.rs ~220L) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): remove resolved/no-action items from roadmap Keep only forward-looking actionable proposals: §2 concept table: removed 6 rows with "Stable"/"No change needed" proposals (RULES.md keybindings, hardline, mount planning, XDG paths, Docker builder, env-var ordering); renumbered 1-19 §5 naming table: removed hardline_agent row (leave-as-is, no action); rephrased load_agent row to focus on the //! doc action not the rename; renumbered to 1-14 §9 open questions: removed OQ3 (preview.yml, resolved — in §6), OQ5 (auth.rs split, resolved — no split needed), OQ7 (astro-og-canvas, resolved — fix in §7.11); renumbered to OQ1-4; merged TS strictness OQ back into the active list Cleanup: removed "resolved OQ5" tag from auth.rs hot-spot entry; removed "(resolved OQ7)" qualifier from §7.11 blocker label Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): update analysis baseline — PR #171 now merged to main Remove all "after PR #171 merges", "PR #171 branch", "pre-merge", and "not yet on main" qualifiers throughout. Specific changes: - §0: update baseline note from "treated as merged" to "now merged" - §1: remove branch-only qualifiers from file tree, module map, coverage count - §2: concept rows 1, 2, 4, 5, 6, 10, 11, 12, 14, 15 updated to reflect code now on main; row 12 op_cache current-state rating updated from requires-tribal-knowledge (pre-merge) to requires-grep (post-merge) - OQ1 (op_picker cache): updated from "deferred" to "read from main now" - §4, §5, §7: remove "(PR #171)" and "adds/branch" language - §10 step 1: remove "once PR #171 merges" condition Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> --------- Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Claude <noreply@anthropic.com>

* docs(roadmap): iteration 1 — readability & modernization analysis Full first draft of READABILITY_AND_MODERNIZATION.md covering §0–§10: project inventory (72 files, 40k LOC), concept-to-location index (25 entries), documentation hierarchy proposal, source-code structural diagnosis (single-crate recommendation, 7 module-shape rules, hot-spot list), naming candidates, CI/tooling analysis, modernization candidates (13 entries with alternatives comparisons), AI-agent workflow (§8.1–§8.3: spec-driven development, superpowers alternatives, docs boundary), risks, and execution sequencing. All claims grounded in direct code reading (cited file paths and line ranges). All crate/tool recommendations include 2–3 alternatives. PR #171 branch read for AgentPicker, OpStructRunner, RawOpField, and RULES.md additions. Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 2 — launch.rs deep analysis, TS strictness, preview workflow Four concrete improvements over iteration 1: - §4: Deep-read src/runtime/launch.rs (2368L) in full; mapped every function to exact line ranges and dependency graph; refined split proposal into 4 files (launch.rs ~120L, launch_pipeline.rs ~560L prod + 1200L tests, terminfo.rs ~110L, trust.rs ~60L); key finding: test module (1282L) exceeds production code (1083L). - §7.11: Discovered docs/AGENTS.md documents both TypeScript strictness blockers explicitly (rainEngine indexed access + astro-og-canvas optional-property types); verified rainEngine.ts at 5 line locations; rewrote recommendation as a concrete 4-step fix plan. - §6: Read preview.yml in full — Homebrew tap rolling-preview pipeline; flagged missing contributor documentation; resolved OQ3. - §2 concepts 4 & 6: Exact PR #171 data — TICK_MS=50 at console/mod.rs:90 with 20Hz rationale; compile-time safety test is an exhaustive struct destructure (not trybuild) at operator_env.rs:2055–2096. Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 3 — operator_env.rs deep analysis, snapshot tests, OQ7 Three concrete improvements over iteration 2: - §4: Deep-read src/operator_env.rs (1569L); mapped every function to exact line ranges; identified two distinct clusters (op CLI subprocess layer lines 96-364 vs env layer resolution lines 365-808) with ~90L connective tissue; proposed module-directory split into mod.rs (~100L), client.rs (~280L), layers.rs (~470L), picker.rs (~250L PR#171); dependency graph shows no circular imports. - §7.5: Named first 3 concrete snapshot test targets with file:line citations — render_sentinel_description_pane (list.rs:306, zero state, ~10L), render_tab_strip (editor.rs:180, 4 enum variants, ~20L), render_mounts_subpanel (list.rs:408, 3 data-driven cases, ~30L). - OQ7 resolved: docs/package.json confirms astro-og-canvas ^0.11.1; docs/src/pages/og/[...slug].png.ts:~35 has `logo: undefined` which is the exact exactOptionalPropertyTypes conflict; fix is one line (omit the property). §7.11 and §9 updated accordingly. Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 4 — config/editor.rs deep analysis, exact rustdoc coverage Two concrete improvements: - §4: Deep-read config/editor.rs (1467L); key finding: production code is only 503L (lines 1-503), tests are 963L (lines 504-1467 — nearly 2x); mapped all 18 public methods with exact line ranges into 5 domain groups; flagged create_workspace/edit_workspace validation-first architectural pattern as a refactor-preserve invariant; proposed 6-file module-directory split; priority note: lower than launch.rs/operator_env.rs since production code is already a reasonable size. - §1/§4/§7.6: Corrected rustdoc coverage from estimate "~28%" to exact count 37/90 files = 41%; identified cluster: console/manager/ and console/widgets/ (PR #171 additions) are well-covered; runtime/, app/, cli/ lag; updated all three occurrences consistently. Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 5 — concrete brainstorm template, §10 step 4 ordering, §5 pruning Three concrete improvements: - §8.2: Added 17-line concrete docs/internal/agent-skills/brainstorm.md template with 6 fields (Purpose/When/Steps/Outputs/Done when/Overlap guard). The Done-when and Overlap-guard fields are the discipline gates missing from superpowers default brainstorming. Makes §8.2 immediately actionable instead of aspirational. - §10 step 4: Refined split ordering from sketch to priority-grounded sequence: config/types (4a) → manifest (4b) → config/editor 503L (4c) → operator_env 810L (4d) → app/dispatch (4e) → runtime/launch 1083L (4f last). Each sub-step has architectural notes and what-could-go-wrong. Flags the operator_env circular-dependency check for layers.rs→client.rs. - §5: Replaced 3 "leave as is" non-candidates (rows 10, 12, 15) with verified candidates from code reading: provision_claude_auth→apply_auth_forward (auth.rs:17), AuthProvisionOutcome→AuthForwardOutcome (instance/mod.rs), spawn_wait_thread→spawn_exit_watcher (operator_env.rs:202). - OQ5 resolved: instance/auth.rs read — only 210L production code, 585L tests (3x); no split needed; removed from hot-spot concern. Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 6 — hot-spot splits, §8 cc-sdd pivot, op_cache, logging Four improvements: - §1: Hot-spot table rebuilt with production/test LOC split columns for all 22 files. Key finding: manifest/validate.rs is 145L prod/816L tests (exemplary testing, not a god file); app/mod.rs is 928L prod/22L tests (most genuine god file after launch.rs). Adds Priority column. - §8: Operator prefers existing tools over hand-rolled skill files. §8.1 recommendation pivots from hand-rolled (Option C) to cc-sdd (Option B). §8.2 rewrites comparison table — cc-sdd covers spec/plan/execute; TDD/debugging/review covered by existing project docs (TESTING.md, open-review-findings.mdx). Removes custom brainstorm template from iteration 5; no docs/internal/agent-skills/ dir needed. - §2 concept 14: Session-scoped op cache confirmed at src/console/op_cache.rs (252L, all production, no tests). Full detail: BTreeMap keyed by (account, vault_id, item_id) tuples, DEFAULT_ACCOUNT_KEY sentinel, invalidation methods, //! doc confirms metadata-only guarantee. - §7.14: New modernization entry — structured logging (log vs tracing vs current eprintln! approach). Recommendation: defer. Research in _research_notes.md. Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 7 — MDX specs, §9 dep graph fix, §7.13 Renovate full entry Five concrete improvements: - §8.1/§8.3/§3: Operator direction — specs become public Starlight MDX pages at docs/src/content/docs/specs/ (draft: true while in-progress), not in docs/internal/specs/. Living source of truth updated with each code change. §8.3 boundary contract rewritten for public-spec model. §3 target shape updated to remove internal specs/ and add public specs/. - §9 R1: Corrected from "circular import risk" to "compilation-at-distance risk". Verified by grep: config imports workspace (config/mod.rs:1,5,6) but workspace does NOT import config. One-way dep: config → workspace. No circular risk; real risk is 30+ use path updates when AppConfig moves. - §10 step 2: Rewritten to match cc-sdd + Starlight MDX approach (was still describing hand-rolled docs/internal/agent-skills/ from pre- iteration-6 recommendation). Added draft page / lychee link-check caveat. - §7.13 Renovate: Full six-subheading entry replacing 2-sentence stub. Evaluated Dependabot and Renovate Cloud App; both rejected due to DCO sign-off constraint (RENOVATE_GIT_AUTHOR env var in renovate.yml:26 is not replicable in either alternative). Two low-cost tunings named. Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 8 — lychee draft-page constraint, concept 18 correction Three improvements: - §8.1: Draft-page lychee constraint verified from docs/lychee.toml (full read). exclude_path has only 404.html pattern — no draft exclusion. Starlight draft pages exist in dist/ and are scanned by PR-time lychee check. Two fix options added: keep specs link-free, or add exclude pattern to lychee.toml. Added Astro sidebar requirement: manual config at astro.config.ts:50-103; autogenerate{ directory: 'specs' } pattern. - §2 concept 18: Corrected a wrong proposed move. AuthForwardMode → instance/auth.rs was incorrect — the type is used in 9 files, is a config field at config/mod.rs:89,96, and has serde Deserialize at line 74. Moving to instance/ would create circular dep. Corrected to: correctly placed, will move intra-module to config/types.rs in §10 4a. - §4 AuthForwardMode false alarm closed: confirmed NOT a §4 Rule 3 violation. Type is correctly in config because it IS a config value. Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 9 — eprintln count, CODE_TOUR content, step 4a serde note - §7.14: grep-verified 96 production eprintln! calls across 16 files; breakdown by file; no rogue debug calls found, flip condition has not triggered - §2 concept 8: full 4-hop load chain with exact line numbers; documents the /__/ separator invariant in runtime_slug that prevents namespace collisions; CODE_TOUR column now specifies what the tour entry must explain - §10 step 4a: confirms AuthForwardMode serde impl is a plain impl<'de> block (not a derive), moves with the type to config/types.rs automatically Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 10 — dispatch_value scope, Renovate automerge, //! exemplar - §5 row 6: dispatch_value → resolve_env_value rename is 1 prod + 6 test call sites in a single file — lowest-cost rename in the table - §7.13: adds minimal safe automerge pattern for lockFileMaintenance only; explicitly excludes patch/minor bumps and SHA-pinned Actions - §4 Rule 7: expands //! exemplar analysis with direct quotes from env_model.rs:1-17 and isolates the three-element pattern Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): strip iteration annotations; reorder log chronologically READABILITY_AND_MODERNIZATION.md now presents a clean final view: - Remove all "(iteration N)", "(verified iteration N)", "read in full for iteration N", "updated iteration N" qualifiers throughout the body - Remove the Iteration counter from §0 meta - Resolved OQ markers simplified from "(resolved in iteration N)" to "(resolved)"; deferred OQ markers from "Tracked for iteration N" to "Deferred" _iteration_log.md now has entries in chronological order 1–10: - Was: 1, 3, 4, 5, 6, 7, 10, 8, 9, 2 - Now: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): research OpenSpec and IIKit; update §8 landscape _research_notes.md: - OpenSpec (Fission-AI/OpenSpec): brownfield-first SDD, three-phase propose/apply/archive, delta markers (ADDED/MODIFIED/REMOVED), living specs at openspec/specs/; /loop-compatible; recommended as cc-sdd complement for §4 module-split proposals - IIKit (intent-integrity-chain/kit): cryptographic .feature hash-locking, 8-phase workflow, Gherkin BDD chain, Tessl-only install; not recommended for jackin (no Gherkin step runner, Tessl lock-in, heavyweight for single-maintainer) READABILITY_AND_MODERNIZATION.md §8.1: - Adds Options E (OpenSpec) and F (IIKit) to the landscape and evaluation table with brownfield delta tracking and Rust/nextest compatibility rows - Adds OpenSpec complement note after the cc-sdd recommendation Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 11 — dtolnay correction, ci.yml detail, snapshot targets - §7.7 / §2 concept 25 / §10 step 3: correct false claim that dtolnay/rust-toolchain reads rust-toolchain.toml; action version is encoded in SHA rev; three sources require manual sync - §6 ci.yml row: expand from high-level to exact job steps; document gaps (no MSRV job, floating tags in build-validator, no doc job, main jackin binary never compiled in CI) - §7.9: grep-confirm all three snapshot target fn names; add exact signatures and private-fn access pattern (use super::*) with list.rs:720 as existing proof Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 12 — ClassSelector scope, lint table, app split - §5 row 5: ClassSelector → AgentClass rename is 138 prod call sites across 17 files — highest-scope rename in the table - §7.8: full lint table enumeration from Cargo.toml:47-75; notes that cast allowances are global despite TUI-scoped inline comment - §4 4e: app/mod.rs run() read in full; refined split from 1 file to 3 (dispatch.rs ~167L, workspace_cmd.rs ~438L, config_cmd.rs ~220L) Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): remove resolved/no-action items from roadmap Keep only forward-looking actionable proposals: §2 concept table: removed 6 rows with "Stable"/"No change needed" proposals (RULES.md keybindings, hardline, mount planning, XDG paths, Docker builder, env-var ordering); renumbered 1-19 §5 naming table: removed hardline_agent row (leave-as-is, no action); rephrased load_agent row to focus on the //! doc action not the rename; renumbered to 1-14 §9 open questions: removed OQ3 (preview.yml, resolved — in §6), OQ5 (auth.rs split, resolved — no split needed), OQ7 (astro-og-canvas, resolved — fix in §7.11); renumbered to OQ1-4; merged TS strictness OQ back into the active list Cleanup: removed "resolved OQ5" tag from auth.rs hot-spot entry; removed "(resolved OQ7)" qualifier from §7.11 blocker label Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): update analysis baseline — PR #171 now merged to main Remove all "after PR #171 merges", "PR #171 branch", "pre-merge", and "not yet on main" qualifiers throughout. Specific changes: - §0: update baseline note from "treated as merged" to "now merged" - §1: remove branch-only qualifiers from file tree, module map, coverage count - §2: concept rows 1, 2, 4, 5, 6, 10, 11, 12, 14, 15 updated to reflect code now on main; row 12 op_cache current-state rating updated from requires-tribal-knowledge (pre-merge) to requires-grep (post-merge) - OQ1 (op_picker cache): updated from "deferred" to "read from main now" - §4, §5, §7: remove "(PR #171)" and "adds/branch" language - §10 step 1: remove "once PR #171 merges" condition Co-authored-by: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Codex <codex@openai.com>

* docs(roadmap): iteration 1 — readability & modernization analysis Full first draft of READABILITY_AND_MODERNIZATION.md covering §0–§10: project inventory (72 files, 40k LOC), concept-to-location index (25 entries), documentation hierarchy proposal, source-code structural diagnosis (single-crate recommendation, 7 module-shape rules, hot-spot list), naming candidates, CI/tooling analysis, modernization candidates (13 entries with alternatives comparisons), AI-agent workflow (§8.1–§8.3: spec-driven development, superpowers alternatives, docs boundary), risks, and execution sequencing. All claims grounded in direct code reading (cited file paths and line ranges). All crate/tool recommendations include 2–3 alternatives. PR #171 branch read for AgentPicker, OpStructRunner, RawOpField, and RULES.md additions. * docs(roadmap): iteration 2 — launch.rs deep analysis, TS strictness, preview workflow Four concrete improvements over iteration 1: - §4: Deep-read src/runtime/launch.rs (2368L) in full; mapped every function to exact line ranges and dependency graph; refined split proposal into 4 files (launch.rs ~120L, launch_pipeline.rs ~560L prod + 1200L tests, terminfo.rs ~110L, trust.rs ~60L); key finding: test module (1282L) exceeds production code (1083L). - §7.11: Discovered docs/AGENTS.md documents both TypeScript strictness blockers explicitly (rainEngine indexed access + astro-og-canvas optional-property types); verified rainEngine.ts at 5 line locations; rewrote recommendation as a concrete 4-step fix plan. - §6: Read preview.yml in full — Homebrew tap rolling-preview pipeline; flagged missing contributor documentation; resolved OQ3. - §2 concepts 4 & 6: Exact PR #171 data — TICK_MS=50 at console/mod.rs:90 with 20Hz rationale; compile-time safety test is an exhaustive struct destructure (not trybuild) at operator_env.rs:2055–2096. * docs(roadmap): iteration 3 — operator_env.rs deep analysis, snapshot tests, OQ7 Three concrete improvements over iteration 2: - §4: Deep-read src/operator_env.rs (1569L); mapped every function to exact line ranges; identified two distinct clusters (op CLI subprocess layer lines 96-364 vs env layer resolution lines 365-808) with ~90L connective tissue; proposed module-directory split into mod.rs (~100L), client.rs (~280L), layers.rs (~470L), picker.rs (~250L PR#171); dependency graph shows no circular imports. - §7.5: Named first 3 concrete snapshot test targets with file:line citations — render_sentinel_description_pane (list.rs:306, zero state, ~10L), render_tab_strip (editor.rs:180, 4 enum variants, ~20L), render_mounts_subpanel (list.rs:408, 3 data-driven cases, ~30L). - OQ7 resolved: docs/package.json confirms astro-og-canvas ^0.11.1; docs/src/pages/og/[...slug].png.ts:~35 has `logo: undefined` which is the exact exactOptionalPropertyTypes conflict; fix is one line (omit the property). §7.11 and §9 updated accordingly. * docs(roadmap): iteration 4 — config/editor.rs deep analysis, exact rustdoc coverage Two concrete improvements: - §4: Deep-read config/editor.rs (1467L); key finding: production code is only 503L (lines 1-503), tests are 963L (lines 504-1467 — nearly 2x); mapped all 18 public methods with exact line ranges into 5 domain groups; flagged create_workspace/edit_workspace validation-first architectural pattern as a refactor-preserve invariant; proposed 6-file module-directory split; priority note: lower than launch.rs/operator_env.rs since production code is already a reasonable size. - §1/§4/§7.6: Corrected rustdoc coverage from estimate "~28%" to exact count 37/90 files = 41%; identified cluster: console/manager/ and console/widgets/ (PR #171 additions) are well-covered; runtime/, app/, cli/ lag; updated all three occurrences consistently. * docs(roadmap): iteration 5 — concrete brainstorm template, §10 step 4 ordering, §5 pruning Three concrete improvements: - §8.2: Added 17-line concrete docs/internal/agent-skills/brainstorm.md template with 6 fields (Purpose/When/Steps/Outputs/Done when/Overlap guard). The Done-when and Overlap-guard fields are the discipline gates missing from superpowers default brainstorming. Makes §8.2 immediately actionable instead of aspirational. - §10 step 4: Refined split ordering from sketch to priority-grounded sequence: config/types (4a) → manifest (4b) → config/editor 503L (4c) → operator_env 810L (4d) → app/dispatch (4e) → runtime/launch 1083L (4f last). Each sub-step has architectural notes and what-could-go-wrong. Flags the operator_env circular-dependency check for layers.rs→client.rs. - §5: Replaced 3 "leave as is" non-candidates (rows 10, 12, 15) with verified candidates from code reading: provision_claude_auth→apply_auth_forward (auth.rs:17), AuthProvisionOutcome→AuthForwardOutcome (instance/mod.rs), spawn_wait_thread→spawn_exit_watcher (operator_env.rs:202). - OQ5 resolved: instance/auth.rs read — only 210L production code, 585L tests (3x); no split needed; removed from hot-spot concern. * docs(roadmap): iteration 6 — hot-spot splits, §8 cc-sdd pivot, op_cache, logging Four improvements: - §1: Hot-spot table rebuilt with production/test LOC split columns for all 22 files. Key finding: manifest/validate.rs is 145L prod/816L tests (exemplary testing, not a god file); app/mod.rs is 928L prod/22L tests (most genuine god file after launch.rs). Adds Priority column. - §8: Operator prefers existing tools over hand-rolled skill files. §8.1 recommendation pivots from hand-rolled (Option C) to cc-sdd (Option B). §8.2 rewrites comparison table — cc-sdd covers spec/plan/execute; TDD/debugging/review covered by existing project docs (TESTING.md, open-review-findings.mdx). Removes custom brainstorm template from iteration 5; no docs/internal/agent-skills/ dir needed. - §2 concept 14: Session-scoped op cache confirmed at src/console/op_cache.rs (252L, all production, no tests). Full detail: BTreeMap keyed by (account, vault_id, item_id) tuples, DEFAULT_ACCOUNT_KEY sentinel, invalidation methods, //! doc confirms metadata-only guarantee. - §7.14: New modernization entry — structured logging (log vs tracing vs current eprintln! approach). Recommendation: defer. Research in _research_notes.md. * docs(roadmap): iteration 7 — MDX specs, §9 dep graph fix, §7.13 Renovate full entry Five concrete improvements: - §8.1/§8.3/§3: Operator direction — specs become public Starlight MDX pages at docs/src/content/docs/specs/ (draft: true while in-progress), not in docs/internal/specs/. Living source of truth updated with each code change. §8.3 boundary contract rewritten for public-spec model. §3 target shape updated to remove internal specs/ and add public specs/. - §9 R1: Corrected from "circular import risk" to "compilation-at-distance risk". Verified by grep: config imports workspace (config/mod.rs:1,5,6) but workspace does NOT import config. One-way dep: config → workspace. No circular risk; real risk is 30+ use path updates when AppConfig moves. - §10 step 2: Rewritten to match cc-sdd + Starlight MDX approach (was still describing hand-rolled docs/internal/agent-skills/ from pre- iteration-6 recommendation). Added draft page / lychee link-check caveat. - §7.13 Renovate: Full six-subheading entry replacing 2-sentence stub. Evaluated Dependabot and Renovate Cloud App; both rejected due to DCO sign-off constraint (RENOVATE_GIT_AUTHOR env var in renovate.yml:26 is not replicable in either alternative). Two low-cost tunings named. * docs(roadmap): iteration 8 — lychee draft-page constraint, concept 18 correction Three improvements: - §8.1: Draft-page lychee constraint verified from docs/lychee.toml (full read). exclude_path has only 404.html pattern — no draft exclusion. Starlight draft pages exist in dist/ and are scanned by PR-time lychee check. Two fix options added: keep specs link-free, or add exclude pattern to lychee.toml. Added Astro sidebar requirement: manual config at astro.config.ts:50-103; autogenerate{ directory: 'specs' } pattern. - §2 concept 18: Corrected a wrong proposed move. AuthForwardMode → instance/auth.rs was incorrect — the type is used in 9 files, is a config field at config/mod.rs:89,96, and has serde Deserialize at line 74. Moving to instance/ would create circular dep. Corrected to: correctly placed, will move intra-module to config/types.rs in §10 4a. - §4 AuthForwardMode false alarm closed: confirmed NOT a §4 Rule 3 violation. Type is correctly in config because it IS a config value. * docs(roadmap): iteration 9 — eprintln count, CODE_TOUR content, step 4a serde note - §7.14: grep-verified 96 production eprintln! calls across 16 files; breakdown by file; no rogue debug calls found, flip condition has not triggered - §2 concept 8: full 4-hop load chain with exact line numbers; documents the /__/ separator invariant in runtime_slug that prevents namespace collisions; CODE_TOUR column now specifies what the tour entry must explain - §10 step 4a: confirms AuthForwardMode serde impl is a plain impl<'de> block (not a derive), moves with the type to config/types.rs automatically * docs(roadmap): iteration 10 — dispatch_value scope, Renovate automerge, //! exemplar - §5 row 6: dispatch_value → resolve_env_value rename is 1 prod + 6 test call sites in a single file — lowest-cost rename in the table - §7.13: adds minimal safe automerge pattern for lockFileMaintenance only; explicitly excludes patch/minor bumps and SHA-pinned Actions - §4 Rule 7: expands //! exemplar analysis with direct quotes from env_model.rs:1-17 and isolates the three-element pattern * docs(roadmap): strip iteration annotations; reorder log chronologically READABILITY_AND_MODERNIZATION.md now presents a clean final view: - Remove all "(iteration N)", "(verified iteration N)", "read in full for iteration N", "updated iteration N" qualifiers throughout the body - Remove the Iteration counter from §0 meta - Resolved OQ markers simplified from "(resolved in iteration N)" to "(resolved)"; deferred OQ markers from "Tracked for iteration N" to "Deferred" _iteration_log.md now has entries in chronological order 1–10: - Was: 1, 3, 4, 5, 6, 7, 10, 8, 9, 2 - Now: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 * docs(roadmap): research OpenSpec and IIKit; update §8 landscape _research_notes.md: - OpenSpec (Fission-AI/OpenSpec): brownfield-first SDD, three-phase propose/apply/archive, delta markers (ADDED/MODIFIED/REMOVED), living specs at openspec/specs/; /loop-compatible; recommended as cc-sdd complement for §4 module-split proposals - IIKit (intent-integrity-chain/kit): cryptographic .feature hash-locking, 8-phase workflow, Gherkin BDD chain, Tessl-only install; not recommended for jackin (no Gherkin step runner, Tessl lock-in, heavyweight for single-maintainer) READABILITY_AND_MODERNIZATION.md §8.1: - Adds Options E (OpenSpec) and F (IIKit) to the landscape and evaluation table with brownfield delta tracking and Rust/nextest compatibility rows - Adds OpenSpec complement note after the cc-sdd recommendation * docs(roadmap): iteration 11 — dtolnay correction, ci.yml detail, snapshot targets - §7.7 / §2 concept 25 / §10 step 3: correct false claim that dtolnay/rust-toolchain reads rust-toolchain.toml; action version is encoded in SHA rev; three sources require manual sync - §6 ci.yml row: expand from high-level to exact job steps; document gaps (no MSRV job, floating tags in build-validator, no doc job, main jackin binary never compiled in CI) - §7.9: grep-confirm all three snapshot target fn names; add exact signatures and private-fn access pattern (use super::*) with list.rs:720 as existing proof * docs(roadmap): iteration 12 — ClassSelector scope, lint table, app split - §5 row 5: ClassSelector → AgentClass rename is 138 prod call sites across 17 files — highest-scope rename in the table - §7.8: full lint table enumeration from Cargo.toml:47-75; notes that cast allowances are global despite TUI-scoped inline comment - §4 4e: app/mod.rs run() read in full; refined split from 1 file to 3 (dispatch.rs ~167L, workspace_cmd.rs ~438L, config_cmd.rs ~220L) * docs(roadmap): remove resolved/no-action items from roadmap Keep only forward-looking actionable proposals: §2 concept table: removed 6 rows with "Stable"/"No change needed" proposals (RULES.md keybindings, hardline, mount planning, XDG paths, Docker builder, env-var ordering); renumbered 1-19 §5 naming table: removed hardline_agent row (leave-as-is, no action); rephrased load_agent row to focus on the //! doc action not the rename; renumbered to 1-14 §9 open questions: removed OQ3 (preview.yml, resolved — in §6), OQ5 (auth.rs split, resolved — no split needed), OQ7 (astro-og-canvas, resolved — fix in §7.11); renumbered to OQ1-4; merged TS strictness OQ back into the active list Cleanup: removed "resolved OQ5" tag from auth.rs hot-spot entry; removed "(resolved OQ7)" qualifier from §7.11 blocker label * docs(roadmap): update analysis baseline — PR #171 now merged to main Remove all "after PR #171 merges", "PR #171 branch", "pre-merge", and "not yet on main" qualifiers throughout. Specific changes: - §0: update baseline note from "treated as merged" to "now merged" - §1: remove branch-only qualifiers from file tree, module map, coverage count - §2: concept rows 1, 2, 4, 5, 6, 10, 11, 12, 14, 15 updated to reflect code now on main; row 12 op_cache current-state rating updated from requires-tribal-knowledge (pre-merge) to requires-grep (post-merge) - OQ1 (op_picker cache): updated from "deferred" to "read from main now" - §4, §5, §7: remove "(PR #171)" and "adds/branch" language - §10 step 1: remove "once PR #171 merges" condition --------- Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Claude <noreply@anthropic.com>

donbeave and others added 16 commits April 26, 2026 02:34

donbeave merged commit 277805f into main Apr 26, 2026
6 checks passed

donbeave deleted the analysis/readability-roadmap branch April 26, 2026 04:52

donbeave mentioned this pull request Apr 26, 2026

docs(roadmap): codebase health & restructuring roadmap in Starlight #183

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(roadmap): readability & modernization analysis loop#182

docs(roadmap): readability & modernization analysis loop#182
donbeave merged 16 commits into
mainfrom
analysis/readability-roadmap

donbeave commented Apr 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

donbeave commented Apr 26, 2026

Summary

What's in iteration 1

Test plan

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant