jared/cc-os

Watch

Fork 0

Record the OsGit public interface as an ADR #1585

New issue

Closed

opened 2026-11-06 16:50:44 +00:00 by jared · 2 comments

jared commented

2026-11-06 16:50:44 +00:00

Owner

Problem

Many plugins will call the OsGit interface. A change to it breaks all of them, so it is a one-way door. No ADR records it. Two existing records also conflict with the code: ADR-0240 is Accepted but the code ignores it, and a claim that "ADR-0174 puts all git calls in OsSdlc::Git::Repo" has no file behind it.

Design: docs/os-git/use-cases-and-domain.md (design) and docs/os-git/call-site-checklist.md (call sites).

Settled by the user on 2026-11-06. Do not reopen these:

The new gem lives inside plugins/os-git in cc-os now. Plugins load it by a path: source. It moves to ruby-gems later. No remote-gem work now.
git-context (ruby-gems/git-context and cc-plugins/git-context) and os:worktree (plugins/os) merge into os-git.
An old wrapper is removed only after every reference to it is updated and nothing breaks.
The design order is: use-cases first, domain objects second, interfaces third. Write to an interface, not to an implementation.
os-context and os-vault will be Ruby. Their Python git sites are replaced by the Ruby port, not by a Python shim.
Ticket tracking stays out of os-git. It stays in forgejo-api and octokit.

Observed

docs/adr/0174-* does not exist. The claim comes from ticket-takedown oracle text. Treat it as not binding.
ADR-0240 (worktree-before-remove commands) is Accepted. plugins/os/lib/worktree/finish_command.rb has no such step. plugins/os/tests/worktree/finish_command_ignores_before_remove_config_test.rb asserts that the step does not run.
ADR-0240 item 4 gives exit code 6 the meaning "before-remove not found". ADR-0253, the code, and plugins/os/skills/worktree/SKILL.md give exit code 6 the meaning "primary checkout dirty".
ADR-0303 item 4 says a path source is a local override only. The user ruled on 2026-11-06 that a path: source is correct now.

Reproduce

n/a: this is a decision record, nothing runs.

Approach

Required work: none beyond the acceptance criteria.

Orchestrator work: run /os-adr:find on plugins/os, plugins/os-sdlc, ruby-gems/git-context, and plugins/os-git. Propose the decision through /os-adr:create and accept its verdict. Never write the ADR by hand.

The ADR records only the public interface of design sections 4.3 and 6: the namespace OsGit; the objects Repository, Branch, ChangeSet, Span, Worktree, Integration, Commit::Plan, Commit, History, Remote, Sync; and the error rule (raise OsGit::Error when git fails, return nil, [], or false when git answers "nothing there"). It does not record the Backend adapters. The adapter choice is a two-way door.

Inputs to settle in the same ADR step:

Q4, the single commit model: commit --only -- <paths> only (ADR-0171). commit-apply takes path arguments.
Q5, ADR-0240: confirm the feature is dead, then supersede ADR-0240 through /os-adr:create. Keep exit code 6 as "primary checkout dirty". If the feature is alive, port it as a Worktree::Finish step and fix the code.
The ADR-0174 claim: record that no such ADR exists.
ADR-0303 item 4 versus the path: source: record the user's ruling as a habit, not as an ADR change, unless /os-adr:create rules otherwise.

Rejected: write one ADR for the adapters too — the choice between Cli and RubyGit is reversible and no caller sees it.

Acceptance criteria

Given the ADR step is done, when docs/adr/README.md is read, then it lists an Accepted ADR for the OsGit public interface.
Given Q5 is ruled, when the ADR files are read, then either a superseding ADR for ADR-0240 exists, or the ADR for OsGit states that the feature is alive and names the fix.
Given the ADR is Accepted, when design section 8 is read, then the Q4 and Q5 rows record the rulings and the ADR numbers.
Given the ADR is Accepted, when it is read, then it names OsGit as the namespace and lists no adapter class.

Blocking edges

