jared
/
cc-os
1
0
Fork 0
Code Issues 17 Pull Requests Packages Projects Releases Wiki Activity

os-backlog: global project→backlog index + cross-project issue filing convention #27

New Issue
Closed
opened 2026-07-13 13:44:05 +00:00 by jared · 2 comments
jared commented 2026-07-13 13:44:05 +00:00
Owner
Copy Link

What to build

A cross-project filing capability so that when work in project A surfaces a change that belongs to project B, project A files an issue with B instead of making the change (each project owns its own work; an outside session doesn't know B's evolved rules, conventions, ADRs, and best practices — filing preserves B's ownership). First live example: jared/cc-os#26, filed from the servers repo.

Three parts:

  1. Global project index. A machine-readable registry mapping project → repo path, tracker key (planka:/forgejo:/github:/repo:), and git remote. Preferred approach: derive rather than hand-maintain — /os-backlog:route already writes each project's .cc-os/config tracker key; extend it (and config-write) to also upsert the project's row in one global index file (location TBD in the ADR — e.g. ~/.cc-os/projects). Add an os-backlog projects CLI subcommand to query it (JSON out, fail-soft like the rest of the CLI).

  2. Filing metadata. Cross-project issues must carry a Discoverer block: filing project (repo/path), date, and the Claude Code session id of the discovering session, so the responsible project can audit the originating session for context if the issue is unclear. Define the issue-body template (and how the session id is obtained — hook-provided env, transcript path, or asked of the user if unavailable; fail-soft, never fabricate).

  3. WHEN/HOW instructions. The policy and mechanics need to reach live sessions: extend the os-backlog SessionStart injection note (slice 7) with a CROSS-PROJECT rule — WHEN a needed change belongs to another project THEN query the index, file with that project's tracker using the Discoverer template, and do NOT edit the other project's code — plus a short skill or reference doc with the exact CLI/tea/gh mechanics. Routing within the target project still follows its own boundary rule (specs → git issues; if the target is planka-only, add a card).

Record the convention as an ADR (file-don't-fix policy, index location/format, metadata contract) via /os-adr:create.

Acceptance criteria

  • ADR recording the cross-project filing convention, human-approved
  • Global index exists, is written/updated by route/config-write, queryable via os-backlog projects
  • Discoverer + session-id template defined and referenced from the injection note or a skill
  • Injection note carries the WHEN→THEN cross-project rule (stays within the token budget)
  • Tests for index read/write in the os-backlog suite
  • implementation-status + build records updated per repo convention

Blocked by

None - can start immediately

Discoverer: jared/cc-os session 5b0af6f9-ee11-4f48-b497-f971a7c7c298, 2026-07-13 (motivated by the servers-repo cross-filing of #26).

## What to build A cross-project filing capability so that when work in project A surfaces a change that belongs to project B, project A **files an issue with B instead of making the change** (each project owns its own work; an outside session doesn't know B's evolved rules, conventions, ADRs, and best practices — filing preserves B's ownership). First live example: jared/cc-os#26, filed from the servers repo. Three parts: 1. **Global project index.** A machine-readable registry mapping project → repo path, tracker key (`planka:`/`forgejo:`/`github:`/`repo:`), and git remote. Preferred approach: derive rather than hand-maintain — `/os-backlog:route` already writes each project's `.cc-os/config` tracker key; extend it (and `config-write`) to also upsert the project's row in one global index file (location TBD in the ADR — e.g. `~/.cc-os/projects`). Add an `os-backlog projects` CLI subcommand to query it (JSON out, fail-soft like the rest of the CLI). 2. **Filing metadata.** Cross-project issues must carry a **Discoverer** block: filing project (repo/path), date, and the **Claude Code session id** of the discovering session, so the responsible project can audit the originating session for context if the issue is unclear. Define the issue-body template (and how the session id is obtained — hook-provided env, transcript path, or asked of the user if unavailable; fail-soft, never fabricate). 3. **WHEN/HOW instructions.** The policy and mechanics need to reach live sessions: extend the os-backlog SessionStart injection note (slice 7) with a CROSS-PROJECT rule — WHEN a needed change belongs to another project THEN query the index, file with that project's tracker using the Discoverer template, and do NOT edit the other project's code — plus a short skill or reference doc with the exact CLI/tea/gh mechanics. Routing within the target project still follows its own boundary rule (specs → git issues; if the target is planka-only, add a card). Record the convention as an ADR (file-don't-fix policy, index location/format, metadata contract) via /os-adr:create. ## Acceptance criteria - [ ] ADR recording the cross-project filing convention, human-approved - [ ] Global index exists, is written/updated by route/config-write, queryable via `os-backlog projects` - [ ] Discoverer + session-id template defined and referenced from the injection note or a skill - [ ] Injection note carries the WHEN→THEN cross-project rule (stays within the token budget) - [ ] Tests for index read/write in the os-backlog suite - [ ] implementation-status + build records updated per repo convention ## Blocked by None - can start immediately --- **Discoverer:** jared/cc-os session 5b0af6f9-ee11-4f48-b497-f971a7c7c298, 2026-07-13 (motivated by the servers-repo cross-filing of #26).
jared commented 2026-07-13 14:27:17 +00:00
Author
Owner
Copy Link

Codex review adopted (pre-implementation, 2026-07-13):

  1. Index is JSON at ~/.cc-os/projects.json (matches CLI's JSON-out convention); ADR must distinguish this GLOBAL state file from per-project .cc-os/ state (ADR-0027).
  2. Upsert keyed by canonical repo path (git rev-parse --show-toplevel, fallback File.realpath) — never raw Dir.pwd; name is metadata only (basenames collide).
  3. Session id: primary source is the hook stdin JSON session_id (as os-vault hooks already read); no CLAUDE_SESSION_ID env convention exists in this repo. If unavailable, omit with a note — never fabricate; no fragile transcript parsing.
  4. Injection note: one compact WHEN→THEN line + pointer to a reference doc; mechanics (tea/gh commands, Discoverer template verbatim) live in the reference doc, not the note.
  5. Index writer uses temp-file+rename atomic write (concurrent config-write across projects).
  6. Wire-up: require in lib/backlog.rb, CLI help text updated.
  7. Tests: corrupt/unreadable index, canonical-path keying, name filter, fail-soft JSON.
  8. adr-new defaults to Accepted — pass status Proposed explicitly; flips to Accepted only at the human gate.
**Codex review adopted (pre-implementation, 2026-07-13):** 1. Index is JSON at ~/.cc-os/projects.json (matches CLI's JSON-out convention); ADR must distinguish this GLOBAL state file from per-project .cc-os/ state (ADR-0027). 2. Upsert keyed by canonical repo path (git rev-parse --show-toplevel, fallback File.realpath) — never raw Dir.pwd; name is metadata only (basenames collide). 3. Session id: primary source is the hook stdin JSON session_id (as os-vault hooks already read); no CLAUDE_SESSION_ID env convention exists in this repo. If unavailable, omit with a note — never fabricate; no fragile transcript parsing. 4. Injection note: one compact WHEN→THEN line + pointer to a reference doc; mechanics (tea/gh commands, Discoverer template verbatim) live in the reference doc, not the note. 5. Index writer uses temp-file+rename atomic write (concurrent config-write across projects). 6. Wire-up: require in lib/backlog.rb, CLI help text updated. 7. Tests: corrupt/unreadable index, canonical-path keying, name filter, fail-soft JSON. 8. adr-new defaults to Accepted — pass status Proposed explicitly; flips to Accepted only at the human gate.
jared commented 2026-07-13 14:48:36 +00:00
Author
Owner
Copy Link

Implemented in f9a81a1, ADR-0034 Accepted (human gate 2026-07-13). Global index live at ~/.cc-os/projects.json (cc-os row present from live smoke), 'os-backlog projects' subcommand, Discoverer template + mechanics in skills/route/references/cross-project-filing.md, CROSS-PROJECT rule in the SessionStart note. Suite 112 runs / 0 failures. All acceptance criteria met.

Implemented in f9a81a1, ADR-0034 Accepted (human gate 2026-07-13). Global index live at ~/.cc-os/projects.json (cc-os row present from live smoke), 'os-backlog projects' subcommand, Discoverer template + mechanics in skills/route/references/cross-project-filing.md, CROSS-PROJECT rule in the SessionStart note. Suite 112 runs / 0 failures. All acceptance criteria met.
jared closed this issue 2026-07-13 14:48:36 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
main
research/clutter-inventory
Labels
Clear labels   
P0

Priority 0 — drop everything

  
P1

Priority 1 — next up

  
P2

Priority 2 — normal

  
P3

Priority 3 — someday

  
afk-ready

Autonomous end-to-end; closed after verification

  
hitl

Human-owned; never picked up autonomously

  
next

Human-curated next up — AI never applies or removes

  
ready-for-agent

Triage complete; an agent can pick this up

  
review

Shipped semi work awaiting human sign-off

  
semi

Autonomous through mechanical parts; stops at gates; ships to review

  
waiting

Blocked; blocker named in a comment

  
wayfinder:grilling

   
wayfinder:map

   
wayfinder:research

   
wayfinder:task
No Label
P0
P1
P2
P3
afk-ready
hitl
next
ready-for-agent
review
semi
waiting
wayfinder:grilling
wayfinder:map
wayfinder:research
wayfinder:task
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: jared/cc-os#27
No description provided.
Delete Branch "%!s(<nil>)"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?