docs(roadmap): tighten per-mount isolation proposal#165
Merged
Conversation
Resolve three open questions and close two review gaps:
- Promote `branch_template` (workspace, with {container}/{workspace}/{agent}
variables) and per-mount `base_branch` override from Defer to V1 Scope.
Teams with branch-protection or naming conventions will ask for these
in week one; the serde/validation surface is small enough to land with
the core feature.
- Add a dirty-host-tree guard to Composition Rules: non-`shared` isolation
with uncommitted host edits warns and requires `--force`. Avoids silently
branching from HEAD past the operator's in-progress work without
defaulting to a tracking branch (which would be worse for the common
"continue my work" case).
- Answer OQ #1: flipping isolation on a running container requires eject.
Docker bind-mount sources are not mutable while running, so the platform
already forces this; state it explicitly rather than leaving it open.
- Document concurrent `jackin load` safety (rely on git's internal ref
locking in `.git/worktrees/`; no jackin'-side lock).
- Document orphan tolerance when the host repo is deleted or moved
(`purge` tolerates, subsequent `load` errors clearly).
- Move "submodules and git-LFS" out of Open Questions into a Known
Limitations list — worktrees inherit parent-repo behavior; no
jackin'-side investment planned for v1.
Docs-only; no code touched.
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Lock the worktree-mode v1 design after a full decision sweep. Scope trims and tightens throughout; clone mode explicitly deferred. User-facing decisions: - Back-merge is entirely upstream (GitHub PR via existing tooling); no jackin diff/integrate/merge commands. - Dirty host tree warns and requires --force; in practice a cold path since operators launch agents from clean trees. - Hooks inherit from the host repo; no --no-hooks flag in v1. - Branch name hardcoded as jackin/<container>; base = host HEAD. No configurable branch_template or base_branch in v1. - Worktree lives at <data_dir>/jackin-<container>/isolated/<slug>/. - jackin cd <container> ships in v1 for navigation. Scope trims: - Drop default_isolation. isolation is per-mount only, explicit. - Drop isolation on global mounts entirely (workspace-scoped only). Eliminates the cascade/composition rules for globals and ad-hoc CLI mounts inheriting a workspace default. - Drop --delete-branches flag from purge; purge silently deletes the local scratch branch along with everything else. Correctness decisions: - Pre-flight validation scoped per isolation type; only checks cases where git would silently do the wrong thing (subdirectory misrouting, mid-rebase HEAD). Obvious errors bubble up from git. - Purge refuses on running agents (fixes a pre-existing gap where remove_data_dir_if_exists runs unconditionally). - Enable extensions.worktreeConfig on first worktree creation per host repo so per-worktree config writes don't leak to shared .git/config. - Mount mode flipped between loads: orphan isolated/ dir left in place, reclaimed by jackin purge. No auto-prune. Known limitations documented (not blockers): - Submodules/LFS inherit parent-repo behavior. - Shared .git/config for remotes, credentials, and non-worktree writes (git limitation, not a jackin boundary). - -clone-N naming collision with future isolation = clone mode. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Claude <noreply@anthropic.com>
donbeave
added a commit
that referenced
this pull request
Apr 26, 2026
…MountConfig caveat - Correct too_many_lines count: 13 across 8 → 16 across 11 files (PR #171 added 5 suppressions in console/manager); add full breakdown table; update all 3 occurrences in roadmap - Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow) - Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description Co-authored-by: Claude <noreply@anthropic.com>
donbeave
added a commit
that referenced
this pull request
Apr 26, 2026
…MountConfig caveat - Correct too_many_lines count: 13 across 8 → 16 across 11 files (PR #171 added 5 suppressions in console/manager); add full breakdown table; update all 3 occurrences in roadmap - Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow) - Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
donbeave
added a commit
that referenced
this pull request
Apr 26, 2026
…MountConfig caveat - Correct too_many_lines count: 13 across 8 → 16 across 11 files (PR #171 added 5 suppressions in console/manager); add full breakdown table; update all 3 occurrences in roadmap - Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow) - Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
donbeave
added a commit
that referenced
this pull request
Apr 26, 2026
…MountConfig caveat - Correct too_many_lines count: 13 across 8 → 16 across 11 files (PR #171 added 5 suppressions in console/manager); add full breakdown table; update all 3 occurrences in roadmap - Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow) - Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
donbeave
added a commit
that referenced
this pull request
Apr 26, 2026
…MountConfig caveat - Correct too_many_lines count: 13 across 8 → 16 across 11 files (PR #171 added 5 suppressions in console/manager); add full breakdown table; update all 3 occurrences in roadmap - Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow) - Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
donbeave
added a commit
that referenced
this pull request
Apr 26, 2026
…183) * docs(roadmap): iteration 13 — AI code verifiability framing, config/types.rs full spec Primary goal shift: codebase must be verifiable for AI-generated code. - §0: replace generic description with explicit verifiability rationale (module contracts, localised concerns, types/behaviour separation) - §4 intro: add "Why structure matters for AI-generated code" section with audit-units table mapping each post-split file to one reviewable question - §4 4a: expand config/types.rs from description to full execution spec — exact type list, post-split mod.rs content, zero-change submodule guarantee (verified: agents.rs/persist.rs/workspaces.rs use super::T which resolves through mod.rs re-exports unchanged), impl-extension pattern already in use documented Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 14 — editor method map, app helpers, //! queue - §4 4c: config/editor.rs split is now execution-ready — complete 6-file method-to-file table with private helper placement verified (validate_candidate→io.rs, table_path_mut→mod.rs pub(super), auth_forward_str→agent_ops.rs, create_workspace delegates to AppConfig) - §4 4e: app/mod.rs split complete — all private helpers mapped (parse_auth_forward_mode_from_cli→config_cmd.rs, workspace_env_scope→workspace_cmd.rs, print_env_table note, remove_data_dir_if_exists→dispatch.rs) - §10 step 5: add //! priority queue — 10 files with draft content, prioritised by cold-landing impact and AI audit risk; selector.rs and instance/mod.rs explicitly document the /→__ invariant Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 15 — dep graph fix, trust.rs safety, OQ1 closed - §4 4d: correct operator_env dependency graph — layers.rs imports both mod.rs (OpRunner) AND client.rs (OpCli for non-injectable resolve_operator_env wrapper at line 797); still a valid DAG - §4 4f: verify trust.rs split safety — FnOnce injection pattern means launch_pipeline.rs has zero dependency on trust.rs; import chain documented; trust bypass audit now requires reading only ~60L - §9 OQ1 closed: op_cache.rs read in full — 4-level structure, per-level invalidation, no TTL/expiry (expiry handled at OpCli subprocess level), DEFAULT_ACCOUNT_KEY sentinel documented Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 16 — CommandRunner Rule 3, render/editor split, 4a/4c independence - Fix duplicate Rule 3 section introduced by previous edit; add docker.rs co-location note as third edge case (three edge cases, not two) - Add render/editor.rs as new Rule 5 violator: 1666L post-PR #171 (was listed as 782L); propose 6-file tab-by-tab split with auditability note on the security-adjacent Secrets tab - Add §10 execution-order note: 4a and 4c are independent — editor.rs imports AppConfig via crate::config re-exports regardless of 4a order - Append iteration 16 log entry with confidence table and weakest sections Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 17 — instance/auth.rs audit, state.rs split, line count corrections - Add instance/auth.rs to //! priority queue at #4: four security invariants (0o600 perms, symlink rejection, TOCTOU-safe writes, macOS Keychain) documented in draft //! content - Add state.rs as new Rule 5 violator: 992L/628L production; 26+ types mixed with impl blocks; propose 5-file types/behavior split - Correct stale line counts: render/list.rs 1122→1989 (PR #171 added render_environments_subpanel); state.rs 865→992; priorities upgraded - Fix §7.9 snapshot function line refs: sentinel_description_pane 306→332, mounts_subpanel 408→433, render_tab_strip 180→269, test ref 720→944 - Renumber //! priority queue to 11 entries (was 10) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 18 — agent_allow OQ2 closed, render/list.rs split proposal - Close OQ2: agent_allow.rs read in full — 55L, correct //! doc, design sound; serves as model for //! priority queue pattern - Add render/list.rs as new Rule 5 violator: 668L production (PR #171 added render_environments_subpanel); propose 3-file split (mod.rs, details.rs, subpanels.rs); note import-path change for agents_block_agent_count - Update §1 module map: agent_allow.rs entry corrected with size/API Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 19 — input/editor.rs critical correction, split proposal - Correct input/editor.rs: 2349L total (was 1304L), 1141L production (was 547L) — PR #171 added Secrets-tab handlers; pub(super) fn handle_editor_modal at line 618 was invisible to previous grep pattern; now the largest production file in the codebase; priority → Critical - Correct input/save.rs: 1472L total, 661L production (was 567L) - Add 5-file split proposal for input/editor.rs: mod.rs (two dispatchers), secrets.rs (~500L AI-generated Secrets-tab), agents.rs, mounts.rs, general.rs - Update key insight paragraph naming input/editor.rs as largest production file Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 20 — console splits in §10, MSRV evidence, animation.rs verdict - Add console/manager/ as §10 Step 4f group with 5 sub-steps in priority order; rename existing 4f (launch.rs) → 4g; add circular-import risk note for ManagerStage/EditorState split sequencing - Analyze tui/animation.rs: 582L all-production, no split needed (banner_grid is a tightly-coupled rendering loop); section comments compensate for missing //! - Partially close OQ3: u64::is_multiple_of (stabilized 1.86) found in animation.rs; within declared MSRV 1.94; full cargo +1.94.0 check deferred (toolchain unavailable) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 21 — input/save.rs split, //! queue fix, save.rs corrections - Add input/save.rs split proposal: 4 pub(super) fns discovered; 3-file split (mod.rs + flow.rs + preview.rs); no cross-dependency between flow and preview groups; §10 4f-v updated from Optional to concrete plan - Fix //! queue preamble: "first 10 files" → "first 11 files" - Correct save.rs module map (1418→1472L, correct key exports) and hot-spot table note (begin_editor_save ~280L → ~118L; commit_editor_save is the Phase 2 partner at ~149L) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 22 — input/list.rs and mount_info.rs analysis - Analyze input/list.rs: 214L production (tests at 215); has //! doc; two focused pub(super) fns; no split needed; Low priority; correct module map - Add mount_info.rs to hot-spot table: 277L production; Low priority; has //! doc; correct module map with 3 public enums + inspect fn - Fix stale §2 diagnosis note: docs/internal/roadmap/ now exists Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 23 — audit units table +5 console rows, input/mod.rs corrected - Expand audit units table from 8 to 13 entries: add state/types.rs, state/editor.rs, input/editor/secrets.rs, render/list/subpanels.rs, input/save/preview.rs — all targeting PR #171 AI-generated console code - Add PR #171 context note linking 5 new entries to AI-generated code concern - Correct input/mod.rs module map: 369L, add InputOutcome enum to exports - Verify rust-toolchain.toml absence; §7.7 and §2 concept 25 already correct Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 24 — render/mod.rs analysis, //! exemplars table, EditorTab confirmed - Add §4 Rule 7 positive exemplars table: 7 files with //! docs graded 1-element (render/mod.rs), 2-element (input/save.rs etc), 3-element (env_model.rs, agent_allow.rs); PR #171 docs-discipline pattern noted - Correct render/mod.rs module map: 421L; FooterItem + palette constants + render_header + centered_rect_fixed added to key exports - Confirm EditorTab variants: General, Mounts, Agents, Secrets (Rust enum) vs "Secrets / Environments" (UI label); /stub qualifier already removed Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 25 — too_many_lines recount, FooterItem PR, MountConfig caveat - Correct too_many_lines count: 13 across 8 → 16 across 11 files (PR #171 added 5 suppressions in console/manager); add full breakdown table; update all 3 occurrences in roadmap - Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow) - Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 26 — console/mod.rs and op_picker/render.rs analyzed - Add console/mod.rs to hot-spot table: 406L/307L production (Low); correct module map from ~200 → 406L; note missing //! doc with ConsoleStage design block comment worth promoting - Add op_picker/render.rs to hot-spot table: 865L/545L production (Medium); PR #171 AI-generated; 14 functions in two logical groups (entry/helpers vs level renderers); split into levels.rs proposed - Correct 3 stale ~200L estimates for console/mod.rs across roadmap Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 27 — op_picker/mod.rs discovery, render split, operator_env correction - Add op_picker/mod.rs to hot-spot table: 1712L/775L production (High); PR #171 AI-generated; OpPickerState types+behavior split opportunity; has 7-line //! doc; module map split into two rows (mod.rs + render.rs) - Add op_picker/render.rs 2-file split proposal: render.rs (coordinator) + render_pane.rs (pane/level renderers); no cross-dependency confirmed - Correct operator_env.rs total: 1569→2130L (880L production); update 4 occurrences across hot-spot table, ASCII tree, §4 analysis Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 28 — op_picker/mod.rs 3-file split, count corrections - Add op_picker/mod.rs formal 3-file split: loading.rs (async load family ~120L) + keys.rs (4 level key handlers ~315L) + mod.rs (types/constructors) - Correct "24 files" → "28+" for 500L threshold count - Update total LOC: ~40,664 → ~43,587 (2 occurrences, with provenance note) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 29 — op_picker execution order + file_browser analysis - §10 Step 4f: expand from 5 to 7 sub-steps; add 4f-vi (op_picker/mod.rs → mod.rs + loading.rs + keys.rs) and 4f-vii (op_picker/render.rs → render.rs + pane.rs); document impl-extension and import-path caveats - §4 //! exemplars: add file_browser/ subsystem analysis — all 5 files have //! docs, no file exceeds ~350L production; classified as exemplar (not a split candidate); document git_prompt.rs coupling-density justification and input.rs as 28-file false positive (144L production) - §1 module map: expand single file_browser/ row to 5 individual rows with production LOC and dominant concern per file Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 30 — challenge split-first thesis, fresh LOC corrections - §4: Add "Alternative thesis: documentation-first verification" — challenges the two core assumptions behind file splitting (files-as-audit-unit and file-size-as-context-constraint); adds 7-criterion comparison table vs structure-first approach; introduces phased combined recommendation: Phase 1 = doc sprint (//! contracts + specs/ for 3 subsystems, 2-3 PRs, zero structural change); Phase 2 = splits only for >600L production files (reduces scope from 14+ to 4 files); Phase 3 = workspace if LOC > 150K - Fix stale LOC: app/mod.rs 951→979, config/editor.rs 1467→1548 (7 and 8 locations respectively; verified by fresh find|xargs wc -l scan) - §1 module map: add agent_picker.rs (436L), scope_picker.rs (201L), source_picker.rs (244L) — all PR #171 additions with //! docs 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 31 — fix 600L→800L threshold error, correct LOC - §4 alternative thesis: correct ">600L production → 4 files" claim introduced in iteration 30; re-verified all 9 candidate files via #[cfg(test)] line position; threshold must be >800L to get exactly 4 files (9 exceed 600L); add verification table with test-start lines - Production LOC corrections (5+ locations each): launch.rs 1085→~1077, operator_env.rs 810→~880, app/mod.rs 928→~957, config/editor.rs 503→~584 - §2 OpPicker row: replace vague "no entry yet" with confirmed gap: PROJECT_STRUCTURE.md line 53 still lists pre-PR#171 widget set (10 named); omits op_picker/, agent_picker.rs, scope_picker.rs, source_picker.rs and pre-dates the manager/ sub-structure split 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 32 — two-tier spec arch, behavioral spec template - §8.1: Add two-tier spec architecture table distinguishing feature specs (public Starlight MDX, user-facing) from behavioral specs (internal docs/internal/specs/, for AI code verification) — resolves contradiction between §4 (which said docs/internal/specs/) and §8.1 (which said "no longer needed; specs are public") - §8.1: Add concrete behavioral spec template for op_picker/ with state machine table and 3 INV invariant entries each with a grep-executable "Verify by:" command; template directly usable for the 3 Phase 1 specs - §8.1: Remove erroneous "docs/internal/specs/ no longer needed" claim - Confirmed render/editor.rs ~736L and render/list.rs ~668L production (no interspersed production code — all test blocks follow consecutively) 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 33 — executive summary, §0 correctness - §0: Add executive summary (~300 words) with core problem, 3-phase recommendation, key counter-argument, and navigation table pointing to §2/§4/§7/§8/§10 by question — resolves the meta-irony of a readability roadmap with no entry-point orientation - §0 item 2: "1569-line monolith" → "2130-line monolith" (operator_env.rs current verified size; stale reference was in the first section readers see) - §0 item 3: Add "(selective)" qualifier and explicit note that standard Rust co-locates struct+impl — impl-extension pattern is justified only for files >800L production, not as a universal rule 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 34 — spec priority reorder, §10 Phase 1 track - §0 + §4 Phase 1: Prioritize runtime/launch.rs behavioral spec (no //! doc, ~1077L production, critical path — all jackin load failures trace here); drop config/editor.rs from Phase 1 (its 963L test suite already serves as behavioral spec — tests are behavioral examples); reduce Phase 1 from 3 specs to 2 specs; add reasoning for the priority ordering - §10 Step 2: Split into two parallel tracks — Track A (cc-sdd tooling setup) + Track B (Phase 1 behavioral spec authoring); Track B includes specific INV invariants to capture for runtime/launch.rs grounded in reading the actual function structure (step comment positions); adds sequencing rationale: spec must precede structural splits 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 35 — verified INV entries for runtime/launch.rs Read load_agent_with lines 553-892 in full. Replaced 3 draft INVs from iteration 34 (inferred from step comment positions) with 5 verified INVs citing exact line numbers: - INV-1: trust gate (line 594) precedes image build (line 736) - INV-2: container name claimed (line 754) between image build and network - INV-3: token verified (line 763) before network creation (line 827) - INV-4: render_exit called at lines 886 AND 890 (all exit paths) - INV-5: cleanup disarm semantics — Running→disarm, clean exit→cleanup, crash→disarm (explains jackin hardline compatibility) Corrected wrong line number: claim_container_name call is at 754, not 918 (918 is the function definition). Each INV has a grep-executable Verify by. 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 36 — CI gate for PROJECT_STRUCTURE.md freshness §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with three concrete options: - Option A: CONTRIBUTING.md rule (necessary but insufficient) - Option B: ci.yml git-diff-scoped shell check (recommended) — only checks files added in the current PR so it doesn't require fixing existing stale entries before merging; greps for module directory name in prose - Option C: Structured TOML module registry (over-engineered for scale) Includes concrete YAML snippet for Option B grounded in the check:repo-links.ts pattern already established in docs/scripts/ 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): iterations 36-37 — CI gate + greenfield workspace architecture Iteration 36: - §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with 3 options (CONTRIBUTING.md rule / ci.yml git-diff check / TOML registry); recommend Option B (git-diff-scoped YAML step) with concrete snippet grounded in existing check:repo-links.ts pattern from docs/scripts/ Iteration 37 (operator directive: greenfield Rust structure): - §4: Add "Greenfield architecture — ideal structure for a growing project" section based on verified cross-module dependency graph (grep iteration 37) - Confirms dependency tiers: workspace/manifest/docker/paths/selector = Tier 0; config/tui/instance = Tier 1; operator_env/runtime/repo = Tier 2; console = Tier 3 - Key finding: workspace/ is LOWER-level than config/ (config re-exports workspace types at lines 5-6); ideal naming inverted in greenfield (jackin-core > jackin-config) - Documents ideal 6-crate workspace: jackin-core, jackin-config, jackin-tui, jackin-runtime, jackin-console, jackin-shell + thin binary - Notes console/ has NO runtime/ import — cleanest pre-existing crate boundary - Bridge: incremental splits (4a, 4d, 4g) are pre-work toward workspace migration 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 38 — Rust workspace standards, community evidence Ground workspace recommendation in real-world project research: - ripgrep (9 crates), gitui (5 crates) went workspace due to library consumers - starship and fd-find stay single-crate at 1M+ LOC — no library use case - jackin (43K LOC, no external consumers) maps to starship/fd pattern → single-crate is community-standard; "stay single-crate" recommendation confirmed Update greenfield workspace structure to follow matklad's pattern: - Virtual manifest at root (no [package] in root Cargo.toml) - Flat crates/ directory (not nested); crate names match folder names - version = "0.0.0" for unpublished internal crates - Add inline dep comments to each crate in the ASCII structure Add research notes: ripgrep/starship/gitui/fd-find Cargo.toml findings + Cargo workspaces reference + matklad "Large Rust Workspaces" (2021-08-22) 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): revise §7.9 + §3 — adopt per-directory README.md §7.9: Reverse previous "reject" recommendation to "adopt" per-directory README.md for major src/ module directories. Rationale: README.md is AI-native — Claude Code, Copilot, Cursor load it automatically on directory entry, giving AI agents orientation before they decide which file to open. PROJECT_STRUCTURE.md being confirmed stale removes the main argument for the "single root file" approach. Add three-layer documentation model table: - README.md: directory orientation (AI + human, on entry) - AGENTS.md: agent workflow rules (root, session start) - CLAUDE.md: @AGENTS.md pointer only — NEVER add content here - //! docs: file-level contracts (when reading/editing) Add specific README.md content targets for 7 directories (src/, src/runtime/, src/console/, src/console/manager/, src/console/widgets/, docs/, docs/internal/). §3 target document shape: Add per-directory README.md to proposed hierarchy; add docs/internal/specs/ explicitly; note CLAUDE.md design principle (single-line @AGENTS.md — never duplicate content). 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): internal docs are browsable — unified Starlight site Operator directive: internal docs (architecture, specs, ADRs, roadmap) should be browsable, not hidden filesystem files. They are a different TYPE of docs focused on implementation details and vision, published as a "Developer Reference" section of the Starlight site. §3 target document shape: - docs/internal/ moves into docs/src/content/docs/internal/ (Starlight pages) - Browsable at jackin.tailrocks.com/internal/ - Sidebar: "Developer Reference" group (collapsed by default) with sub-sections for architecture, code-tour, contributing, testing, decisions, specs, roadmap - Include astro.config.ts sidebar config snippet §8.1 two-tier spec distinction eliminated: - Feature specs and behavioral specs both live at docs/src/content/docs/internal/specs/ - Type expressed via spec_type: behavioral | feature frontmatter, not filesystem location - Both browsable and searchable via Starlight; AI agents can be pointed to URLs §8.3 + §4: - All docs/internal/specs/ paths → docs/src/content/docs/internal/specs/ - ADRs: docs/internal/decisions/ → docs/src/content/docs/internal/decisions/ (browsable) - README.md pointer for src/runtime/ updated to URL reference 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): §11 — modern Rust docs platform (future project) Add §11 capturing the vision for a modern docs.rs alternative with: - rustdoc JSON ingestion → Astro Starlight presentation - MCP server for AI agent queries (Context7 alternative for Rust) - Rust-specific query types: rust_get_context(), rust_find_impls(), rust_search_types() — things Context7 cannot provide - Comparison table vs Context7 - Architecture diagram (ingestion → processing → Starlight + MCP) - Name candidates: rustlight, ferrodoc, cargo-starlight / starlight.rs - Note that jackin's §7.15 gen-rust-api.ts pipeline is the intentional prototype for the platform's processing and presentation layers 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 39 — update §0, fix stale internal/ paths §0 executive summary: rewrite to reflect decisions from iterations 30-38: - browsable internal docs (jackin.tailrocks.com/internal/) - per-directory README.md adoption (§7.9 reversed) - CLAUDE.md = @AGENTS.md single-line pointer only - greenfield workspace architecture (matklad's virtual manifest pattern) - §11 future project: modern Rust docs platform / Context7-for-Rust - document size 1800+ → 2200+ Fix stale docs/internal/ bare paths not caught by iteration 38 sweep: - Mermaid diagram: INTERNAL_ROADMAP, INTERNAL_CODE_TOUR → Starlight paths - §7.10 ADRs: docs/internal/decisions/NNN-title.md → .mdx Starlight path - §10 Track B item 2: op-picker spec path → Starlight MDX 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 40 — §7.15 pipeline + Rule 4 pub audit §7.15 (new): rustdoc JSON → Astro Starlight API documentation pipeline - Three options: rustdoc HTML publish / rustdoc JSON + bun script (recommended) / rustdoc-json crate as Rust binary - Option B recommended: matches existing docs/scripts/ pattern, nightly isolated to separate CI step, zero effect on stable build - Key design: URL at /internal/api/, cross-links to behavioral specs, Starlight unified search, prototype for §11 future project - Pub(crate) note: gen-rust-api.ts can feed Rule 4 visibility audit - Recommend: adopt after Phase 1 //! sprint (value ∝ coverage) §4 Rule 4 pub discipline: replace estimated "50-100 items" guess with verified numbers from iteration 40 grep: - 257 bare pub items, 21 pub(crate), 61 pub(super) across 94 files - 0 uses of unreachable_pub lint — no enforcement gate - Top violators: operator_env.rs (17), tui/output.rs (13), planner.rs (8) - Add concrete Cargo.toml [lints.rust] snippet: unreachable_pub = "warn" - Revised scope: ~150-200 mechanical conversions (excludes entry points) 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): split research into 19 actionable items Delete _research_notes.md (no longer needed). Replace 2343L READABILITY_AND_MODERNIZATION.md with: - README.md: index of all 19 items with phase, ordering notes, links - READABILITY_AND_MODERNIZATION.md: lightweight research summary (63L) - items/ITEM-001 through ITEM-019: individual actionable items Items by phase: Phase 1 (low risk, no confirmation): ITEM-001..004, 006..011 Phase 1 (needs confirmation): ITEM-005, 016, 018 Phase 2 (structural splits, confirmation required): ITEM-012..015 Phase 3 (deferred): ITEM-017 (rustdoc pipeline), ITEM-019 (workspace) Each item has: summary, key files with line numbers, steps, what needs confirmation, and relevant research backing from the 40-iteration analysis loop. 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): migrate 19 items to Starlight reference/roadmap section Move all codebase health roadmap items from docs/internal/roadmap/items/ (plain Markdown, not browsable) to docs/src/content/docs/reference/roadmap/ (MDX pages, browsable at jackin.tailrocks.com/reference/roadmap/). Adds a new "Codebase health" sidebar group (Phase 1 → Phase 3) to astro.config.ts. Deletes the old items/ directory. Updates the internal README to redirect to the new location. Also adds codebase-readability.mdx — a new overview item that captures the overall readability/restructuring program with a recommended execution order: file splits first, then greenfield workspace, then per-directory README+AGENTS.md, then docs and specs. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): remove premature internal/roadmap/README.md The internal/ structure doesn't exist yet — it will be created as part of the roadmap items themselves. No need for a redirect stub now. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): remove READABILITY_AND_MODERNIZATION.md research archive All content has been distilled into the individual Starlight roadmap pages. The full 2343L research is preserved in git history at commit b7e9fc2. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): fix check:repo-links errors + remove iteration log - Replace plain code spans with <RepoFile> for validate.rs, mise.toml, Cargo.toml, and op_picker/mod.rs - Remove deleted READABILITY_AND_MODERNIZATION.md reference from codebase-readability.mdx - Delete _iteration_log.md (git history is the archive) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): fix lychee false-positive link in move-contributing-testing The example redirect text contained a markdown hyperlink to a proposed future file path that doesn't exist yet. Changed to a code span. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> --------- Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Co-authored-by: Claude <noreply@anthropic.com>
donbeave
added a commit
that referenced
this pull request
May 6, 2026
Finalizes v1 requirements for per-mount isolation (from #116) after a full decision sweep. Still docs-only — no implementation. User-facing decisions: - Back-merge is upstream only (GitHub PR via existing tooling). No jackin diff / jackin integrate / merge commands. - Dirty host tree warns and requires --force (cold path since operators launch from clean trees). - Hooks inherit from the host repo; no --no-hooks flag in v1. - Branch name hardcoded as jackin/<container>; base = host HEAD. No configurable branch_template or base_branch. - Worktree at <data_dir>/jackin-<container>/isolated/<slug>/. - jackin cd <container> for navigation. Scope trims: - Drop default_isolation. isolation is per-mount only, explicit. - Drop isolation on global mounts entirely (workspace-scoped only). - Drop --delete-branches flag on purge; purge silently deletes everything, including the local scratch branch. Correctness: - Pre-flight validation scoped per isolation type; only checks cases where git would silently do the wrong thing (subdir misrouting, mid-rebase HEAD). - Purge refuses on running agents (fixes a pre-existing gap where remove_data_dir_if_exists ran unconditionally). - Enable extensions.worktreeConfig on first worktree creation per host repo so per-worktree config writes don't leak to shared .git/config. - Mount mode flipped between loads: orphan isolated/ dir left in place, reclaimed by jackin purge. No auto-prune. Known limitations documented: submodules/LFS inherit parent-repo behavior; shared .git/config for remotes/credentials/non-worktree writes (git limitation); -clone-N naming collision to resolve when clone mode ships. Co-authored-by: Claude <noreply@anthropic.com>
donbeave
added a commit
that referenced
this pull request
May 6, 2026
…183) * docs(roadmap): iteration 13 — AI code verifiability framing, config/types.rs full spec Primary goal shift: codebase must be verifiable for AI-generated code. - §0: replace generic description with explicit verifiability rationale (module contracts, localised concerns, types/behaviour separation) - §4 intro: add "Why structure matters for AI-generated code" section with audit-units table mapping each post-split file to one reviewable question - §4 4a: expand config/types.rs from description to full execution spec — exact type list, post-split mod.rs content, zero-change submodule guarantee (verified: agents.rs/persist.rs/workspaces.rs use super::T which resolves through mod.rs re-exports unchanged), impl-extension pattern already in use documented Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 14 — editor method map, app helpers, //! queue - §4 4c: config/editor.rs split is now execution-ready — complete 6-file method-to-file table with private helper placement verified (validate_candidate→io.rs, table_path_mut→mod.rs pub(super), auth_forward_str→agent_ops.rs, create_workspace delegates to AppConfig) - §4 4e: app/mod.rs split complete — all private helpers mapped (parse_auth_forward_mode_from_cli→config_cmd.rs, workspace_env_scope→workspace_cmd.rs, print_env_table note, remove_data_dir_if_exists→dispatch.rs) - §10 step 5: add //! priority queue — 10 files with draft content, prioritised by cold-landing impact and AI audit risk; selector.rs and instance/mod.rs explicitly document the /→__ invariant Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 15 — dep graph fix, trust.rs safety, OQ1 closed - §4 4d: correct operator_env dependency graph — layers.rs imports both mod.rs (OpRunner) AND client.rs (OpCli for non-injectable resolve_operator_env wrapper at line 797); still a valid DAG - §4 4f: verify trust.rs split safety — FnOnce injection pattern means launch_pipeline.rs has zero dependency on trust.rs; import chain documented; trust bypass audit now requires reading only ~60L - §9 OQ1 closed: op_cache.rs read in full — 4-level structure, per-level invalidation, no TTL/expiry (expiry handled at OpCli subprocess level), DEFAULT_ACCOUNT_KEY sentinel documented Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 16 — CommandRunner Rule 3, render/editor split, 4a/4c independence - Fix duplicate Rule 3 section introduced by previous edit; add docker.rs co-location note as third edge case (three edge cases, not two) - Add render/editor.rs as new Rule 5 violator: 1666L post-PR #171 (was listed as 782L); propose 6-file tab-by-tab split with auditability note on the security-adjacent Secrets tab - Add §10 execution-order note: 4a and 4c are independent — editor.rs imports AppConfig via crate::config re-exports regardless of 4a order - Append iteration 16 log entry with confidence table and weakest sections Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 17 — instance/auth.rs audit, state.rs split, line count corrections - Add instance/auth.rs to //! priority queue at #4: four security invariants (0o600 perms, symlink rejection, TOCTOU-safe writes, macOS Keychain) documented in draft //! content - Add state.rs as new Rule 5 violator: 992L/628L production; 26+ types mixed with impl blocks; propose 5-file types/behavior split - Correct stale line counts: render/list.rs 1122→1989 (PR #171 added render_environments_subpanel); state.rs 865→992; priorities upgraded - Fix §7.9 snapshot function line refs: sentinel_description_pane 306→332, mounts_subpanel 408→433, render_tab_strip 180→269, test ref 720→944 - Renumber //! priority queue to 11 entries (was 10) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 18 — agent_allow OQ2 closed, render/list.rs split proposal - Close OQ2: agent_allow.rs read in full — 55L, correct //! doc, design sound; serves as model for //! priority queue pattern - Add render/list.rs as new Rule 5 violator: 668L production (PR #171 added render_environments_subpanel); propose 3-file split (mod.rs, details.rs, subpanels.rs); note import-path change for agents_block_agent_count - Update §1 module map: agent_allow.rs entry corrected with size/API Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 19 — input/editor.rs critical correction, split proposal - Correct input/editor.rs: 2349L total (was 1304L), 1141L production (was 547L) — PR #171 added Secrets-tab handlers; pub(super) fn handle_editor_modal at line 618 was invisible to previous grep pattern; now the largest production file in the codebase; priority → Critical - Correct input/save.rs: 1472L total, 661L production (was 567L) - Add 5-file split proposal for input/editor.rs: mod.rs (two dispatchers), secrets.rs (~500L AI-generated Secrets-tab), agents.rs, mounts.rs, general.rs - Update key insight paragraph naming input/editor.rs as largest production file Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 20 — console splits in §10, MSRV evidence, animation.rs verdict - Add console/manager/ as §10 Step 4f group with 5 sub-steps in priority order; rename existing 4f (launch.rs) → 4g; add circular-import risk note for ManagerStage/EditorState split sequencing - Analyze tui/animation.rs: 582L all-production, no split needed (banner_grid is a tightly-coupled rendering loop); section comments compensate for missing //! - Partially close OQ3: u64::is_multiple_of (stabilized 1.86) found in animation.rs; within declared MSRV 1.94; full cargo +1.94.0 check deferred (toolchain unavailable) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 21 — input/save.rs split, //! queue fix, save.rs corrections - Add input/save.rs split proposal: 4 pub(super) fns discovered; 3-file split (mod.rs + flow.rs + preview.rs); no cross-dependency between flow and preview groups; §10 4f-v updated from Optional to concrete plan - Fix //! queue preamble: "first 10 files" → "first 11 files" - Correct save.rs module map (1418→1472L, correct key exports) and hot-spot table note (begin_editor_save ~280L → ~118L; commit_editor_save is the Phase 2 partner at ~149L) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 22 — input/list.rs and mount_info.rs analysis - Analyze input/list.rs: 214L production (tests at 215); has //! doc; two focused pub(super) fns; no split needed; Low priority; correct module map - Add mount_info.rs to hot-spot table: 277L production; Low priority; has //! doc; correct module map with 3 public enums + inspect fn - Fix stale §2 diagnosis note: docs/internal/roadmap/ now exists Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 23 — audit units table +5 console rows, input/mod.rs corrected - Expand audit units table from 8 to 13 entries: add state/types.rs, state/editor.rs, input/editor/secrets.rs, render/list/subpanels.rs, input/save/preview.rs — all targeting PR #171 AI-generated console code - Add PR #171 context note linking 5 new entries to AI-generated code concern - Correct input/mod.rs module map: 369L, add InputOutcome enum to exports - Verify rust-toolchain.toml absence; §7.7 and §2 concept 25 already correct Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 24 — render/mod.rs analysis, //! exemplars table, EditorTab confirmed - Add §4 Rule 7 positive exemplars table: 7 files with //! docs graded 1-element (render/mod.rs), 2-element (input/save.rs etc), 3-element (env_model.rs, agent_allow.rs); PR #171 docs-discipline pattern noted - Correct render/mod.rs module map: 421L; FooterItem + palette constants + render_header + centered_rect_fixed added to key exports - Confirm EditorTab variants: General, Mounts, Agents, Secrets (Rust enum) vs "Secrets / Environments" (UI label); /stub qualifier already removed Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 25 — too_many_lines recount, FooterItem PR, MountConfig caveat - Correct too_many_lines count: 13 across 8 → 16 across 11 files (PR #171 added 5 suppressions in console/manager); add full breakdown table; update all 3 occurrences in roadmap - Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow) - Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 26 — console/mod.rs and op_picker/render.rs analyzed - Add console/mod.rs to hot-spot table: 406L/307L production (Low); correct module map from ~200 → 406L; note missing //! doc with ConsoleStage design block comment worth promoting - Add op_picker/render.rs to hot-spot table: 865L/545L production (Medium); PR #171 AI-generated; 14 functions in two logical groups (entry/helpers vs level renderers); split into levels.rs proposed - Correct 3 stale ~200L estimates for console/mod.rs across roadmap Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 27 — op_picker/mod.rs discovery, render split, operator_env correction - Add op_picker/mod.rs to hot-spot table: 1712L/775L production (High); PR #171 AI-generated; OpPickerState types+behavior split opportunity; has 7-line //! doc; module map split into two rows (mod.rs + render.rs) - Add op_picker/render.rs 2-file split proposal: render.rs (coordinator) + render_pane.rs (pane/level renderers); no cross-dependency confirmed - Correct operator_env.rs total: 1569→2130L (880L production); update 4 occurrences across hot-spot table, ASCII tree, §4 analysis Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 28 — op_picker/mod.rs 3-file split, count corrections - Add op_picker/mod.rs formal 3-file split: loading.rs (async load family ~120L) + keys.rs (4 level key handlers ~315L) + mod.rs (types/constructors) - Correct "24 files" → "28+" for 500L threshold count - Update total LOC: ~40,664 → ~43,587 (2 occurrences, with provenance note) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 29 — op_picker execution order + file_browser analysis - §10 Step 4f: expand from 5 to 7 sub-steps; add 4f-vi (op_picker/mod.rs → mod.rs + loading.rs + keys.rs) and 4f-vii (op_picker/render.rs → render.rs + pane.rs); document impl-extension and import-path caveats - §4 //! exemplars: add file_browser/ subsystem analysis — all 5 files have //! docs, no file exceeds ~350L production; classified as exemplar (not a split candidate); document git_prompt.rs coupling-density justification and input.rs as 28-file false positive (144L production) - §1 module map: expand single file_browser/ row to 5 individual rows with production LOC and dominant concern per file Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): iteration 30 — challenge split-first thesis, fresh LOC corrections - §4: Add "Alternative thesis: documentation-first verification" — challenges the two core assumptions behind file splitting (files-as-audit-unit and file-size-as-context-constraint); adds 7-criterion comparison table vs structure-first approach; introduces phased combined recommendation: Phase 1 = doc sprint (//! contracts + specs/ for 3 subsystems, 2-3 PRs, zero structural change); Phase 2 = splits only for >600L production files (reduces scope from 14+ to 4 files); Phase 3 = workspace if LOC > 150K - Fix stale LOC: app/mod.rs 951→979, config/editor.rs 1467→1548 (7 and 8 locations respectively; verified by fresh find|xargs wc -l scan) - §1 module map: add agent_picker.rs (436L), scope_picker.rs (201L), source_picker.rs (244L) — all PR #171 additions with //! docs 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 31 — fix 600L→800L threshold error, correct LOC - §4 alternative thesis: correct ">600L production → 4 files" claim introduced in iteration 30; re-verified all 9 candidate files via #[cfg(test)] line position; threshold must be >800L to get exactly 4 files (9 exceed 600L); add verification table with test-start lines - Production LOC corrections (5+ locations each): launch.rs 1085→~1077, operator_env.rs 810→~880, app/mod.rs 928→~957, config/editor.rs 503→~584 - §2 OpPicker row: replace vague "no entry yet" with confirmed gap: PROJECT_STRUCTURE.md line 53 still lists pre-PR#171 widget set (10 named); omits op_picker/, agent_picker.rs, scope_picker.rs, source_picker.rs and pre-dates the manager/ sub-structure split 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 32 — two-tier spec arch, behavioral spec template - §8.1: Add two-tier spec architecture table distinguishing feature specs (public Starlight MDX, user-facing) from behavioral specs (internal docs/internal/specs/, for AI code verification) — resolves contradiction between §4 (which said docs/internal/specs/) and §8.1 (which said "no longer needed; specs are public") - §8.1: Add concrete behavioral spec template for op_picker/ with state machine table and 3 INV invariant entries each with a grep-executable "Verify by:" command; template directly usable for the 3 Phase 1 specs - §8.1: Remove erroneous "docs/internal/specs/ no longer needed" claim - Confirmed render/editor.rs ~736L and render/list.rs ~668L production (no interspersed production code — all test blocks follow consecutively) 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 33 — executive summary, §0 correctness - §0: Add executive summary (~300 words) with core problem, 3-phase recommendation, key counter-argument, and navigation table pointing to §2/§4/§7/§8/§10 by question — resolves the meta-irony of a readability roadmap with no entry-point orientation - §0 item 2: "1569-line monolith" → "2130-line monolith" (operator_env.rs current verified size; stale reference was in the first section readers see) - §0 item 3: Add "(selective)" qualifier and explicit note that standard Rust co-locates struct+impl — impl-extension pattern is justified only for files >800L production, not as a universal rule 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 34 — spec priority reorder, §10 Phase 1 track - §0 + §4 Phase 1: Prioritize runtime/launch.rs behavioral spec (no //! doc, ~1077L production, critical path — all jackin load failures trace here); drop config/editor.rs from Phase 1 (its 963L test suite already serves as behavioral spec — tests are behavioral examples); reduce Phase 1 from 3 specs to 2 specs; add reasoning for the priority ordering - §10 Step 2: Split into two parallel tracks — Track A (cc-sdd tooling setup) + Track B (Phase 1 behavioral spec authoring); Track B includes specific INV invariants to capture for runtime/launch.rs grounded in reading the actual function structure (step comment positions); adds sequencing rationale: spec must precede structural splits 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 35 — verified INV entries for runtime/launch.rs Read load_agent_with lines 553-892 in full. Replaced 3 draft INVs from iteration 34 (inferred from step comment positions) with 5 verified INVs citing exact line numbers: - INV-1: trust gate (line 594) precedes image build (line 736) - INV-2: container name claimed (line 754) between image build and network - INV-3: token verified (line 763) before network creation (line 827) - INV-4: render_exit called at lines 886 AND 890 (all exit paths) - INV-5: cleanup disarm semantics — Running→disarm, clean exit→cleanup, crash→disarm (explains jackin hardline compatibility) Corrected wrong line number: claim_container_name call is at 754, not 918 (918 is the function definition). Each INV has a grep-executable Verify by. 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 36 — CI gate for PROJECT_STRUCTURE.md freshness §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with three concrete options: - Option A: CONTRIBUTING.md rule (necessary but insufficient) - Option B: ci.yml git-diff-scoped shell check (recommended) — only checks files added in the current PR so it doesn't require fixing existing stale entries before merging; greps for module directory name in prose - Option C: Structured TOML module registry (over-engineered for scale) Includes concrete YAML snippet for Option B grounded in the check:repo-links.ts pattern already established in docs/scripts/ 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): iterations 36-37 — CI gate + greenfield workspace architecture Iteration 36: - §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with 3 options (CONTRIBUTING.md rule / ci.yml git-diff check / TOML registry); recommend Option B (git-diff-scoped YAML step) with concrete snippet grounded in existing check:repo-links.ts pattern from docs/scripts/ Iteration 37 (operator directive: greenfield Rust structure): - §4: Add "Greenfield architecture — ideal structure for a growing project" section based on verified cross-module dependency graph (grep iteration 37) - Confirms dependency tiers: workspace/manifest/docker/paths/selector = Tier 0; config/tui/instance = Tier 1; operator_env/runtime/repo = Tier 2; console = Tier 3 - Key finding: workspace/ is LOWER-level than config/ (config re-exports workspace types at lines 5-6); ideal naming inverted in greenfield (jackin-core > jackin-config) - Documents ideal 6-crate workspace: jackin-core, jackin-config, jackin-tui, jackin-runtime, jackin-console, jackin-shell + thin binary - Notes console/ has NO runtime/ import — cleanest pre-existing crate boundary - Bridge: incremental splits (4a, 4d, 4g) are pre-work toward workspace migration 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 38 — Rust workspace standards, community evidence Ground workspace recommendation in real-world project research: - ripgrep (9 crates), gitui (5 crates) went workspace due to library consumers - starship and fd-find stay single-crate at 1M+ LOC — no library use case - jackin (43K LOC, no external consumers) maps to starship/fd pattern → single-crate is community-standard; "stay single-crate" recommendation confirmed Update greenfield workspace structure to follow matklad's pattern: - Virtual manifest at root (no [package] in root Cargo.toml) - Flat crates/ directory (not nested); crate names match folder names - version = "0.0.0" for unpublished internal crates - Add inline dep comments to each crate in the ASCII structure Add research notes: ripgrep/starship/gitui/fd-find Cargo.toml findings + Cargo workspaces reference + matklad "Large Rust Workspaces" (2021-08-22) 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): revise §7.9 + §3 — adopt per-directory README.md §7.9: Reverse previous "reject" recommendation to "adopt" per-directory README.md for major src/ module directories. Rationale: README.md is AI-native — Claude Code, Copilot, Cursor load it automatically on directory entry, giving AI agents orientation before they decide which file to open. PROJECT_STRUCTURE.md being confirmed stale removes the main argument for the "single root file" approach. Add three-layer documentation model table: - README.md: directory orientation (AI + human, on entry) - AGENTS.md: agent workflow rules (root, session start) - CLAUDE.md: @AGENTS.md pointer only — NEVER add content here - //! docs: file-level contracts (when reading/editing) Add specific README.md content targets for 7 directories (src/, src/runtime/, src/console/, src/console/manager/, src/console/widgets/, docs/, docs/internal/). §3 target document shape: Add per-directory README.md to proposed hierarchy; add docs/internal/specs/ explicitly; note CLAUDE.md design principle (single-line @AGENTS.md — never duplicate content). 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): internal docs are browsable — unified Starlight site Operator directive: internal docs (architecture, specs, ADRs, roadmap) should be browsable, not hidden filesystem files. They are a different TYPE of docs focused on implementation details and vision, published as a "Developer Reference" section of the Starlight site. §3 target document shape: - docs/internal/ moves into docs/src/content/docs/internal/ (Starlight pages) - Browsable at jackin.tailrocks.com/internal/ - Sidebar: "Developer Reference" group (collapsed by default) with sub-sections for architecture, code-tour, contributing, testing, decisions, specs, roadmap - Include astro.config.ts sidebar config snippet §8.1 two-tier spec distinction eliminated: - Feature specs and behavioral specs both live at docs/src/content/docs/internal/specs/ - Type expressed via spec_type: behavioral | feature frontmatter, not filesystem location - Both browsable and searchable via Starlight; AI agents can be pointed to URLs §8.3 + §4: - All docs/internal/specs/ paths → docs/src/content/docs/internal/specs/ - ADRs: docs/internal/decisions/ → docs/src/content/docs/internal/decisions/ (browsable) - README.md pointer for src/runtime/ updated to URL reference 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): §11 — modern Rust docs platform (future project) Add §11 capturing the vision for a modern docs.rs alternative with: - rustdoc JSON ingestion → Astro Starlight presentation - MCP server for AI agent queries (Context7 alternative for Rust) - Rust-specific query types: rust_get_context(), rust_find_impls(), rust_search_types() — things Context7 cannot provide - Comparison table vs Context7 - Architecture diagram (ingestion → processing → Starlight + MCP) - Name candidates: rustlight, ferrodoc, cargo-starlight / starlight.rs - Note that jackin's §7.15 gen-rust-api.ts pipeline is the intentional prototype for the platform's processing and presentation layers 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 39 — update §0, fix stale internal/ paths §0 executive summary: rewrite to reflect decisions from iterations 30-38: - browsable internal docs (jackin.tailrocks.com/internal/) - per-directory README.md adoption (§7.9 reversed) - CLAUDE.md = @AGENTS.md single-line pointer only - greenfield workspace architecture (matklad's virtual manifest pattern) - §11 future project: modern Rust docs platform / Context7-for-Rust - document size 1800+ → 2200+ Fix stale docs/internal/ bare paths not caught by iteration 38 sweep: - Mermaid diagram: INTERNAL_ROADMAP, INTERNAL_CODE_TOUR → Starlight paths - §7.10 ADRs: docs/internal/decisions/NNN-title.md → .mdx Starlight path - §10 Track B item 2: op-picker spec path → Starlight MDX 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 40 — §7.15 pipeline + Rule 4 pub audit §7.15 (new): rustdoc JSON → Astro Starlight API documentation pipeline - Three options: rustdoc HTML publish / rustdoc JSON + bun script (recommended) / rustdoc-json crate as Rust binary - Option B recommended: matches existing docs/scripts/ pattern, nightly isolated to separate CI step, zero effect on stable build - Key design: URL at /internal/api/, cross-links to behavioral specs, Starlight unified search, prototype for §11 future project - Pub(crate) note: gen-rust-api.ts can feed Rule 4 visibility audit - Recommend: adopt after Phase 1 //! sprint (value ∝ coverage) §4 Rule 4 pub discipline: replace estimated "50-100 items" guess with verified numbers from iteration 40 grep: - 257 bare pub items, 21 pub(crate), 61 pub(super) across 94 files - 0 uses of unreachable_pub lint — no enforcement gate - Top violators: operator_env.rs (17), tui/output.rs (13), planner.rs (8) - Add concrete Cargo.toml [lints.rust] snippet: unreachable_pub = "warn" - Revised scope: ~150-200 mechanical conversions (excludes entry points) 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): split research into 19 actionable items Delete _research_notes.md (no longer needed). Replace 2343L READABILITY_AND_MODERNIZATION.md with: - README.md: index of all 19 items with phase, ordering notes, links - READABILITY_AND_MODERNIZATION.md: lightweight research summary (63L) - items/ITEM-001 through ITEM-019: individual actionable items Items by phase: Phase 1 (low risk, no confirmation): ITEM-001..004, 006..011 Phase 1 (needs confirmation): ITEM-005, 016, 018 Phase 2 (structural splits, confirmation required): ITEM-012..015 Phase 3 (deferred): ITEM-017 (rustdoc pipeline), ITEM-019 (workspace) Each item has: summary, key files with line numbers, steps, what needs confirmation, and relevant research backing from the 40-iteration analysis loop. 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): migrate 19 items to Starlight reference/roadmap section Move all codebase health roadmap items from docs/internal/roadmap/items/ (plain Markdown, not browsable) to docs/src/content/docs/reference/roadmap/ (MDX pages, browsable at jackin.tailrocks.com/reference/roadmap/). Adds a new "Codebase health" sidebar group (Phase 1 → Phase 3) to astro.config.ts. Deletes the old items/ directory. Updates the internal README to redirect to the new location. Also adds codebase-readability.mdx — a new overview item that captures the overall readability/restructuring program with a recommended execution order: file splits first, then greenfield workspace, then per-directory README+AGENTS.md, then docs and specs. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): remove premature internal/roadmap/README.md The internal/ structure doesn't exist yet — it will be created as part of the roadmap items themselves. No need for a redirect stub now. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): remove READABILITY_AND_MODERNIZATION.md research archive All content has been distilled into the individual Starlight roadmap pages. The full 2343L research is preserved in git history at commit b7e9fc2. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): fix check:repo-links errors + remove iteration log - Replace plain code spans with <RepoFile> for validate.rs, mise.toml, Cargo.toml, and op_picker/mod.rs - Remove deleted READABILITY_AND_MODERNIZATION.md reference from codebase-readability.mdx - Delete _iteration_log.md (git history is the archive) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> * docs(roadmap): fix lychee false-positive link in move-contributing-testing The example redirect text contained a markdown hyperlink to a proposed future file path that doesn't exist yet. Changed to a code span. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> --------- Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Co-authored-by: Claude <noreply@anthropic.com>
donbeave
added a commit
that referenced
this pull request
May 7, 2026
Finalizes v1 requirements for per-mount isolation (from #116) after a full decision sweep. Still docs-only — no implementation. User-facing decisions: - Back-merge is upstream only (GitHub PR via existing tooling). No jackin diff / jackin integrate / merge commands. - Dirty host tree warns and requires --force (cold path since operators launch from clean trees). - Hooks inherit from the host repo; no --no-hooks flag in v1. - Branch name hardcoded as jackin/<container>; base = host HEAD. No configurable branch_template or base_branch. - Worktree at <data_dir>/jackin-<container>/isolated/<slug>/. - jackin cd <container> for navigation. Scope trims: - Drop default_isolation. isolation is per-mount only, explicit. - Drop isolation on global mounts entirely (workspace-scoped only). - Drop --delete-branches flag on purge; purge silently deletes everything, including the local scratch branch. Correctness: - Pre-flight validation scoped per isolation type; only checks cases where git would silently do the wrong thing (subdir misrouting, mid-rebase HEAD). - Purge refuses on running agents (fixes a pre-existing gap where remove_data_dir_if_exists ran unconditionally). - Enable extensions.worktreeConfig on first worktree creation per host repo so per-worktree config writes don't leak to shared .git/config. - Mount mode flipped between loads: orphan isolated/ dir left in place, reclaimed by jackin purge. No auto-prune. Known limitations documented: submodules/LFS inherit parent-repo behavior; shared .git/config for remotes/credentials/non-worktree writes (git limitation); -clone-N naming collision to resolve when clone mode ships. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Codex <codex@openai.com>
donbeave
added a commit
that referenced
this pull request
May 7, 2026
…183) * docs(roadmap): iteration 13 — AI code verifiability framing, config/types.rs full spec Primary goal shift: codebase must be verifiable for AI-generated code. - §0: replace generic description with explicit verifiability rationale (module contracts, localised concerns, types/behaviour separation) - §4 intro: add "Why structure matters for AI-generated code" section with audit-units table mapping each post-split file to one reviewable question - §4 4a: expand config/types.rs from description to full execution spec — exact type list, post-split mod.rs content, zero-change submodule guarantee (verified: agents.rs/persist.rs/workspaces.rs use super::T which resolves through mod.rs re-exports unchanged), impl-extension pattern already in use documented Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 14 — editor method map, app helpers, //! queue - §4 4c: config/editor.rs split is now execution-ready — complete 6-file method-to-file table with private helper placement verified (validate_candidate→io.rs, table_path_mut→mod.rs pub(super), auth_forward_str→agent_ops.rs, create_workspace delegates to AppConfig) - §4 4e: app/mod.rs split complete — all private helpers mapped (parse_auth_forward_mode_from_cli→config_cmd.rs, workspace_env_scope→workspace_cmd.rs, print_env_table note, remove_data_dir_if_exists→dispatch.rs) - §10 step 5: add //! priority queue — 10 files with draft content, prioritised by cold-landing impact and AI audit risk; selector.rs and instance/mod.rs explicitly document the /→__ invariant Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 15 — dep graph fix, trust.rs safety, OQ1 closed - §4 4d: correct operator_env dependency graph — layers.rs imports both mod.rs (OpRunner) AND client.rs (OpCli for non-injectable resolve_operator_env wrapper at line 797); still a valid DAG - §4 4f: verify trust.rs split safety — FnOnce injection pattern means launch_pipeline.rs has zero dependency on trust.rs; import chain documented; trust bypass audit now requires reading only ~60L - §9 OQ1 closed: op_cache.rs read in full — 4-level structure, per-level invalidation, no TTL/expiry (expiry handled at OpCli subprocess level), DEFAULT_ACCOUNT_KEY sentinel documented Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 16 — CommandRunner Rule 3, render/editor split, 4a/4c independence - Fix duplicate Rule 3 section introduced by previous edit; add docker.rs co-location note as third edge case (three edge cases, not two) - Add render/editor.rs as new Rule 5 violator: 1666L post-PR #171 (was listed as 782L); propose 6-file tab-by-tab split with auditability note on the security-adjacent Secrets tab - Add §10 execution-order note: 4a and 4c are independent — editor.rs imports AppConfig via crate::config re-exports regardless of 4a order - Append iteration 16 log entry with confidence table and weakest sections Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 17 — instance/auth.rs audit, state.rs split, line count corrections - Add instance/auth.rs to //! priority queue at #4: four security invariants (0o600 perms, symlink rejection, TOCTOU-safe writes, macOS Keychain) documented in draft //! content - Add state.rs as new Rule 5 violator: 992L/628L production; 26+ types mixed with impl blocks; propose 5-file types/behavior split - Correct stale line counts: render/list.rs 1122→1989 (PR #171 added render_environments_subpanel); state.rs 865→992; priorities upgraded - Fix §7.9 snapshot function line refs: sentinel_description_pane 306→332, mounts_subpanel 408→433, render_tab_strip 180→269, test ref 720→944 - Renumber //! priority queue to 11 entries (was 10) Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 18 — agent_allow OQ2 closed, render/list.rs split proposal - Close OQ2: agent_allow.rs read in full — 55L, correct //! doc, design sound; serves as model for //! priority queue pattern - Add render/list.rs as new Rule 5 violator: 668L production (PR #171 added render_environments_subpanel); propose 3-file split (mod.rs, details.rs, subpanels.rs); note import-path change for agents_block_agent_count - Update §1 module map: agent_allow.rs entry corrected with size/API Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 19 — input/editor.rs critical correction, split proposal - Correct input/editor.rs: 2349L total (was 1304L), 1141L production (was 547L) — PR #171 added Secrets-tab handlers; pub(super) fn handle_editor_modal at line 618 was invisible to previous grep pattern; now the largest production file in the codebase; priority → Critical - Correct input/save.rs: 1472L total, 661L production (was 567L) - Add 5-file split proposal for input/editor.rs: mod.rs (two dispatchers), secrets.rs (~500L AI-generated Secrets-tab), agents.rs, mounts.rs, general.rs - Update key insight paragraph naming input/editor.rs as largest production file Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 20 — console splits in §10, MSRV evidence, animation.rs verdict - Add console/manager/ as §10 Step 4f group with 5 sub-steps in priority order; rename existing 4f (launch.rs) → 4g; add circular-import risk note for ManagerStage/EditorState split sequencing - Analyze tui/animation.rs: 582L all-production, no split needed (banner_grid is a tightly-coupled rendering loop); section comments compensate for missing //! - Partially close OQ3: u64::is_multiple_of (stabilized 1.86) found in animation.rs; within declared MSRV 1.94; full cargo +1.94.0 check deferred (toolchain unavailable) Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 21 — input/save.rs split, //! queue fix, save.rs corrections - Add input/save.rs split proposal: 4 pub(super) fns discovered; 3-file split (mod.rs + flow.rs + preview.rs); no cross-dependency between flow and preview groups; §10 4f-v updated from Optional to concrete plan - Fix //! queue preamble: "first 10 files" → "first 11 files" - Correct save.rs module map (1418→1472L, correct key exports) and hot-spot table note (begin_editor_save ~280L → ~118L; commit_editor_save is the Phase 2 partner at ~149L) Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 22 — input/list.rs and mount_info.rs analysis - Analyze input/list.rs: 214L production (tests at 215); has //! doc; two focused pub(super) fns; no split needed; Low priority; correct module map - Add mount_info.rs to hot-spot table: 277L production; Low priority; has //! doc; correct module map with 3 public enums + inspect fn - Fix stale §2 diagnosis note: docs/internal/roadmap/ now exists Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 23 — audit units table +5 console rows, input/mod.rs corrected - Expand audit units table from 8 to 13 entries: add state/types.rs, state/editor.rs, input/editor/secrets.rs, render/list/subpanels.rs, input/save/preview.rs — all targeting PR #171 AI-generated console code - Add PR #171 context note linking 5 new entries to AI-generated code concern - Correct input/mod.rs module map: 369L, add InputOutcome enum to exports - Verify rust-toolchain.toml absence; §7.7 and §2 concept 25 already correct Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 24 — render/mod.rs analysis, //! exemplars table, EditorTab confirmed - Add §4 Rule 7 positive exemplars table: 7 files with //! docs graded 1-element (render/mod.rs), 2-element (input/save.rs etc), 3-element (env_model.rs, agent_allow.rs); PR #171 docs-discipline pattern noted - Correct render/mod.rs module map: 421L; FooterItem + palette constants + render_header + centered_rect_fixed added to key exports - Confirm EditorTab variants: General, Mounts, Agents, Secrets (Rust enum) vs "Secrets / Environments" (UI label); /stub qualifier already removed Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 25 — too_many_lines recount, FooterItem PR, MountConfig caveat - Correct too_many_lines count: 13 across 8 → 16 across 11 files (PR #171 added 5 suppressions in console/manager); add full breakdown table; update all 3 occurrences in roadmap - Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow) - Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 26 — console/mod.rs and op_picker/render.rs analyzed - Add console/mod.rs to hot-spot table: 406L/307L production (Low); correct module map from ~200 → 406L; note missing //! doc with ConsoleStage design block comment worth promoting - Add op_picker/render.rs to hot-spot table: 865L/545L production (Medium); PR #171 AI-generated; 14 functions in two logical groups (entry/helpers vs level renderers); split into levels.rs proposed - Correct 3 stale ~200L estimates for console/mod.rs across roadmap Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 27 — op_picker/mod.rs discovery, render split, operator_env correction - Add op_picker/mod.rs to hot-spot table: 1712L/775L production (High); PR #171 AI-generated; OpPickerState types+behavior split opportunity; has 7-line //! doc; module map split into two rows (mod.rs + render.rs) - Add op_picker/render.rs 2-file split proposal: render.rs (coordinator) + render_pane.rs (pane/level renderers); no cross-dependency confirmed - Correct operator_env.rs total: 1569→2130L (880L production); update 4 occurrences across hot-spot table, ASCII tree, §4 analysis Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 28 — op_picker/mod.rs 3-file split, count corrections - Add op_picker/mod.rs formal 3-file split: loading.rs (async load family ~120L) + keys.rs (4 level key handlers ~315L) + mod.rs (types/constructors) - Correct "24 files" → "28+" for 500L threshold count - Update total LOC: ~40,664 → ~43,587 (2 occurrences, with provenance note) Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 29 — op_picker execution order + file_browser analysis - §10 Step 4f: expand from 5 to 7 sub-steps; add 4f-vi (op_picker/mod.rs → mod.rs + loading.rs + keys.rs) and 4f-vii (op_picker/render.rs → render.rs + pane.rs); document impl-extension and import-path caveats - §4 //! exemplars: add file_browser/ subsystem analysis — all 5 files have //! docs, no file exceeds ~350L production; classified as exemplar (not a split candidate); document git_prompt.rs coupling-density justification and input.rs as 28-file false positive (144L production) - §1 module map: expand single file_browser/ row to 5 individual rows with production LOC and dominant concern per file Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 30 — challenge split-first thesis, fresh LOC corrections - §4: Add "Alternative thesis: documentation-first verification" — challenges the two core assumptions behind file splitting (files-as-audit-unit and file-size-as-context-constraint); adds 7-criterion comparison table vs structure-first approach; introduces phased combined recommendation: Phase 1 = doc sprint (//! contracts + specs/ for 3 subsystems, 2-3 PRs, zero structural change); Phase 2 = splits only for >600L production files (reduces scope from 14+ to 4 files); Phase 3 = workspace if LOC > 150K - Fix stale LOC: app/mod.rs 951→979, config/editor.rs 1467→1548 (7 and 8 locations respectively; verified by fresh find|xargs wc -l scan) - §1 module map: add agent_picker.rs (436L), scope_picker.rs (201L), source_picker.rs (244L) — all PR #171 additions with //! docs Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 31 — fix 600L→800L threshold error, correct LOC - §4 alternative thesis: correct ">600L production → 4 files" claim introduced in iteration 30; re-verified all 9 candidate files via #[cfg(test)] line position; threshold must be >800L to get exactly 4 files (9 exceed 600L); add verification table with test-start lines - Production LOC corrections (5+ locations each): launch.rs 1085→~1077, operator_env.rs 810→~880, app/mod.rs 928→~957, config/editor.rs 503→~584 - §2 OpPicker row: replace vague "no entry yet" with confirmed gap: PROJECT_STRUCTURE.md line 53 still lists pre-PR#171 widget set (10 named); omits op_picker/, agent_picker.rs, scope_picker.rs, source_picker.rs and pre-dates the manager/ sub-structure split Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 32 — two-tier spec arch, behavioral spec template - §8.1: Add two-tier spec architecture table distinguishing feature specs (public Starlight MDX, user-facing) from behavioral specs (internal docs/internal/specs/, for AI code verification) — resolves contradiction between §4 (which said docs/internal/specs/) and §8.1 (which said "no longer needed; specs are public") - §8.1: Add concrete behavioral spec template for op_picker/ with state machine table and 3 INV invariant entries each with a grep-executable "Verify by:" command; template directly usable for the 3 Phase 1 specs - §8.1: Remove erroneous "docs/internal/specs/ no longer needed" claim - Confirmed render/editor.rs ~736L and render/list.rs ~668L production (no interspersed production code — all test blocks follow consecutively) Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 33 — executive summary, §0 correctness - §0: Add executive summary (~300 words) with core problem, 3-phase recommendation, key counter-argument, and navigation table pointing to §2/§4/§7/§8/§10 by question — resolves the meta-irony of a readability roadmap with no entry-point orientation - §0 item 2: "1569-line monolith" → "2130-line monolith" (operator_env.rs current verified size; stale reference was in the first section readers see) - §0 item 3: Add "(selective)" qualifier and explicit note that standard Rust co-locates struct+impl — impl-extension pattern is justified only for files >800L production, not as a universal rule Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 34 — spec priority reorder, §10 Phase 1 track - §0 + §4 Phase 1: Prioritize runtime/launch.rs behavioral spec (no //! doc, ~1077L production, critical path — all jackin load failures trace here); drop config/editor.rs from Phase 1 (its 963L test suite already serves as behavioral spec — tests are behavioral examples); reduce Phase 1 from 3 specs to 2 specs; add reasoning for the priority ordering - §10 Step 2: Split into two parallel tracks — Track A (cc-sdd tooling setup) + Track B (Phase 1 behavioral spec authoring); Track B includes specific INV invariants to capture for runtime/launch.rs grounded in reading the actual function structure (step comment positions); adds sequencing rationale: spec must precede structural splits Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 35 — verified INV entries for runtime/launch.rs Read load_agent_with lines 553-892 in full. Replaced 3 draft INVs from iteration 34 (inferred from step comment positions) with 5 verified INVs citing exact line numbers: - INV-1: trust gate (line 594) precedes image build (line 736) - INV-2: container name claimed (line 754) between image build and network - INV-3: token verified (line 763) before network creation (line 827) - INV-4: render_exit called at lines 886 AND 890 (all exit paths) - INV-5: cleanup disarm semantics — Running→disarm, clean exit→cleanup, crash→disarm (explains jackin hardline compatibility) Corrected wrong line number: claim_container_name call is at 754, not 918 (918 is the function definition). Each INV has a grep-executable Verify by. Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 36 — CI gate for PROJECT_STRUCTURE.md freshness §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with three concrete options: - Option A: CONTRIBUTING.md rule (necessary but insufficient) - Option B: ci.yml git-diff-scoped shell check (recommended) — only checks files added in the current PR so it doesn't require fixing existing stale entries before merging; greps for module directory name in prose - Option C: Structured TOML module registry (over-engineered for scale) Includes concrete YAML snippet for Option B grounded in the check:repo-links.ts pattern already established in docs/scripts/ Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iterations 36-37 — CI gate + greenfield workspace architecture Iteration 36: - §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with 3 options (CONTRIBUTING.md rule / ci.yml git-diff check / TOML registry); recommend Option B (git-diff-scoped YAML step) with concrete snippet grounded in existing check:repo-links.ts pattern from docs/scripts/ Iteration 37 (operator directive: greenfield Rust structure): - §4: Add "Greenfield architecture — ideal structure for a growing project" section based on verified cross-module dependency graph (grep iteration 37) - Confirms dependency tiers: workspace/manifest/docker/paths/selector = Tier 0; config/tui/instance = Tier 1; operator_env/runtime/repo = Tier 2; console = Tier 3 - Key finding: workspace/ is LOWER-level than config/ (config re-exports workspace types at lines 5-6); ideal naming inverted in greenfield (jackin-core > jackin-config) - Documents ideal 6-crate workspace: jackin-core, jackin-config, jackin-tui, jackin-runtime, jackin-console, jackin-shell + thin binary - Notes console/ has NO runtime/ import — cleanest pre-existing crate boundary - Bridge: incremental splits (4a, 4d, 4g) are pre-work toward workspace migration Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 38 — Rust workspace standards, community evidence Ground workspace recommendation in real-world project research: - ripgrep (9 crates), gitui (5 crates) went workspace due to library consumers - starship and fd-find stay single-crate at 1M+ LOC — no library use case - jackin (43K LOC, no external consumers) maps to starship/fd pattern → single-crate is community-standard; "stay single-crate" recommendation confirmed Update greenfield workspace structure to follow matklad's pattern: - Virtual manifest at root (no [package] in root Cargo.toml) - Flat crates/ directory (not nested); crate names match folder names - version = "0.0.0" for unpublished internal crates - Add inline dep comments to each crate in the ASCII structure Add research notes: ripgrep/starship/gitui/fd-find Cargo.toml findings + Cargo workspaces reference + matklad "Large Rust Workspaces" (2021-08-22) Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): revise §7.9 + §3 — adopt per-directory README.md §7.9: Reverse previous "reject" recommendation to "adopt" per-directory README.md for major src/ module directories. Rationale: README.md is AI-native — Claude Code, Copilot, Cursor load it automatically on directory entry, giving AI agents orientation before they decide which file to open. PROJECT_STRUCTURE.md being confirmed stale removes the main argument for the "single root file" approach. Add three-layer documentation model table: - README.md: directory orientation (AI + human, on entry) - AGENTS.md: agent workflow rules (root, session start) - CLAUDE.md: @AGENTS.md pointer only — NEVER add content here - //! docs: file-level contracts (when reading/editing) Add specific README.md content targets for 7 directories (src/, src/runtime/, src/console/, src/console/manager/, src/console/widgets/, docs/, docs/internal/). §3 target document shape: Add per-directory README.md to proposed hierarchy; add docs/internal/specs/ explicitly; note CLAUDE.md design principle (single-line @AGENTS.md — never duplicate content). Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): internal docs are browsable — unified Starlight site Operator directive: internal docs (architecture, specs, ADRs, roadmap) should be browsable, not hidden filesystem files. They are a different TYPE of docs focused on implementation details and vision, published as a "Developer Reference" section of the Starlight site. §3 target document shape: - docs/internal/ moves into docs/src/content/docs/internal/ (Starlight pages) - Browsable at jackin.tailrocks.com/internal/ - Sidebar: "Developer Reference" group (collapsed by default) with sub-sections for architecture, code-tour, contributing, testing, decisions, specs, roadmap - Include astro.config.ts sidebar config snippet §8.1 two-tier spec distinction eliminated: - Feature specs and behavioral specs both live at docs/src/content/docs/internal/specs/ - Type expressed via spec_type: behavioral | feature frontmatter, not filesystem location - Both browsable and searchable via Starlight; AI agents can be pointed to URLs §8.3 + §4: - All docs/internal/specs/ paths → docs/src/content/docs/internal/specs/ - ADRs: docs/internal/decisions/ → docs/src/content/docs/internal/decisions/ (browsable) - README.md pointer for src/runtime/ updated to URL reference Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): §11 — modern Rust docs platform (future project) Add §11 capturing the vision for a modern docs.rs alternative with: - rustdoc JSON ingestion → Astro Starlight presentation - MCP server for AI agent queries (Context7 alternative for Rust) - Rust-specific query types: rust_get_context(), rust_find_impls(), rust_search_types() — things Context7 cannot provide - Comparison table vs Context7 - Architecture diagram (ingestion → processing → Starlight + MCP) - Name candidates: rustlight, ferrodoc, cargo-starlight / starlight.rs - Note that jackin's §7.15 gen-rust-api.ts pipeline is the intentional prototype for the platform's processing and presentation layers Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 39 — update §0, fix stale internal/ paths §0 executive summary: rewrite to reflect decisions from iterations 30-38: - browsable internal docs (jackin.tailrocks.com/internal/) - per-directory README.md adoption (§7.9 reversed) - CLAUDE.md = @AGENTS.md single-line pointer only - greenfield workspace architecture (matklad's virtual manifest pattern) - §11 future project: modern Rust docs platform / Context7-for-Rust - document size 1800+ → 2200+ Fix stale docs/internal/ bare paths not caught by iteration 38 sweep: - Mermaid diagram: INTERNAL_ROADMAP, INTERNAL_CODE_TOUR → Starlight paths - §7.10 ADRs: docs/internal/decisions/NNN-title.md → .mdx Starlight path - §10 Track B item 2: op-picker spec path → Starlight MDX Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): iteration 40 — §7.15 pipeline + Rule 4 pub audit §7.15 (new): rustdoc JSON → Astro Starlight API documentation pipeline - Three options: rustdoc HTML publish / rustdoc JSON + bun script (recommended) / rustdoc-json crate as Rust binary - Option B recommended: matches existing docs/scripts/ pattern, nightly isolated to separate CI step, zero effect on stable build - Key design: URL at /internal/api/, cross-links to behavioral specs, Starlight unified search, prototype for §11 future project - Pub(crate) note: gen-rust-api.ts can feed Rule 4 visibility audit - Recommend: adopt after Phase 1 //! sprint (value ∝ coverage) §4 Rule 4 pub discipline: replace estimated "50-100 items" guess with verified numbers from iteration 40 grep: - 257 bare pub items, 21 pub(crate), 61 pub(super) across 94 files - 0 uses of unreachable_pub lint — no enforcement gate - Top violators: operator_env.rs (17), tui/output.rs (13), planner.rs (8) - Add concrete Cargo.toml [lints.rust] snippet: unreachable_pub = "warn" - Revised scope: ~150-200 mechanical conversions (excludes entry points) Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): split research into 19 actionable items Delete _research_notes.md (no longer needed). Replace 2343L READABILITY_AND_MODERNIZATION.md with: - README.md: index of all 19 items with phase, ordering notes, links - READABILITY_AND_MODERNIZATION.md: lightweight research summary (63L) - items/ITEM-001 through ITEM-019: individual actionable items Items by phase: Phase 1 (low risk, no confirmation): ITEM-001..004, 006..011 Phase 1 (needs confirmation): ITEM-005, 016, 018 Phase 2 (structural splits, confirmation required): ITEM-012..015 Phase 3 (deferred): ITEM-017 (rustdoc pipeline), ITEM-019 (workspace) Each item has: summary, key files with line numbers, steps, what needs confirmation, and relevant research backing from the 40-iteration analysis loop. Co-authored-by: Claude <noreply@anthropic.com> * docs(roadmap): migrate 19 items to Starlight reference/roadmap section Move all codebase health roadmap items from docs/internal/roadmap/items/ (plain Markdown, not browsable) to docs/src/content/docs/reference/roadmap/ (MDX pages, browsable at jackin.tailrocks.com/reference/roadmap/). Adds a new "Codebase health" sidebar group (Phase 1 → Phase 3) to astro.config.ts. Deletes the old items/ directory. Updates the internal README to redirect to the new location. Also adds codebase-readability.mdx — a new overview item that captures the overall readability/restructuring program with a recommended execution order: file splits first, then greenfield workspace, then per-directory README+AGENTS.md, then docs and specs. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> * docs(roadmap): remove premature internal/roadmap/README.md The internal/ structure doesn't exist yet — it will be created as part of the roadmap items themselves. No need for a redirect stub now. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> * docs(roadmap): remove READABILITY_AND_MODERNIZATION.md research archive All content has been distilled into the individual Starlight roadmap pages. The full 2343L research is preserved in git history at commit b7e9fc2. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> * docs(roadmap): fix check:repo-links errors + remove iteration log - Replace plain code spans with <RepoFile> for validate.rs, mise.toml, Cargo.toml, and op_picker/mod.rs - Remove deleted READABILITY_AND_MODERNIZATION.md reference from codebase-readability.mdx - Delete _iteration_log.md (git history is the archive) Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> * docs(roadmap): fix lychee false-positive link in move-contributing-testing The example redirect text contained a markdown hyperlink to a proposed future file path that doesn't exist yet. Changed to a code span. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> --------- Signed-off-by: Alexey Zhokhov <alexey@chainargos.com> Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Codex <codex@openai.com>
donbeave
added a commit
that referenced
this pull request
May 7, 2026
Finalizes v1 requirements for per-mount isolation (from #116) after a full decision sweep. Still docs-only — no implementation. User-facing decisions: - Back-merge is upstream only (GitHub PR via existing tooling). No jackin diff / jackin integrate / merge commands. - Dirty host tree warns and requires --force (cold path since operators launch from clean trees). - Hooks inherit from the host repo; no --no-hooks flag in v1. - Branch name hardcoded as jackin/<container>; base = host HEAD. No configurable branch_template or base_branch. - Worktree at <data_dir>/jackin-<container>/isolated/<slug>/. - jackin cd <container> for navigation. Scope trims: - Drop default_isolation. isolation is per-mount only, explicit. - Drop isolation on global mounts entirely (workspace-scoped only). - Drop --delete-branches flag on purge; purge silently deletes everything, including the local scratch branch. Correctness: - Pre-flight validation scoped per isolation type; only checks cases where git would silently do the wrong thing (subdir misrouting, mid-rebase HEAD). - Purge refuses on running agents (fixes a pre-existing gap where remove_data_dir_if_exists ran unconditionally). - Enable extensions.worktreeConfig on first worktree creation per host repo so per-worktree config writes don't leak to shared .git/config. - Mount mode flipped between loads: orphan isolated/ dir left in place, reclaimed by jackin purge. No auto-prune. Known limitations documented: submodules/LFS inherit parent-repo behavior; shared .git/config for remotes/credentials/non-worktree writes (git limitation); -clone-N naming collision to resolve when clone mode ships. Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Claude <noreply@anthropic.com>
donbeave
added a commit
that referenced
this pull request
May 7, 2026
…183) * docs(roadmap): iteration 13 — AI code verifiability framing, config/types.rs full spec Primary goal shift: codebase must be verifiable for AI-generated code. - §0: replace generic description with explicit verifiability rationale (module contracts, localised concerns, types/behaviour separation) - §4 intro: add "Why structure matters for AI-generated code" section with audit-units table mapping each post-split file to one reviewable question - §4 4a: expand config/types.rs from description to full execution spec — exact type list, post-split mod.rs content, zero-change submodule guarantee (verified: agents.rs/persist.rs/workspaces.rs use super::T which resolves through mod.rs re-exports unchanged), impl-extension pattern already in use documented * docs(roadmap): iteration 14 — editor method map, app helpers, //! queue - §4 4c: config/editor.rs split is now execution-ready — complete 6-file method-to-file table with private helper placement verified (validate_candidate→io.rs, table_path_mut→mod.rs pub(super), auth_forward_str→agent_ops.rs, create_workspace delegates to AppConfig) - §4 4e: app/mod.rs split complete — all private helpers mapped (parse_auth_forward_mode_from_cli→config_cmd.rs, workspace_env_scope→workspace_cmd.rs, print_env_table note, remove_data_dir_if_exists→dispatch.rs) - §10 step 5: add //! priority queue — 10 files with draft content, prioritised by cold-landing impact and AI audit risk; selector.rs and instance/mod.rs explicitly document the /→__ invariant * docs(roadmap): iteration 15 — dep graph fix, trust.rs safety, OQ1 closed - §4 4d: correct operator_env dependency graph — layers.rs imports both mod.rs (OpRunner) AND client.rs (OpCli for non-injectable resolve_operator_env wrapper at line 797); still a valid DAG - §4 4f: verify trust.rs split safety — FnOnce injection pattern means launch_pipeline.rs has zero dependency on trust.rs; import chain documented; trust bypass audit now requires reading only ~60L - §9 OQ1 closed: op_cache.rs read in full — 4-level structure, per-level invalidation, no TTL/expiry (expiry handled at OpCli subprocess level), DEFAULT_ACCOUNT_KEY sentinel documented * docs(roadmap): iteration 16 — CommandRunner Rule 3, render/editor split, 4a/4c independence - Fix duplicate Rule 3 section introduced by previous edit; add docker.rs co-location note as third edge case (three edge cases, not two) - Add render/editor.rs as new Rule 5 violator: 1666L post-PR #171 (was listed as 782L); propose 6-file tab-by-tab split with auditability note on the security-adjacent Secrets tab - Add §10 execution-order note: 4a and 4c are independent — editor.rs imports AppConfig via crate::config re-exports regardless of 4a order - Append iteration 16 log entry with confidence table and weakest sections * docs(roadmap): iteration 17 — instance/auth.rs audit, state.rs split, line count corrections - Add instance/auth.rs to //! priority queue at #4: four security invariants (0o600 perms, symlink rejection, TOCTOU-safe writes, macOS Keychain) documented in draft //! content - Add state.rs as new Rule 5 violator: 992L/628L production; 26+ types mixed with impl blocks; propose 5-file types/behavior split - Correct stale line counts: render/list.rs 1122→1989 (PR #171 added render_environments_subpanel); state.rs 865→992; priorities upgraded - Fix §7.9 snapshot function line refs: sentinel_description_pane 306→332, mounts_subpanel 408→433, render_tab_strip 180→269, test ref 720→944 - Renumber //! priority queue to 11 entries (was 10) * docs(roadmap): iteration 18 — agent_allow OQ2 closed, render/list.rs split proposal - Close OQ2: agent_allow.rs read in full — 55L, correct //! doc, design sound; serves as model for //! priority queue pattern - Add render/list.rs as new Rule 5 violator: 668L production (PR #171 added render_environments_subpanel); propose 3-file split (mod.rs, details.rs, subpanels.rs); note import-path change for agents_block_agent_count - Update §1 module map: agent_allow.rs entry corrected with size/API * docs(roadmap): iteration 19 — input/editor.rs critical correction, split proposal - Correct input/editor.rs: 2349L total (was 1304L), 1141L production (was 547L) — PR #171 added Secrets-tab handlers; pub(super) fn handle_editor_modal at line 618 was invisible to previous grep pattern; now the largest production file in the codebase; priority → Critical - Correct input/save.rs: 1472L total, 661L production (was 567L) - Add 5-file split proposal for input/editor.rs: mod.rs (two dispatchers), secrets.rs (~500L AI-generated Secrets-tab), agents.rs, mounts.rs, general.rs - Update key insight paragraph naming input/editor.rs as largest production file * docs(roadmap): iteration 20 — console splits in §10, MSRV evidence, animation.rs verdict - Add console/manager/ as §10 Step 4f group with 5 sub-steps in priority order; rename existing 4f (launch.rs) → 4g; add circular-import risk note for ManagerStage/EditorState split sequencing - Analyze tui/animation.rs: 582L all-production, no split needed (banner_grid is a tightly-coupled rendering loop); section comments compensate for missing //! - Partially close OQ3: u64::is_multiple_of (stabilized 1.86) found in animation.rs; within declared MSRV 1.94; full cargo +1.94.0 check deferred (toolchain unavailable) * docs(roadmap): iteration 21 — input/save.rs split, //! queue fix, save.rs corrections - Add input/save.rs split proposal: 4 pub(super) fns discovered; 3-file split (mod.rs + flow.rs + preview.rs); no cross-dependency between flow and preview groups; §10 4f-v updated from Optional to concrete plan - Fix //! queue preamble: "first 10 files" → "first 11 files" - Correct save.rs module map (1418→1472L, correct key exports) and hot-spot table note (begin_editor_save ~280L → ~118L; commit_editor_save is the Phase 2 partner at ~149L) * docs(roadmap): iteration 22 — input/list.rs and mount_info.rs analysis - Analyze input/list.rs: 214L production (tests at 215); has //! doc; two focused pub(super) fns; no split needed; Low priority; correct module map - Add mount_info.rs to hot-spot table: 277L production; Low priority; has //! doc; correct module map with 3 public enums + inspect fn - Fix stale §2 diagnosis note: docs/internal/roadmap/ now exists * docs(roadmap): iteration 23 — audit units table +5 console rows, input/mod.rs corrected - Expand audit units table from 8 to 13 entries: add state/types.rs, state/editor.rs, input/editor/secrets.rs, render/list/subpanels.rs, input/save/preview.rs — all targeting PR #171 AI-generated console code - Add PR #171 context note linking 5 new entries to AI-generated code concern - Correct input/mod.rs module map: 369L, add InputOutcome enum to exports - Verify rust-toolchain.toml absence; §7.7 and §2 concept 25 already correct * docs(roadmap): iteration 24 — render/mod.rs analysis, //! exemplars table, EditorTab confirmed - Add §4 Rule 7 positive exemplars table: 7 files with //! docs graded 1-element (render/mod.rs), 2-element (input/save.rs etc), 3-element (env_model.rs, agent_allow.rs); PR #171 docs-discipline pattern noted - Correct render/mod.rs module map: 421L; FooterItem + palette constants + render_header + centered_rect_fixed added to key exports - Confirm EditorTab variants: General, Mounts, Agents, Secrets (Rust enum) vs "Secrets / Environments" (UI label); /stub qualifier already removed * docs(roadmap): iteration 25 — too_many_lines recount, FooterItem PR, MountConfig caveat - Correct too_many_lines count: 13 across 8 → 16 across 11 files (PR #171 added 5 suppressions in console/manager); add full breakdown table; update all 3 occurrences in roadmap - Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow) - Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description * docs(roadmap): iteration 26 — console/mod.rs and op_picker/render.rs analyzed - Add console/mod.rs to hot-spot table: 406L/307L production (Low); correct module map from ~200 → 406L; note missing //! doc with ConsoleStage design block comment worth promoting - Add op_picker/render.rs to hot-spot table: 865L/545L production (Medium); PR #171 AI-generated; 14 functions in two logical groups (entry/helpers vs level renderers); split into levels.rs proposed - Correct 3 stale ~200L estimates for console/mod.rs across roadmap * docs(roadmap): iteration 27 — op_picker/mod.rs discovery, render split, operator_env correction - Add op_picker/mod.rs to hot-spot table: 1712L/775L production (High); PR #171 AI-generated; OpPickerState types+behavior split opportunity; has 7-line //! doc; module map split into two rows (mod.rs + render.rs) - Add op_picker/render.rs 2-file split proposal: render.rs (coordinator) + render_pane.rs (pane/level renderers); no cross-dependency confirmed - Correct operator_env.rs total: 1569→2130L (880L production); update 4 occurrences across hot-spot table, ASCII tree, §4 analysis * docs(roadmap): iteration 28 — op_picker/mod.rs 3-file split, count corrections - Add op_picker/mod.rs formal 3-file split: loading.rs (async load family ~120L) + keys.rs (4 level key handlers ~315L) + mod.rs (types/constructors) - Correct "24 files" → "28+" for 500L threshold count - Update total LOC: ~40,664 → ~43,587 (2 occurrences, with provenance note) * docs(roadmap): iteration 29 — op_picker execution order + file_browser analysis - §10 Step 4f: expand from 5 to 7 sub-steps; add 4f-vi (op_picker/mod.rs → mod.rs + loading.rs + keys.rs) and 4f-vii (op_picker/render.rs → render.rs + pane.rs); document impl-extension and import-path caveats - §4 //! exemplars: add file_browser/ subsystem analysis — all 5 files have //! docs, no file exceeds ~350L production; classified as exemplar (not a split candidate); document git_prompt.rs coupling-density justification and input.rs as 28-file false positive (144L production) - §1 module map: expand single file_browser/ row to 5 individual rows with production LOC and dominant concern per file * docs(roadmap): iteration 30 — challenge split-first thesis, fresh LOC corrections - §4: Add "Alternative thesis: documentation-first verification" — challenges the two core assumptions behind file splitting (files-as-audit-unit and file-size-as-context-constraint); adds 7-criterion comparison table vs structure-first approach; introduces phased combined recommendation: Phase 1 = doc sprint (//! contracts + specs/ for 3 subsystems, 2-3 PRs, zero structural change); Phase 2 = splits only for >600L production files (reduces scope from 14+ to 4 files); Phase 3 = workspace if LOC > 150K - Fix stale LOC: app/mod.rs 951→979, config/editor.rs 1467→1548 (7 and 8 locations respectively; verified by fresh find|xargs wc -l scan) - §1 module map: add agent_picker.rs (436L), scope_picker.rs (201L), source_picker.rs (244L) — all PR #171 additions with //! docs * docs(roadmap): iteration 31 — fix 600L→800L threshold error, correct LOC - §4 alternative thesis: correct ">600L production → 4 files" claim introduced in iteration 30; re-verified all 9 candidate files via #[cfg(test)] line position; threshold must be >800L to get exactly 4 files (9 exceed 600L); add verification table with test-start lines - Production LOC corrections (5+ locations each): launch.rs 1085→~1077, operator_env.rs 810→~880, app/mod.rs 928→~957, config/editor.rs 503→~584 - §2 OpPicker row: replace vague "no entry yet" with confirmed gap: PROJECT_STRUCTURE.md line 53 still lists pre-PR#171 widget set (10 named); omits op_picker/, agent_picker.rs, scope_picker.rs, source_picker.rs and pre-dates the manager/ sub-structure split * docs(roadmap): iteration 32 — two-tier spec arch, behavioral spec template - §8.1: Add two-tier spec architecture table distinguishing feature specs (public Starlight MDX, user-facing) from behavioral specs (internal docs/internal/specs/, for AI code verification) — resolves contradiction between §4 (which said docs/internal/specs/) and §8.1 (which said "no longer needed; specs are public") - §8.1: Add concrete behavioral spec template for op_picker/ with state machine table and 3 INV invariant entries each with a grep-executable "Verify by:" command; template directly usable for the 3 Phase 1 specs - §8.1: Remove erroneous "docs/internal/specs/ no longer needed" claim - Confirmed render/editor.rs ~736L and render/list.rs ~668L production (no interspersed production code — all test blocks follow consecutively) * docs(roadmap): iteration 33 — executive summary, §0 correctness - §0: Add executive summary (~300 words) with core problem, 3-phase recommendation, key counter-argument, and navigation table pointing to §2/§4/§7/§8/§10 by question — resolves the meta-irony of a readability roadmap with no entry-point orientation - §0 item 2: "1569-line monolith" → "2130-line monolith" (operator_env.rs current verified size; stale reference was in the first section readers see) - §0 item 3: Add "(selective)" qualifier and explicit note that standard Rust co-locates struct+impl — impl-extension pattern is justified only for files >800L production, not as a universal rule * docs(roadmap): iteration 34 — spec priority reorder, §10 Phase 1 track - §0 + §4 Phase 1: Prioritize runtime/launch.rs behavioral spec (no //! doc, ~1077L production, critical path — all jackin load failures trace here); drop config/editor.rs from Phase 1 (its 963L test suite already serves as behavioral spec — tests are behavioral examples); reduce Phase 1 from 3 specs to 2 specs; add reasoning for the priority ordering - §10 Step 2: Split into two parallel tracks — Track A (cc-sdd tooling setup) + Track B (Phase 1 behavioral spec authoring); Track B includes specific INV invariants to capture for runtime/launch.rs grounded in reading the actual function structure (step comment positions); adds sequencing rationale: spec must precede structural splits * docs(roadmap): iteration 35 — verified INV entries for runtime/launch.rs Read load_agent_with lines 553-892 in full. Replaced 3 draft INVs from iteration 34 (inferred from step comment positions) with 5 verified INVs citing exact line numbers: - INV-1: trust gate (line 594) precedes image build (line 736) - INV-2: container name claimed (line 754) between image build and network - INV-3: token verified (line 763) before network creation (line 827) - INV-4: render_exit called at lines 886 AND 890 (all exit paths) - INV-5: cleanup disarm semantics — Running→disarm, clean exit→cleanup, crash→disarm (explains jackin hardline compatibility) Corrected wrong line number: claim_container_name call is at 754, not 918 (918 is the function definition). Each INV has a grep-executable Verify by. * docs(roadmap): iteration 36 — CI gate for PROJECT_STRUCTURE.md freshness §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with three concrete options: - Option A: CONTRIBUTING.md rule (necessary but insufficient) - Option B: ci.yml git-diff-scoped shell check (recommended) — only checks files added in the current PR so it doesn't require fixing existing stale entries before merging; greps for module directory name in prose - Option C: Structured TOML module registry (over-engineered for scale) Includes concrete YAML snippet for Option B grounded in the check:repo-links.ts pattern already established in docs/scripts/ * docs(roadmap): iterations 36-37 — CI gate + greenfield workspace architecture Iteration 36: - §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with 3 options (CONTRIBUTING.md rule / ci.yml git-diff check / TOML registry); recommend Option B (git-diff-scoped YAML step) with concrete snippet grounded in existing check:repo-links.ts pattern from docs/scripts/ Iteration 37 (operator directive: greenfield Rust structure): - §4: Add "Greenfield architecture — ideal structure for a growing project" section based on verified cross-module dependency graph (grep iteration 37) - Confirms dependency tiers: workspace/manifest/docker/paths/selector = Tier 0; config/tui/instance = Tier 1; operator_env/runtime/repo = Tier 2; console = Tier 3 - Key finding: workspace/ is LOWER-level than config/ (config re-exports workspace types at lines 5-6); ideal naming inverted in greenfield (jackin-core > jackin-config) - Documents ideal 6-crate workspace: jackin-core, jackin-config, jackin-tui, jackin-runtime, jackin-console, jackin-shell + thin binary - Notes console/ has NO runtime/ import — cleanest pre-existing crate boundary - Bridge: incremental splits (4a, 4d, 4g) are pre-work toward workspace migration * docs(roadmap): iteration 38 — Rust workspace standards, community evidence Ground workspace recommendation in real-world project research: - ripgrep (9 crates), gitui (5 crates) went workspace due to library consumers - starship and fd-find stay single-crate at 1M+ LOC — no library use case - jackin (43K LOC, no external consumers) maps to starship/fd pattern → single-crate is community-standard; "stay single-crate" recommendation confirmed Update greenfield workspace structure to follow matklad's pattern: - Virtual manifest at root (no [package] in root Cargo.toml) - Flat crates/ directory (not nested); crate names match folder names - version = "0.0.0" for unpublished internal crates - Add inline dep comments to each crate in the ASCII structure Add research notes: ripgrep/starship/gitui/fd-find Cargo.toml findings + Cargo workspaces reference + matklad "Large Rust Workspaces" (2021-08-22) * docs(roadmap): revise §7.9 + §3 — adopt per-directory README.md §7.9: Reverse previous "reject" recommendation to "adopt" per-directory README.md for major src/ module directories. Rationale: README.md is AI-native — Claude Code, Copilot, Cursor load it automatically on directory entry, giving AI agents orientation before they decide which file to open. PROJECT_STRUCTURE.md being confirmed stale removes the main argument for the "single root file" approach. Add three-layer documentation model table: - README.md: directory orientation (AI + human, on entry) - AGENTS.md: agent workflow rules (root, session start) - CLAUDE.md: @AGENTS.md pointer only — NEVER add content here - //! docs: file-level contracts (when reading/editing) Add specific README.md content targets for 7 directories (src/, src/runtime/, src/console/, src/console/manager/, src/console/widgets/, docs/, docs/internal/). §3 target document shape: Add per-directory README.md to proposed hierarchy; add docs/internal/specs/ explicitly; note CLAUDE.md design principle (single-line @AGENTS.md — never duplicate content). * docs(roadmap): internal docs are browsable — unified Starlight site Operator directive: internal docs (architecture, specs, ADRs, roadmap) should be browsable, not hidden filesystem files. They are a different TYPE of docs focused on implementation details and vision, published as a "Developer Reference" section of the Starlight site. §3 target document shape: - docs/internal/ moves into docs/src/content/docs/internal/ (Starlight pages) - Browsable at jackin.tailrocks.com/internal/ - Sidebar: "Developer Reference" group (collapsed by default) with sub-sections for architecture, code-tour, contributing, testing, decisions, specs, roadmap - Include astro.config.ts sidebar config snippet §8.1 two-tier spec distinction eliminated: - Feature specs and behavioral specs both live at docs/src/content/docs/internal/specs/ - Type expressed via spec_type: behavioral | feature frontmatter, not filesystem location - Both browsable and searchable via Starlight; AI agents can be pointed to URLs §8.3 + §4: - All docs/internal/specs/ paths → docs/src/content/docs/internal/specs/ - ADRs: docs/internal/decisions/ → docs/src/content/docs/internal/decisions/ (browsable) - README.md pointer for src/runtime/ updated to URL reference * docs(roadmap): §11 — modern Rust docs platform (future project) Add §11 capturing the vision for a modern docs.rs alternative with: - rustdoc JSON ingestion → Astro Starlight presentation - MCP server for AI agent queries (Context7 alternative for Rust) - Rust-specific query types: rust_get_context(), rust_find_impls(), rust_search_types() — things Context7 cannot provide - Comparison table vs Context7 - Architecture diagram (ingestion → processing → Starlight + MCP) - Name candidates: rustlight, ferrodoc, cargo-starlight / starlight.rs - Note that jackin's §7.15 gen-rust-api.ts pipeline is the intentional prototype for the platform's processing and presentation layers * docs(roadmap): iteration 39 — update §0, fix stale internal/ paths §0 executive summary: rewrite to reflect decisions from iterations 30-38: - browsable internal docs (jackin.tailrocks.com/internal/) - per-directory README.md adoption (§7.9 reversed) - CLAUDE.md = @AGENTS.md single-line pointer only - greenfield workspace architecture (matklad's virtual manifest pattern) - §11 future project: modern Rust docs platform / Context7-for-Rust - document size 1800+ → 2200+ Fix stale docs/internal/ bare paths not caught by iteration 38 sweep: - Mermaid diagram: INTERNAL_ROADMAP, INTERNAL_CODE_TOUR → Starlight paths - §7.10 ADRs: docs/internal/decisions/NNN-title.md → .mdx Starlight path - §10 Track B item 2: op-picker spec path → Starlight MDX * docs(roadmap): iteration 40 — §7.15 pipeline + Rule 4 pub audit §7.15 (new): rustdoc JSON → Astro Starlight API documentation pipeline - Three options: rustdoc HTML publish / rustdoc JSON + bun script (recommended) / rustdoc-json crate as Rust binary - Option B recommended: matches existing docs/scripts/ pattern, nightly isolated to separate CI step, zero effect on stable build - Key design: URL at /internal/api/, cross-links to behavioral specs, Starlight unified search, prototype for §11 future project - Pub(crate) note: gen-rust-api.ts can feed Rule 4 visibility audit - Recommend: adopt after Phase 1 //! sprint (value ∝ coverage) §4 Rule 4 pub discipline: replace estimated "50-100 items" guess with verified numbers from iteration 40 grep: - 257 bare pub items, 21 pub(crate), 61 pub(super) across 94 files - 0 uses of unreachable_pub lint — no enforcement gate - Top violators: operator_env.rs (17), tui/output.rs (13), planner.rs (8) - Add concrete Cargo.toml [lints.rust] snippet: unreachable_pub = "warn" - Revised scope: ~150-200 mechanical conversions (excludes entry points) * docs(roadmap): split research into 19 actionable items Delete _research_notes.md (no longer needed). Replace 2343L READABILITY_AND_MODERNIZATION.md with: - README.md: index of all 19 items with phase, ordering notes, links - READABILITY_AND_MODERNIZATION.md: lightweight research summary (63L) - items/ITEM-001 through ITEM-019: individual actionable items Items by phase: Phase 1 (low risk, no confirmation): ITEM-001..004, 006..011 Phase 1 (needs confirmation): ITEM-005, 016, 018 Phase 2 (structural splits, confirmation required): ITEM-012..015 Phase 3 (deferred): ITEM-017 (rustdoc pipeline), ITEM-019 (workspace) Each item has: summary, key files with line numbers, steps, what needs confirmation, and relevant research backing from the 40-iteration analysis loop. * docs(roadmap): migrate 19 items to Starlight reference/roadmap section Move all codebase health roadmap items from docs/internal/roadmap/items/ (plain Markdown, not browsable) to docs/src/content/docs/reference/roadmap/ (MDX pages, browsable at jackin.tailrocks.com/reference/roadmap/). Adds a new "Codebase health" sidebar group (Phase 1 → Phase 3) to astro.config.ts. Deletes the old items/ directory. Updates the internal README to redirect to the new location. Also adds codebase-readability.mdx — a new overview item that captures the overall readability/restructuring program with a recommended execution order: file splits first, then greenfield workspace, then per-directory README+AGENTS.md, then docs and specs. * docs(roadmap): remove premature internal/roadmap/README.md The internal/ structure doesn't exist yet — it will be created as part of the roadmap items themselves. No need for a redirect stub now. * docs(roadmap): remove READABILITY_AND_MODERNIZATION.md research archive All content has been distilled into the individual Starlight roadmap pages. The full 2343L research is preserved in git history at commit b7e9fc2. * docs(roadmap): fix check:repo-links errors + remove iteration log - Replace plain code spans with <RepoFile> for validate.rs, mise.toml, Cargo.toml, and op_picker/mod.rs - Remove deleted READABILITY_AND_MODERNIZATION.md reference from codebase-readability.mdx - Delete _iteration_log.md (git history is the archive) * docs(roadmap): fix lychee false-positive link in move-contributing-testing The example redirect text contained a markdown hyperlink to a proposed future file path that doesn't exist yet. Changed to a code span. --------- Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Claude <noreply@anthropic.com>
donbeave
added a commit
that referenced
this pull request
May 7, 2026
Finalizes v1 requirements for per-mount isolation (from #116) after a full decision sweep. Still docs-only — no implementation. User-facing decisions: - Back-merge is upstream only (GitHub PR via existing tooling). No jackin diff / jackin integrate / merge commands. - Dirty host tree warns and requires --force (cold path since operators launch from clean trees). - Hooks inherit from the host repo; no --no-hooks flag in v1. - Branch name hardcoded as jackin/<container>; base = host HEAD. No configurable branch_template or base_branch. - Worktree at <data_dir>/jackin-<container>/isolated/<slug>/. - jackin cd <container> for navigation. Scope trims: - Drop default_isolation. isolation is per-mount only, explicit. - Drop isolation on global mounts entirely (workspace-scoped only). - Drop --delete-branches flag on purge; purge silently deletes everything, including the local scratch branch. Correctness: - Pre-flight validation scoped per isolation type; only checks cases where git would silently do the wrong thing (subdir misrouting, mid-rebase HEAD). - Purge refuses on running agents (fixes a pre-existing gap where remove_data_dir_if_exists ran unconditionally). - Enable extensions.worktreeConfig on first worktree creation per host repo so per-worktree config writes don't leak to shared .git/config. - Mount mode flipped between loads: orphan isolated/ dir left in place, reclaimed by jackin purge. No auto-prune. Known limitations documented: submodules/LFS inherit parent-repo behavior; shared .git/config for remotes/credentials/non-worktree writes (git limitation); -clone-N naming collision to resolve when clone mode ships. Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Claude <noreply@anthropic.com>
donbeave
added a commit
that referenced
this pull request
May 7, 2026
…183) * docs(roadmap): iteration 13 — AI code verifiability framing, config/types.rs full spec Primary goal shift: codebase must be verifiable for AI-generated code. - §0: replace generic description with explicit verifiability rationale (module contracts, localised concerns, types/behaviour separation) - §4 intro: add "Why structure matters for AI-generated code" section with audit-units table mapping each post-split file to one reviewable question - §4 4a: expand config/types.rs from description to full execution spec — exact type list, post-split mod.rs content, zero-change submodule guarantee (verified: agents.rs/persist.rs/workspaces.rs use super::T which resolves through mod.rs re-exports unchanged), impl-extension pattern already in use documented * docs(roadmap): iteration 14 — editor method map, app helpers, //! queue - §4 4c: config/editor.rs split is now execution-ready — complete 6-file method-to-file table with private helper placement verified (validate_candidate→io.rs, table_path_mut→mod.rs pub(super), auth_forward_str→agent_ops.rs, create_workspace delegates to AppConfig) - §4 4e: app/mod.rs split complete — all private helpers mapped (parse_auth_forward_mode_from_cli→config_cmd.rs, workspace_env_scope→workspace_cmd.rs, print_env_table note, remove_data_dir_if_exists→dispatch.rs) - §10 step 5: add //! priority queue — 10 files with draft content, prioritised by cold-landing impact and AI audit risk; selector.rs and instance/mod.rs explicitly document the /→__ invariant * docs(roadmap): iteration 15 — dep graph fix, trust.rs safety, OQ1 closed - §4 4d: correct operator_env dependency graph — layers.rs imports both mod.rs (OpRunner) AND client.rs (OpCli for non-injectable resolve_operator_env wrapper at line 797); still a valid DAG - §4 4f: verify trust.rs split safety — FnOnce injection pattern means launch_pipeline.rs has zero dependency on trust.rs; import chain documented; trust bypass audit now requires reading only ~60L - §9 OQ1 closed: op_cache.rs read in full — 4-level structure, per-level invalidation, no TTL/expiry (expiry handled at OpCli subprocess level), DEFAULT_ACCOUNT_KEY sentinel documented * docs(roadmap): iteration 16 — CommandRunner Rule 3, render/editor split, 4a/4c independence - Fix duplicate Rule 3 section introduced by previous edit; add docker.rs co-location note as third edge case (three edge cases, not two) - Add render/editor.rs as new Rule 5 violator: 1666L post-PR #171 (was listed as 782L); propose 6-file tab-by-tab split with auditability note on the security-adjacent Secrets tab - Add §10 execution-order note: 4a and 4c are independent — editor.rs imports AppConfig via crate::config re-exports regardless of 4a order - Append iteration 16 log entry with confidence table and weakest sections * docs(roadmap): iteration 17 — instance/auth.rs audit, state.rs split, line count corrections - Add instance/auth.rs to //! priority queue at #4: four security invariants (0o600 perms, symlink rejection, TOCTOU-safe writes, macOS Keychain) documented in draft //! content - Add state.rs as new Rule 5 violator: 992L/628L production; 26+ types mixed with impl blocks; propose 5-file types/behavior split - Correct stale line counts: render/list.rs 1122→1989 (PR #171 added render_environments_subpanel); state.rs 865→992; priorities upgraded - Fix §7.9 snapshot function line refs: sentinel_description_pane 306→332, mounts_subpanel 408→433, render_tab_strip 180→269, test ref 720→944 - Renumber //! priority queue to 11 entries (was 10) * docs(roadmap): iteration 18 — agent_allow OQ2 closed, render/list.rs split proposal - Close OQ2: agent_allow.rs read in full — 55L, correct //! doc, design sound; serves as model for //! priority queue pattern - Add render/list.rs as new Rule 5 violator: 668L production (PR #171 added render_environments_subpanel); propose 3-file split (mod.rs, details.rs, subpanels.rs); note import-path change for agents_block_agent_count - Update §1 module map: agent_allow.rs entry corrected with size/API * docs(roadmap): iteration 19 — input/editor.rs critical correction, split proposal - Correct input/editor.rs: 2349L total (was 1304L), 1141L production (was 547L) — PR #171 added Secrets-tab handlers; pub(super) fn handle_editor_modal at line 618 was invisible to previous grep pattern; now the largest production file in the codebase; priority → Critical - Correct input/save.rs: 1472L total, 661L production (was 567L) - Add 5-file split proposal for input/editor.rs: mod.rs (two dispatchers), secrets.rs (~500L AI-generated Secrets-tab), agents.rs, mounts.rs, general.rs - Update key insight paragraph naming input/editor.rs as largest production file * docs(roadmap): iteration 20 — console splits in §10, MSRV evidence, animation.rs verdict - Add console/manager/ as §10 Step 4f group with 5 sub-steps in priority order; rename existing 4f (launch.rs) → 4g; add circular-import risk note for ManagerStage/EditorState split sequencing - Analyze tui/animation.rs: 582L all-production, no split needed (banner_grid is a tightly-coupled rendering loop); section comments compensate for missing //! - Partially close OQ3: u64::is_multiple_of (stabilized 1.86) found in animation.rs; within declared MSRV 1.94; full cargo +1.94.0 check deferred (toolchain unavailable) * docs(roadmap): iteration 21 — input/save.rs split, //! queue fix, save.rs corrections - Add input/save.rs split proposal: 4 pub(super) fns discovered; 3-file split (mod.rs + flow.rs + preview.rs); no cross-dependency between flow and preview groups; §10 4f-v updated from Optional to concrete plan - Fix //! queue preamble: "first 10 files" → "first 11 files" - Correct save.rs module map (1418→1472L, correct key exports) and hot-spot table note (begin_editor_save ~280L → ~118L; commit_editor_save is the Phase 2 partner at ~149L) * docs(roadmap): iteration 22 — input/list.rs and mount_info.rs analysis - Analyze input/list.rs: 214L production (tests at 215); has //! doc; two focused pub(super) fns; no split needed; Low priority; correct module map - Add mount_info.rs to hot-spot table: 277L production; Low priority; has //! doc; correct module map with 3 public enums + inspect fn - Fix stale §2 diagnosis note: docs/internal/roadmap/ now exists * docs(roadmap): iteration 23 — audit units table +5 console rows, input/mod.rs corrected - Expand audit units table from 8 to 13 entries: add state/types.rs, state/editor.rs, input/editor/secrets.rs, render/list/subpanels.rs, input/save/preview.rs — all targeting PR #171 AI-generated console code - Add PR #171 context note linking 5 new entries to AI-generated code concern - Correct input/mod.rs module map: 369L, add InputOutcome enum to exports - Verify rust-toolchain.toml absence; §7.7 and §2 concept 25 already correct * docs(roadmap): iteration 24 — render/mod.rs analysis, //! exemplars table, EditorTab confirmed - Add §4 Rule 7 positive exemplars table: 7 files with //! docs graded 1-element (render/mod.rs), 2-element (input/save.rs etc), 3-element (env_model.rs, agent_allow.rs); PR #171 docs-discipline pattern noted - Correct render/mod.rs module map: 421L; FooterItem + palette constants + render_header + centered_rect_fixed added to key exports - Confirm EditorTab variants: General, Mounts, Agents, Secrets (Rust enum) vs "Secrets / Environments" (UI label); /stub qualifier already removed * docs(roadmap): iteration 25 — too_many_lines recount, FooterItem PR, MountConfig caveat - Correct too_many_lines count: 13 across 8 → 16 across 11 files (PR #171 added 5 suppressions in console/manager); add full breakdown table; update all 3 occurrences in roadmap - Fix FooterItem PR reference: #165 → #166 (confirmed by git log --follow) - Add MountConfig → MountSpec rename caveat to §7.5 snapshot test description * docs(roadmap): iteration 26 — console/mod.rs and op_picker/render.rs analyzed - Add console/mod.rs to hot-spot table: 406L/307L production (Low); correct module map from ~200 → 406L; note missing //! doc with ConsoleStage design block comment worth promoting - Add op_picker/render.rs to hot-spot table: 865L/545L production (Medium); PR #171 AI-generated; 14 functions in two logical groups (entry/helpers vs level renderers); split into levels.rs proposed - Correct 3 stale ~200L estimates for console/mod.rs across roadmap * docs(roadmap): iteration 27 — op_picker/mod.rs discovery, render split, operator_env correction - Add op_picker/mod.rs to hot-spot table: 1712L/775L production (High); PR #171 AI-generated; OpPickerState types+behavior split opportunity; has 7-line //! doc; module map split into two rows (mod.rs + render.rs) - Add op_picker/render.rs 2-file split proposal: render.rs (coordinator) + render_pane.rs (pane/level renderers); no cross-dependency confirmed - Correct operator_env.rs total: 1569→2130L (880L production); update 4 occurrences across hot-spot table, ASCII tree, §4 analysis * docs(roadmap): iteration 28 — op_picker/mod.rs 3-file split, count corrections - Add op_picker/mod.rs formal 3-file split: loading.rs (async load family ~120L) + keys.rs (4 level key handlers ~315L) + mod.rs (types/constructors) - Correct "24 files" → "28+" for 500L threshold count - Update total LOC: ~40,664 → ~43,587 (2 occurrences, with provenance note) * docs(roadmap): iteration 29 — op_picker execution order + file_browser analysis - §10 Step 4f: expand from 5 to 7 sub-steps; add 4f-vi (op_picker/mod.rs → mod.rs + loading.rs + keys.rs) and 4f-vii (op_picker/render.rs → render.rs + pane.rs); document impl-extension and import-path caveats - §4 //! exemplars: add file_browser/ subsystem analysis — all 5 files have //! docs, no file exceeds ~350L production; classified as exemplar (not a split candidate); document git_prompt.rs coupling-density justification and input.rs as 28-file false positive (144L production) - §1 module map: expand single file_browser/ row to 5 individual rows with production LOC and dominant concern per file * docs(roadmap): iteration 30 — challenge split-first thesis, fresh LOC corrections - §4: Add "Alternative thesis: documentation-first verification" — challenges the two core assumptions behind file splitting (files-as-audit-unit and file-size-as-context-constraint); adds 7-criterion comparison table vs structure-first approach; introduces phased combined recommendation: Phase 1 = doc sprint (//! contracts + specs/ for 3 subsystems, 2-3 PRs, zero structural change); Phase 2 = splits only for >600L production files (reduces scope from 14+ to 4 files); Phase 3 = workspace if LOC > 150K - Fix stale LOC: app/mod.rs 951→979, config/editor.rs 1467→1548 (7 and 8 locations respectively; verified by fresh find|xargs wc -l scan) - §1 module map: add agent_picker.rs (436L), scope_picker.rs (201L), source_picker.rs (244L) — all PR #171 additions with //! docs * docs(roadmap): iteration 31 — fix 600L→800L threshold error, correct LOC - §4 alternative thesis: correct ">600L production → 4 files" claim introduced in iteration 30; re-verified all 9 candidate files via #[cfg(test)] line position; threshold must be >800L to get exactly 4 files (9 exceed 600L); add verification table with test-start lines - Production LOC corrections (5+ locations each): launch.rs 1085→~1077, operator_env.rs 810→~880, app/mod.rs 928→~957, config/editor.rs 503→~584 - §2 OpPicker row: replace vague "no entry yet" with confirmed gap: PROJECT_STRUCTURE.md line 53 still lists pre-PR#171 widget set (10 named); omits op_picker/, agent_picker.rs, scope_picker.rs, source_picker.rs and pre-dates the manager/ sub-structure split * docs(roadmap): iteration 32 — two-tier spec arch, behavioral spec template - §8.1: Add two-tier spec architecture table distinguishing feature specs (public Starlight MDX, user-facing) from behavioral specs (internal docs/internal/specs/, for AI code verification) — resolves contradiction between §4 (which said docs/internal/specs/) and §8.1 (which said "no longer needed; specs are public") - §8.1: Add concrete behavioral spec template for op_picker/ with state machine table and 3 INV invariant entries each with a grep-executable "Verify by:" command; template directly usable for the 3 Phase 1 specs - §8.1: Remove erroneous "docs/internal/specs/ no longer needed" claim - Confirmed render/editor.rs ~736L and render/list.rs ~668L production (no interspersed production code — all test blocks follow consecutively) * docs(roadmap): iteration 33 — executive summary, §0 correctness - §0: Add executive summary (~300 words) with core problem, 3-phase recommendation, key counter-argument, and navigation table pointing to §2/§4/§7/§8/§10 by question — resolves the meta-irony of a readability roadmap with no entry-point orientation - §0 item 2: "1569-line monolith" → "2130-line monolith" (operator_env.rs current verified size; stale reference was in the first section readers see) - §0 item 3: Add "(selective)" qualifier and explicit note that standard Rust co-locates struct+impl — impl-extension pattern is justified only for files >800L production, not as a universal rule * docs(roadmap): iteration 34 — spec priority reorder, §10 Phase 1 track - §0 + §4 Phase 1: Prioritize runtime/launch.rs behavioral spec (no //! doc, ~1077L production, critical path — all jackin load failures trace here); drop config/editor.rs from Phase 1 (its 963L test suite already serves as behavioral spec — tests are behavioral examples); reduce Phase 1 from 3 specs to 2 specs; add reasoning for the priority ordering - §10 Step 2: Split into two parallel tracks — Track A (cc-sdd tooling setup) + Track B (Phase 1 behavioral spec authoring); Track B includes specific INV invariants to capture for runtime/launch.rs grounded in reading the actual function structure (step comment positions); adds sequencing rationale: spec must precede structural splits * docs(roadmap): iteration 35 — verified INV entries for runtime/launch.rs Read load_agent_with lines 553-892 in full. Replaced 3 draft INVs from iteration 34 (inferred from step comment positions) with 5 verified INVs citing exact line numbers: - INV-1: trust gate (line 594) precedes image build (line 736) - INV-2: container name claimed (line 754) between image build and network - INV-3: token verified (line 763) before network creation (line 827) - INV-4: render_exit called at lines 886 AND 890 (all exit paths) - INV-5: cleanup disarm semantics — Running→disarm, clean exit→cleanup, crash→disarm (explains jackin hardline compatibility) Corrected wrong line number: claim_container_name call is at 754, not 918 (918 is the function definition). Each INV has a grep-executable Verify by. * docs(roadmap): iteration 36 — CI gate for PROJECT_STRUCTURE.md freshness §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with three concrete options: - Option A: CONTRIBUTING.md rule (necessary but insufficient) - Option B: ci.yml git-diff-scoped shell check (recommended) — only checks files added in the current PR so it doesn't require fixing existing stale entries before merging; greps for module directory name in prose - Option C: Structured TOML module registry (over-engineered for scale) Includes concrete YAML snippet for Option B grounded in the check:repo-links.ts pattern already established in docs/scripts/ * docs(roadmap): iterations 36-37 — CI gate + greenfield workspace architecture Iteration 36: - §3: Add "Preventing future PROJECT_STRUCTURE.md staleness" subsection with 3 options (CONTRIBUTING.md rule / ci.yml git-diff check / TOML registry); recommend Option B (git-diff-scoped YAML step) with concrete snippet grounded in existing check:repo-links.ts pattern from docs/scripts/ Iteration 37 (operator directive: greenfield Rust structure): - §4: Add "Greenfield architecture — ideal structure for a growing project" section based on verified cross-module dependency graph (grep iteration 37) - Confirms dependency tiers: workspace/manifest/docker/paths/selector = Tier 0; config/tui/instance = Tier 1; operator_env/runtime/repo = Tier 2; console = Tier 3 - Key finding: workspace/ is LOWER-level than config/ (config re-exports workspace types at lines 5-6); ideal naming inverted in greenfield (jackin-core > jackin-config) - Documents ideal 6-crate workspace: jackin-core, jackin-config, jackin-tui, jackin-runtime, jackin-console, jackin-shell + thin binary - Notes console/ has NO runtime/ import — cleanest pre-existing crate boundary - Bridge: incremental splits (4a, 4d, 4g) are pre-work toward workspace migration * docs(roadmap): iteration 38 — Rust workspace standards, community evidence Ground workspace recommendation in real-world project research: - ripgrep (9 crates), gitui (5 crates) went workspace due to library consumers - starship and fd-find stay single-crate at 1M+ LOC — no library use case - jackin (43K LOC, no external consumers) maps to starship/fd pattern → single-crate is community-standard; "stay single-crate" recommendation confirmed Update greenfield workspace structure to follow matklad's pattern: - Virtual manifest at root (no [package] in root Cargo.toml) - Flat crates/ directory (not nested); crate names match folder names - version = "0.0.0" for unpublished internal crates - Add inline dep comments to each crate in the ASCII structure Add research notes: ripgrep/starship/gitui/fd-find Cargo.toml findings + Cargo workspaces reference + matklad "Large Rust Workspaces" (2021-08-22) * docs(roadmap): revise §7.9 + §3 — adopt per-directory README.md §7.9: Reverse previous "reject" recommendation to "adopt" per-directory README.md for major src/ module directories. Rationale: README.md is AI-native — Claude Code, Copilot, Cursor load it automatically on directory entry, giving AI agents orientation before they decide which file to open. PROJECT_STRUCTURE.md being confirmed stale removes the main argument for the "single root file" approach. Add three-layer documentation model table: - README.md: directory orientation (AI + human, on entry) - AGENTS.md: agent workflow rules (root, session start) - CLAUDE.md: @AGENTS.md pointer only — NEVER add content here - //! docs: file-level contracts (when reading/editing) Add specific README.md content targets for 7 directories (src/, src/runtime/, src/console/, src/console/manager/, src/console/widgets/, docs/, docs/internal/). §3 target document shape: Add per-directory README.md to proposed hierarchy; add docs/internal/specs/ explicitly; note CLAUDE.md design principle (single-line @AGENTS.md — never duplicate content). * docs(roadmap): internal docs are browsable — unified Starlight site Operator directive: internal docs (architecture, specs, ADRs, roadmap) should be browsable, not hidden filesystem files. They are a different TYPE of docs focused on implementation details and vision, published as a "Developer Reference" section of the Starlight site. §3 target document shape: - docs/internal/ moves into docs/src/content/docs/internal/ (Starlight pages) - Browsable at jackin.tailrocks.com/internal/ - Sidebar: "Developer Reference" group (collapsed by default) with sub-sections for architecture, code-tour, contributing, testing, decisions, specs, roadmap - Include astro.config.ts sidebar config snippet §8.1 two-tier spec distinction eliminated: - Feature specs and behavioral specs both live at docs/src/content/docs/internal/specs/ - Type expressed via spec_type: behavioral | feature frontmatter, not filesystem location - Both browsable and searchable via Starlight; AI agents can be pointed to URLs §8.3 + §4: - All docs/internal/specs/ paths → docs/src/content/docs/internal/specs/ - ADRs: docs/internal/decisions/ → docs/src/content/docs/internal/decisions/ (browsable) - README.md pointer for src/runtime/ updated to URL reference * docs(roadmap): §11 — modern Rust docs platform (future project) Add §11 capturing the vision for a modern docs.rs alternative with: - rustdoc JSON ingestion → Astro Starlight presentation - MCP server for AI agent queries (Context7 alternative for Rust) - Rust-specific query types: rust_get_context(), rust_find_impls(), rust_search_types() — things Context7 cannot provide - Comparison table vs Context7 - Architecture diagram (ingestion → processing → Starlight + MCP) - Name candidates: rustlight, ferrodoc, cargo-starlight / starlight.rs - Note that jackin's §7.15 gen-rust-api.ts pipeline is the intentional prototype for the platform's processing and presentation layers * docs(roadmap): iteration 39 — update §0, fix stale internal/ paths §0 executive summary: rewrite to reflect decisions from iterations 30-38: - browsable internal docs (jackin.tailrocks.com/internal/) - per-directory README.md adoption (§7.9 reversed) - CLAUDE.md = @AGENTS.md single-line pointer only - greenfield workspace architecture (matklad's virtual manifest pattern) - §11 future project: modern Rust docs platform / Context7-for-Rust - document size 1800+ → 2200+ Fix stale docs/internal/ bare paths not caught by iteration 38 sweep: - Mermaid diagram: INTERNAL_ROADMAP, INTERNAL_CODE_TOUR → Starlight paths - §7.10 ADRs: docs/internal/decisions/NNN-title.md → .mdx Starlight path - §10 Track B item 2: op-picker spec path → Starlight MDX * docs(roadmap): iteration 40 — §7.15 pipeline + Rule 4 pub audit §7.15 (new): rustdoc JSON → Astro Starlight API documentation pipeline - Three options: rustdoc HTML publish / rustdoc JSON + bun script (recommended) / rustdoc-json crate as Rust binary - Option B recommended: matches existing docs/scripts/ pattern, nightly isolated to separate CI step, zero effect on stable build - Key design: URL at /internal/api/, cross-links to behavioral specs, Starlight unified search, prototype for §11 future project - Pub(crate) note: gen-rust-api.ts can feed Rule 4 visibility audit - Recommend: adopt after Phase 1 //! sprint (value ∝ coverage) §4 Rule 4 pub discipline: replace estimated "50-100 items" guess with verified numbers from iteration 40 grep: - 257 bare pub items, 21 pub(crate), 61 pub(super) across 94 files - 0 uses of unreachable_pub lint — no enforcement gate - Top violators: operator_env.rs (17), tui/output.rs (13), planner.rs (8) - Add concrete Cargo.toml [lints.rust] snippet: unreachable_pub = "warn" - Revised scope: ~150-200 mechanical conversions (excludes entry points) * docs(roadmap): split research into 19 actionable items Delete _research_notes.md (no longer needed). Replace 2343L READABILITY_AND_MODERNIZATION.md with: - README.md: index of all 19 items with phase, ordering notes, links - READABILITY_AND_MODERNIZATION.md: lightweight research summary (63L) - items/ITEM-001 through ITEM-019: individual actionable items Items by phase: Phase 1 (low risk, no confirmation): ITEM-001..004, 006..011 Phase 1 (needs confirmation): ITEM-005, 016, 018 Phase 2 (structural splits, confirmation required): ITEM-012..015 Phase 3 (deferred): ITEM-017 (rustdoc pipeline), ITEM-019 (workspace) Each item has: summary, key files with line numbers, steps, what needs confirmation, and relevant research backing from the 40-iteration analysis loop. * docs(roadmap): migrate 19 items to Starlight reference/roadmap section Move all codebase health roadmap items from docs/internal/roadmap/items/ (plain Markdown, not browsable) to docs/src/content/docs/reference/roadmap/ (MDX pages, browsable at jackin.tailrocks.com/reference/roadmap/). Adds a new "Codebase health" sidebar group (Phase 1 → Phase 3) to astro.config.ts. Deletes the old items/ directory. Updates the internal README to redirect to the new location. Also adds codebase-readability.mdx — a new overview item that captures the overall readability/restructuring program with a recommended execution order: file splits first, then greenfield workspace, then per-directory README+AGENTS.md, then docs and specs. * docs(roadmap): remove premature internal/roadmap/README.md The internal/ structure doesn't exist yet — it will be created as part of the roadmap items themselves. No need for a redirect stub now. * docs(roadmap): remove READABILITY_AND_MODERNIZATION.md research archive All content has been distilled into the individual Starlight roadmap pages. The full 2343L research is preserved in git history at commit b7e9fc2. * docs(roadmap): fix check:repo-links errors + remove iteration log - Replace plain code spans with <RepoFile> for validate.rs, mise.toml, Cargo.toml, and op_picker/mod.rs - Remove deleted READABILITY_AND_MODERNIZATION.md reference from codebase-readability.mdx - Delete _iteration_log.md (git history is the archive) * docs(roadmap): fix lychee false-positive link in move-contributing-testing The example redirect text contained a markdown hyperlink to a proposed future file path that doesn't exist yet. Changed to a code span. --------- Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Tightens the per-mount isolation roadmap proposal from #116 based on a review pass. No implementation yet — still docs-only.
branch_template), and chore: upgrade crossterm 0.29, ratatui 0.30, and toml 1.1 #4 (submodules/LFS → known limitations)branch_template(workspace-level) andbase_branch(per-mount) from Defer → V1 Scope--force, rather than silently branching fromHEADpast the operator's in-progress workjackin loadsafety (relies on git's internal ref locking; no jackin'-side lock)Scope
docs/src/content/docs/reference/roadmap/per-mount-isolation.mdxonly. +14 / −9.Test plan
bun run buildindocs/— I could not run this in my environment (bun unavailable; npm is forbidden perdocs/AGENTS.md). Changes are plain markdown inside one mdx file, with no new MDX components, no imports, no frontmatter changes, and no bare curly braces outside inline code — breakage risk is very low, but a localbun run buildbefore merge is recommended.Notes
cargo fmt / clippy / nextestskipped perCOMMITS.md("Docs-only commits may skip").worktreemode bullet.base_branchto the tracking branch (e.g.origin/main) — that would give the agent less of the operator's work than the current HEAD default, the opposite of the intended fix. The dirty-tree warn-and---forcepath is the actual UX fix.