None. The spike (#1586) can run in parallel. Scaffold (#1587) waits for this ticket.

Origin

Trigger: User request in session 1a5b2630-09c9-46cb-aee4-a5a98e2e7d24 on 2026-11-06: one os-git gem for all local git work in cc-os and the user's projects.
Improvised this session: none
Chain: no record of the shared git interface ← git logic grew per plugin ← DESIGN (docs/os-git/use-cases-and-domain.md section 0)
Root candidate: none found; searched open issues for git, worktree, octokit, ruby port, python, statusline, reset --hard. Related but not a match: #845, #853, #857, #1527, #1554.
Where: docs/adr/, docs/os-git/use-cases-and-domain.md
Session: 1a5b2630-09c9-46cb-aee4-a5a98e2e7d24
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/1a5b2630-09c9-46cb-aee4-a5a98e2e7d24.jsonl

## Problem Many plugins will call the `OsGit` interface. A change to it breaks all of them, so it is a one-way door. No ADR records it. Two existing records also conflict with the code: ADR-0240 is Accepted but the code ignores it, and a claim that "ADR-0174 puts all git calls in `OsSdlc::Git::Repo`" has no file behind it. Design: `docs/os-git/use-cases-and-domain.md` (design) and `docs/os-git/call-site-checklist.md` (call sites). Settled by the user on 2026-11-06. Do not reopen these: 1. The new gem lives inside `plugins/os-git` in cc-os now. Plugins load it by a `path:` source. It moves to `ruby-gems` later. No remote-gem work now. 2. `git-context` (`ruby-gems/git-context` and `cc-plugins/git-context`) and `os:worktree` (`plugins/os`) merge into `os-git`. 3. An old wrapper is removed only after every reference to it is updated and nothing breaks. 4. The design order is: use-cases first, domain objects second, interfaces third. Write to an interface, not to an implementation. 5. `os-context` and `os-vault` will be Ruby. Their Python git sites are replaced by the Ruby port, not by a Python shim. 6. Ticket tracking stays out of `os-git`. It stays in `forgejo-api` and `octokit`. ## Observed 1. `docs/adr/0174-*` does not exist. The claim comes from ticket-takedown oracle text. Treat it as not binding. 2. ADR-0240 (`worktree-before-remove` commands) is Accepted. `plugins/os/lib/worktree/finish_command.rb` has no such step. `plugins/os/tests/worktree/finish_command_ignores_before_remove_config_test.rb` asserts that the step does not run. 3. ADR-0240 item 4 gives exit code 6 the meaning "before-remove not found". ADR-0253, the code, and `plugins/os/skills/worktree/SKILL.md` give exit code 6 the meaning "primary checkout dirty". 4. ADR-0303 item 4 says a path source is a local override only. The user ruled on 2026-11-06 that a `path:` source is correct now. ## Reproduce n/a: this is a decision record, nothing runs. ## Approach Required work: none beyond the acceptance criteria. Orchestrator work: run `/os-adr:find` on `plugins/os`, `plugins/os-sdlc`, `ruby-gems/git-context`, and `plugins/os-git`. Propose the decision through `/os-adr:create` and accept its verdict. Never write the ADR by hand. The ADR records only the public interface of design sections 4.3 and 6: the namespace `OsGit`; the objects `Repository`, `Branch`, `ChangeSet`, `Span`, `Worktree`, `Integration`, `Commit::Plan`, `Commit`, `History`, `Remote`, `Sync`; and the error rule (raise `OsGit::Error` when git fails, return `nil`, `[]`, or `false` when git answers "nothing there"). It does not record the `Backend` adapters. The adapter choice is a two-way door. Inputs to settle in the same ADR step: 1. Q4, the single commit model: `commit --only -- <paths>` only (ADR-0171). `commit-apply` takes path arguments. 2. Q5, ADR-0240: confirm the feature is dead, then supersede ADR-0240 through `/os-adr:create`. Keep exit code 6 as "primary checkout dirty". If the feature is alive, port it as a `Worktree::Finish` step and fix the code. 3. The ADR-0174 claim: record that no such ADR exists. 4. ADR-0303 item 4 versus the `path:` source: record the user's ruling as a habit, not as an ADR change, unless `/os-adr:create` rules otherwise. Rejected: write one ADR for the adapters too — the choice between `Cli` and `RubyGit` is reversible and no caller sees it. ## Acceptance criteria 1. Given the ADR step is done, when `docs/adr/README.md` is read, then it lists an Accepted ADR for the `OsGit` public interface. 2. Given Q5 is ruled, when the ADR files are read, then either a superseding ADR for ADR-0240 exists, or the ADR for `OsGit` states that the feature is alive and names the fix. 3. Given the ADR is Accepted, when design section 8 is read, then the Q4 and Q5 rows record the rulings and the ADR numbers. 4. Given the ADR is Accepted, when it is read, then it names `OsGit` as the namespace and lists no adapter class. ## Blocking edges None. The spike (#1586) can run in parallel. Scaffold (#1587) waits for this ticket. ## Origin - Trigger: User request in session 1a5b2630-09c9-46cb-aee4-a5a98e2e7d24 on 2026-11-06: one os-git gem for all local git work in cc-os and the user's projects. - Improvised this session: none - Chain: no record of the shared git interface ← git logic grew per plugin ← DESIGN (docs/os-git/use-cases-and-domain.md section 0) - Root candidate: none found; searched open issues for git, worktree, octokit, ruby port, python, statusline, reset --hard. Related but not a match: #845, #853, #857, #1527, #1554. - Where: docs/adr/, docs/os-git/use-cases-and-domain.md - Session: 1a5b2630-09c9-46cb-aee4-a5a98e2e7d24 - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/1a5b2630-09c9-46cb-aee4-a5a98e2e7d24.jsonl

jared added the

project/cc-os

filed-by/user

category/prose-artifact

labels

2026-11-06 16:50:44 +00:00

jared referenced this issue

2026-11-06 16:51:24 +00:00

Spike: confirm ruby-git v6 coverage and hook load cost #1586

jared referenced this issue

2026-11-06 16:51:24 +00:00

Scaffold the os-git plugin with the OsGit namespace and backends #1587

jared referenced this issue

2026-11-06 16:51:44 +00:00

Move os:worktree and handoff git calls into os-git Worktree and Integration #1589

jared referenced this issue

2026-11-06 16:52:23 +00:00

Merge git-context into os-git and delete the commit_context fork #1591

jared referenced this issue

2026-11-06 16:54:49 +00:00

Build os-git end to end (orchestrator) #1610

jared commented

2026-11-06 17:13:52 +00:00

Author

Owner

Work started by the #1610 orchestrator, session 5b14a4ef-91b2-45c0-a729-baa17682a39a. Branch: ticket-1585.

jared referenced this issue

2026-11-06 17:13:54 +00:00

Build os-git end to end (orchestrator) #1610

jared commented

2026-11-06 17:18:00 +00:00

Author

Owner

Resolution

Done: ADR-0305 records the OsGit public interface. ADR-0306 supersedes ADR-0240. Design section 8 records Q4 and Q5.

Evidence: b430ce73; docs/adr/README.md lists both as Accepted; ADR-0305 names no adapter class. ADR-0240 dead: finish_command.rb has no step, test asserts it does not run, 0 of 27 .cc-os/config files have the key, 6cd75d59 (#842) deleted it on a user ruling. Judge verdict: trim on both.

Follow-ups: commit-apply flag shape (--path versus positional) goes to #1591. ADR-0253 citation of retired ADR-0252 dropped: history text, no effect.

## Resolution **Done:** ADR-0305 records the OsGit public interface. ADR-0306 supersedes ADR-0240. Design section 8 records Q4 and Q5. **Evidence:** b430ce73; docs/adr/README.md lists both as Accepted; ADR-0305 names no adapter class. ADR-0240 dead: finish_command.rb has no step, test asserts it does not run, 0 of 27 .cc-os/config files have the key, 6cd75d59 (#842) deleted it on a user ruling. Judge verdict: trim on both. **Follow-ups:** commit-apply flag shape (--path versus positional) goes to #1591. ADR-0253 citation of retired ADR-0252 dropped: history text, no effect.

jared closed this issue

2026-11-06 17:18:00 +00:00

jared referenced this issue from a commit

2026-11-06 20:25:09 +00:00

docs(adr): record the OsGit public interface and retire ADR-0240 (#1585)

jared referenced this issue from a commit

2026-11-06 20:25:09 +00:00

docs(os-git): mark the design accepted and point it at ADR-0305 and ADR-0306 (#1585)

jared referenced this issue

2026-11-07 07:09:13 +00:00

Build os-git end to end (orchestrator) #1610