ADR: supersede ADR-0218 item 1 — os and os-backlog libraries take collaborators and paths as parameters, only bin/ reads process globals #716

New issue

Closed

opened 2026-09-25 15:03:15 +00:00 by jared · 2 comments

jared commented

2026-09-25 15:03:15 +00:00

Owner

Problem

ADR-0218 item 1 (2026-09-25, commit 8f279513) chose a spawn-env-hash-plus-Thread.current shape for Worktree::CLI.start(env:) and Backlog::CLI.start(env:).
That shape is the one ADR-0213 removed from plugins/os one day earlier (2026-09-24, commit 7714b9ce, "ENV fallbacks removed").
It also contradicts ADR-0207 (only bin/ reads process globals into an Invocation; library collaborators take explicit parameters, no default) and ADR-0174 (Git::Repo is the single class that spawns git, and it takes no env).
plugins/os/lib/worktree/cli.rb:7-8,31-32 sets Thread.current[:worktree_cli_env] and falls back to ENV.
plugins/os/lib/worktree/finish_command.rb:14 defaults env: ENV and threads @env through Open3/system calls to ConflictScan, Removal, RepoRoot, and UsageSweep.
plugins/os-backlog/lib/backlog/cli_env_context.rb:6,21,26 has the matching thread-local for Backlog::CLI, consumed by ProjectsCommand/ConfigWriteCommand only to compute ProjectIndex.default_path(env:).
No superseding ADR exists yet, so this repository currently holds two contradictory accepted decisions about the same shape.

Approach

Create an ADR with /os-adr:create that supersedes ADR-0218 item 1 only (items 2-4 of ADR-0218 stand: no ENV writes, SerializedChdir, parallelize_me!, RepoSeeder).
The new ADR extends ADR-0174's single-git-owner rule and ADR-0207's Invocation pattern to plugins/os and plugins/os-backlog:

Required work:

Record that library code in plugins/os/lib and plugins/os-backlog/lib never reads ENV or Thread.current; only bin/worktree, bin/os-backlog, and bin/wakeup-poll read process globals, and they pass explicit parameters (a git: collaborator, a state_dir:/path: value, or an Invocation) into Thor config.
Record that plugins/os gets its own Worktree::Git collaborator (a copy of os-sdlc's Adapter::Git::Repo shape) because ADR-0025 item 4 forbids source coupling between plugins; note the resulting duplication is tracked by #699.
Record that ADR-0205's spawn-env-hash pattern remains valid only for ProjectShell-style commands supplied by a target project (a different call shape: a caller-provided command, not a library-internal git spawn), so this ADR does not reverse ADR-0205.
List the tickets this ADR unblocks (filed after this ADR, numbers to be added by comment once known).

Non-goals

This ticket is documentation only. It does not implement Worktree::Git, Invocation, or any library change — those are ticket 1 (plugin/os) and ticket 2 (plugin/os-backlog), both blocked by this ADR.

Check

After creating the ADR, confirm it exists and is indexed:

grep -l "0218" docs/adr/*.md
ls docs/adr | grep -i supersed

Origin

Session: 89876543-c418-46b0-b994-dd6dc6887802
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/89876543-c418-46b0-b994-dd6dc6887802.jsonl
Trigger: review of #634/#707/#708 (commits 8ef12ae8, e2817ffe, ADR-0218)
Improvised this session: none
Chain: env:/thread-local in lib ← ADR-0218 item 1 chose spawn-env-hash + Thread.current ← DESIGN (docs/adr/ADR-0218…, contradicts ADR-0213 and ADR-0207)
Root candidate: this ticket (the superseding ADR)

## Problem ADR-0218 item 1 (2026-09-25, commit 8f279513) chose a spawn-env-hash-plus-`Thread.current` shape for `Worktree::CLI.start(env:)` and `Backlog::CLI.start(env:)`. That shape is the one ADR-0213 removed from `plugins/os` one day earlier (2026-09-24, commit 7714b9ce, "ENV fallbacks removed"). It also contradicts ADR-0207 (only `bin/` reads process globals into an `Invocation`; library collaborators take explicit parameters, no default) and ADR-0174 (`Git::Repo` is the single class that spawns git, and it takes no env). `plugins/os/lib/worktree/cli.rb:7-8,31-32` sets `Thread.current[:worktree_cli_env]` and falls back to `ENV`. `plugins/os/lib/worktree/finish_command.rb:14` defaults `env: ENV` and threads `@env` through `Open3`/`system` calls to `ConflictScan`, `Removal`, `RepoRoot`, and `UsageSweep`. `plugins/os-backlog/lib/backlog/cli_env_context.rb:6,21,26` has the matching thread-local for `Backlog::CLI`, consumed by `ProjectsCommand`/`ConfigWriteCommand` only to compute `ProjectIndex.default_path(env:)`. No superseding ADR exists yet, so this repository currently holds two contradictory accepted decisions about the same shape. ## Approach Create an ADR with `/os-adr:create` that supersedes ADR-0218 item 1 only (items 2-4 of ADR-0218 stand: no ENV writes, `SerializedChdir`, `parallelize_me!`, `RepoSeeder`). The new ADR extends ADR-0174's single-git-owner rule and ADR-0207's `Invocation` pattern to `plugins/os` and `plugins/os-backlog`: Required work: 1. Record that library code in `plugins/os/lib` and `plugins/os-backlog/lib` never reads `ENV` or `Thread.current`; only `bin/worktree`, `bin/os-backlog`, and `bin/wakeup-poll` read process globals, and they pass explicit parameters (a `git:` collaborator, a `state_dir:`/`path:` value, or an `Invocation`) into Thor config. 2. Record that `plugins/os` gets its own `Worktree::Git` collaborator (a copy of os-sdlc's `Adapter::Git::Repo` shape) because ADR-0025 item 4 forbids source coupling between plugins; note the resulting duplication is tracked by #699. 3. Record that ADR-0205's spawn-env-hash pattern remains valid only for `ProjectShell`-style commands supplied by a target project (a different call shape: a caller-provided command, not a library-internal git spawn), so this ADR does not reverse ADR-0205. 4. List the tickets this ADR unblocks (filed after this ADR, numbers to be added by comment once known). ## Non-goals This ticket is documentation only. It does not implement `Worktree::Git`, `Invocation`, or any library change — those are ticket 1 (plugin/os) and ticket 2 (plugin/os-backlog), both blocked by this ADR. ## Check After creating the ADR, confirm it exists and is indexed: grep -l "0218" docs/adr/*.md ls docs/adr | grep -i supersed ## Origin Session: 89876543-c418-46b0-b994-dd6dc6887802 Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/89876543-c418-46b0-b994-dd6dc6887802.jsonl Trigger: review of #634/#707/#708 (commits 8ef12ae8, e2817ffe, ADR-0218) Improvised this session: none Chain: env:/thread-local in lib ← ADR-0218 item 1 chose spawn-env-hash + Thread.current ← DESIGN (docs/adr/ADR-0218…, contradicts ADR-0213 and ADR-0207) Root candidate: this ticket (the superseding ADR)

jared added the

project/cc-os

filed-by/user

labels

2026-09-25 15:03:15 +00:00

jared referenced this issue

2026-09-25 15:04:07 +00:00

os: FinishCommand takes git: and after_merge: collaborators; Invocation from bin/worktree; remove env: and thread-local #717

jared referenced this issue

2026-09-25 15:04:08 +00:00

os-backlog: bin/os-backlog resolves CC_OS_HOME once into state_dir; library takes paths as parameters; remove CliEnvContext #718

jared referenced this issue

2026-09-25 15:04:24 +00:00

os: memoize base_branch so finish runs git symbolic-ref once #719

jared commented

2026-09-25 15:04:41 +00:00

Author

Owner

Blocks: #717, #718.

jared commented

2026-09-25 15:05:59 +00:00

Author

Owner

Resolution

Done: ADR-0220 created; ADR-0218 marked Superseded; index regenerated

Evidence: commit b480696f, docs/adr/0220-*.md

Follow-ups: #717 and #718 implement the decision; none other

## Resolution **Done:** ADR-0220 created; ADR-0218 marked Superseded; index regenerated **Evidence:** commit b480696f, docs/adr/0220-*.md **Follow-ups:** #717 and #718 implement the decision; none other

jared closed this issue

2026-09-25 15:05:59 +00:00

jared referenced this issue from a commit

2026-09-26 13:57:00 +00:00

docs(adr): ADR-0220 os and os-backlog libraries take collaborators and paths as parameters; supersedes ADR-0218 item 1 (#716)