jared
/
cc-os
1
0
Fork 0
Code Issues 19 Pull Requests Packages Projects Releases Wiki Activity
cc-os/docs/adr/README.md

54 lines
8.5 KiB
Markdown
Raw Normal View History

Migrate ADR log to docs/adr/, one file per decision The monolithic docs/memory-system/03-architecture-decisions.md had grown to 27 entries and was becoming hard to navigate and diff. Run /os-adr:migrate to split it into docs/adr/ (one file per ADR plus a generated README index and migration report), promoting the cc-os retrofit ahead of pilot projects per the ADR-020 amendment recorded in the monolith. The monolith is retained as the historical source (tagged with migration_source frontmatter) but new decisions now go in docs/adr/. Update CLAUDE.md's layout and conventions sections and docs/implementation-status.md's timeline/rollout notes to point at the new location. Closes out the /os-status:fix run; refs ADR-020.
2026-07-12 22:10:31 +00:00
<!-- Generated by os-adr. Do not hand-edit the table: it is regenerated in full on every ADR write. -->
# Architecture Decision Records
One file per decision, `NNNN-kebab-title.md`, created via `/os-adr:create`.
<!-- adr-index:begin -->
| ID | Title | Status | Date |
| --- | --- | --- | --- |
| 0001 | [Two memory types, kept as separate systems](0001-two-memory-types-kept-as-separate-systems.md) | Accepted | 2026-06-03 |
| 0002 | [memsearch for the episodic layer](0002-memsearch-for-the-episodic-layer.md) | Accepted | 2026-06-03 |
| 0003 | [Flat vault with namespaced tags, not folders](0003-flat-vault-with-namespaced-tags-not-folders.md) | Accepted | 2026-06-03 |
| 0004 | [SQLite + Sequel (Ruby) tag index as the knowledge-layer cache](0004-sqlite-sequel-ruby-tag-index-as-the-knowledge-layer-cache.md) | Superseded | 2026-06-03 |
| 0005 | [Structured-first; semantic search over the vault deferred](0005-structured-first-semantic-search-over-the-vault-deferred.md) | Superseded | 2026-06-03 |
| 0006 | [QMD as the (deferred) semantic-over-knowledge layer](0006-qmd-as-the-deferred-semantic-over-knowledge-layer.md) | Superseded | 2026-06-03 |
| 0007 | [Lazy freshness: write-hook + session-start reconcile, no daemon/cron](0007-lazy-freshness-write-hook-session-start-reconcile-no-daemon-cron.md) | Accepted | 2026-06-03 |
| 0008 | [Markdown-as-truth; sync the vault, not the indexes](0008-markdown-as-truth-sync-the-vault-not-the-indexes.md) | Accepted | 2026-06-03 |
| 0009 | [Package as a global Claude Code plugin with skills](0009-package-as-a-global-claude-code-plugin-with-skills.md) | Accepted | 2026-06-03 |
| 0010 | [Graphify knowledge graph as the knowledge layer (supersedes ADR-004/005/006)](0010-graphify-knowledge-graph-as-the-knowledge-layer-supersedes-adr-004-005-006.md) | Accepted | 2026-06-03 |
| 0011 | [Faceted tag taxonomy: six independent namespaces (refines ADR-003)](0011-faceted-tag-taxonomy-six-independent-namespaces-refines-adr-003.md) | Accepted | 2026-06-04 |
| 0012 | [Reuse the existing SecondBrain vault as the knowledge vault](0012-reuse-the-existing-secondbrain-vault-as-the-knowledge-vault.md) | Accepted | 2026-06-04 |
| 0013 | [Build-first / migrate-incrementally (build-order inversion)](0013-build-first-migrate-incrementally-build-order-inversion.md) | Accepted | 2026-06-04 |
| 0014 | [Graph connectivity comes from authored structure; migration scaffolding is a first-class prerequisite](0014-graph-connectivity-comes-from-authored-structure-migration-scaffolding-is-a-first-class-prerequisite.md) | Accepted | 2026-06-05 |
| 0015 | [memsearch episodic memory version-controlled in a dedicated private repo, auto-synced via cc-os SessionEnd hook](0015-memsearch-episodic-memory-version-controlled-in-a-dedicated-private-repo-auto-synced-via-cc-os-sessionend-hook.md) | Accepted | 2026-06-09 |
| 0016 | [Memory plugin sourced from cc-os git repo; bash→Python deep-module port; memsearch-sync split; symlink cutover](0016-memory-plugin-sourced-from-cc-os-git-repo-bash-python-deep-module-port-memsearch-sync-split-symlink-cutover.md) | Accepted | 2026-06-12 |
| 0017 | [Project graph onboarding assesses the repo and writes `.graphifyignore` before extracting](0017-project-graph-onboarding-assesses-the-repo-and-writes-graphifyignore-before-extracting.md) | Accepted | 2026-06-17 |
| 0018 | [Plugin renames must update the marketplace manifest, not just the directory and settings.json](0018-plugin-renames-must-update-the-marketplace-manifest-not-just-the-directory-and-settings-json.md) | Accepted | 2026-07-03 |
os-context: prompt-composer plugin supersedes os-orchestration; prompt files authored (ADR-031) Rename plugins/os-orchestration -> plugins/os-context. SessionStart hook is now a composer: globs prompts/session-start/*.md in filename order, emits one additionalContext block, byte-identical for the existing orchestration rules (tested), line budgets enforced (warn 120 / refuse 240). ORCHESTRATION.md -> prompts/session-start/10-orchestration.md. New prompt files from the 2026-07-09 audit: 20-kickoff-conventions, 30-standing-safety, 40-decision-memos (total injection 102/120 lines). os-status audit-skill and state-path references updated (old ~/.local/state path symlinked; OS_ORCH_AUDIT_LEDGER name kept for compatibility). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CLeMz48rvG3s9XpAsDxeho
2026-07-13 12:06:48 +00:00
| 0019 | [Global os-orchestration plugin supersedes per-project orchestration text](0019-global-os-orchestration-plugin-supersedes-per-project-orchestration-text.md) | Superseded | 2026-07-03 |
Migrate ADR log to docs/adr/, one file per decision The monolithic docs/memory-system/03-architecture-decisions.md had grown to 27 entries and was becoming hard to navigate and diff. Run /os-adr:migrate to split it into docs/adr/ (one file per ADR plus a generated README index and migration report), promoting the cc-os retrofit ahead of pilot projects per the ADR-020 amendment recorded in the monolith. The monolith is retained as the historical source (tagged with migration_source frontmatter) but new decisions now go in docs/adr/. Update CLAUDE.md's layout and conventions sections and docs/implementation-status.md's timeline/rollout notes to point at the new location. Closes out the /os-status:fix run; refs ADR-020.
2026-07-12 22:10:31 +00:00
| 0020 | [os-adr plugin built; implementation-time resolutions of the design's open questions](0020-os-adr-plugin-built-implementation-time-resolutions-of-the-design-s-open-questions.md) | Accepted | 2026-07-03 |
| 0021 | [Model-tier skill-execution eval for os-adr (Eval A), run in-session via subagents](0021-model-tier-skill-execution-eval-for-os-adr-eval-a-run-in-session-via-subagents.md) | Accepted | 2026-07-03 |
| 0022 | [os-status plugin: aggregated in-process SessionStart status checks](0022-os-status-plugin-aggregated-in-process-sessionstart-status-checks.md) | Accepted | 2026-07-06 |
| 0023 | [Backlog process management ships as a new `os-backlog` plugin (not an os-vault extension)](0023-backlog-process-management-ships-as-a-new-os-backlog-plugin-not-an-os-vault-extension.md) | Accepted | 2026-07-10 |
| 0024 | [Apprise replaces Pushover as the notification transport (supersedes the Pushover-direct plan)](0024-apprise-replaces-pushover-as-the-notification-transport-supersedes-the-pushover-direct-plan.md) | Accepted | 2026-07-10 |
| 0025 | [Standard Ruby structure for cc-os plugins (lib/ + single-dispatcher bin/, fail-soft, installed-gem-only dependencies)](0025-standard-ruby-structure-for-cc-os-plugins-lib-single-dispatcher-bin-fail-soft-installed-gem-only-dependencies.md) | Accepted | 2026-07-10 |
| 0026 | [Unified project setup/update command: `/os-status:fix` remediates what the os-status checks flag](0026-unified-project-setup-update-command-os-status-fix-remediates-what-the-os-status-checks-flag.md) | Accepted | 2026-07-12 |
| 0027 | [All cc-os per-project state lives under `.cc-os/<plugin>/`](0027-all-cc-os-per-project-state-lives-under-cc-os-plugin.md) | Accepted | 2026-07-12 |
os-shortcuts: new plugin + /wrap session-close skill (ADR-028) User-invoked QOL commands plugin; domain boundary vs hook-injection plugins recorded in ADR-028. First resident /os-shortcuts:wrap encodes the session-close ritual (commit per repo conventions, doc sweep, handoff) from the 2026-07-09 workflow audit. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QBAYNm4AmczQaEHfXwai5a
2026-07-12 22:53:07 +00:00
| 0028 | [os-shortcuts plugin for user-invoked QOL commands, bounded against hook-injection plugins](0028-os-shortcuts-plugin-for-user-invoked-qol-commands-bounded-against-hook-injection-plugins.md) | Accepted | 2026-07-12 |
os-backlog: card-move with CLI-enforced column ownership (ADR-029) Adds card-move over planka-api Cards#move; ownership rules enforced in lib (never Next, never hitl, never out of Done, Done only for afk-ready). afk-ready cards now skip Review per user decision; semi still stops at Review. Skills updated to "working a card means moving it". Suite 68 runs/153 assertions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QBAYNm4AmczQaEHfXwai5a
2026-07-12 23:11:49 +00:00
| 0029 | [os-backlog card-move with CLI-enforced column ownership; afk-ready cards skip Review](0029-os-backlog-card-move-with-cli-enforced-column-ownership-afk-ready-cards-skip-review.md) | Accepted | 2026-07-12 |
os-context: prompt-composer plugin supersedes os-orchestration; prompt files authored (ADR-031) Rename plugins/os-orchestration -> plugins/os-context. SessionStart hook is now a composer: globs prompts/session-start/*.md in filename order, emits one additionalContext block, byte-identical for the existing orchestration rules (tested), line budgets enforced (warn 120 / refuse 240). ORCHESTRATION.md -> prompts/session-start/10-orchestration.md. New prompt files from the 2026-07-09 audit: 20-kickoff-conventions, 30-standing-safety, 40-decision-memos (total injection 102/120 lines). os-status audit-skill and state-path references updated (old ~/.local/state path symlinked; OS_ORCH_AUDIT_LEDGER name kept for compatibility). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CLeMz48rvG3s9XpAsDxeho
2026-07-13 12:06:48 +00:00
| 0030 | [Read-only work uses Claude Code plan mode; no /readonly shortcut command](0030-read-only-work-uses-claude-code-plan-mode-no-readonly-shortcut-command.md) | Accepted | 2026-07-13 |
| 0031 | [os-context prompt-composer plugin supersedes single-file os-orchestration](0031-os-context-prompt-composer-plugin-supersedes-single-file-os-orchestration.md) | Accepted | 2026-07-13 |
docs: distill implementation-status.md to index+PD; ADR-0032 records the convention (issue #25 parts 2-3) - implementation-status.md: 729 lines/~9k tokens -> index (~110 lines/~1.8k tokens); per-component detail in docs/implementation-status/ leaf files; operational runbooks preserved in operational-procedures.md; ADR-restated detail removed, not moved - CLAUDE.md record-keeping rule and pointers updated (convention migration, not just reorg) - ADR-0032 (Accepted): AI-maintained knowledge files are indexes with progressive disclosure; the os-doc-hygiene file_length signal enforces it Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CLeMz48rvG3s9XpAsDxeho
2026-07-13 13:18:23 +00:00
| 0032 | [AI-maintained knowledge files are indexes with progressive disclosure](0032-ai-maintained-knowledge-files-are-indexes-with-progressive-disclosure.md) | Accepted | 2026-07-13 |
Retire Planka: os-backlog reworked to git-issues-only (ADR-0042) Executes OpenSpec change retire-planka-git-issues-only (archived, 25/25 tasks): - os-backlog v0.3.0: Planka lib/CLI/agents deleted; issue-create/issues helpers (tea/gh/repo-file dispatch); ten-label taxonomy, human-only next - planka: rejected fail-soft citing ADR-0042 in tracker grammar, config-write, and the os-status check - Skills, SessionStart note (~687 -> ~444 tokens), /to-issues, os-status fix rewritten to the single-tracker model - All boards snapshotted + pg-dumped (ovh-vps ~/planka-final-snapshot-2026-07-16); cards migrated to jared/cc-os#61-70, jared/ops#1-21, jared/llf-schema#7-10 - Planka server decommissioned; planka gem repo archived read-only - Delta specs synced to openspec/specs/ (issue-backlog, issue-state-labels) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014HWNfGWoWnhrub4EJa1M1Y
2026-07-16 19:48:40 +00:00
| 0033 | [Tracker routing: Planka is state, git issues are specs](0033-tracker-routing-planka-is-state-git-issues-are-specs.md) | Superseded | 2026-07-13 |
os-backlog: wakeup-polling + tmux-convention design spike (issue #28, ADR-0035/0036) Poll + tmux direction chosen at the human gate. Thin pilot: Backlog::Wakeup + bin/wakeup-poll (dry-run default; opt-in wakeup=true; afk-ready acts, semi triage-only, else pull-only notify). No cron installed. Suite 128/0. Follow-up: single designated poller machine; cadence deferred to first opt-in. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CLeMz48rvG3s9XpAsDxeho
2026-07-13 15:02:44 +00:00
| 0034 | [Cross-project filing: file-dont-fix with a derived global project index](0034-cross-project-filing-file-dont-fix-with-a-derived-global-project-index.md) | Accepted | 2026-07-13 |
| 0035 | [Issue-triggered project AI wakeup via polling, not webhooks](0035-issue-triggered-project-ai-wakeup-via-polling-not-webhooks.md) | Accepted | 2026-07-13 |
| 0036 | [tmux session convention for AI-run sessions: cc-<project>-<purpose>](0036-tmux-session-convention-for-ai-run-sessions-cc-project-purpose.md) | Accepted | 2026-07-13 |
os-doc-hygiene: lifecycle-aware hygiene design locked — spec + ADR set (map #31, ticket #46) lifecycle-spec.md consolidates wayfinder decisions #32-#48; ADR-0038 (repo-root .dochygiene-rules.json override), ADR-0039 (evidence-quality deletion tiers), ADR-0040 (no ignore-surface propagation), ADR-0041 (determinism promotion + conventions catalog). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Bvc6togVPDXvkoq8fbHj3e
2026-07-14 20:33:26 +00:00
| 0037 | [os-sdlc lives inside cc-os as a new plugin, not a separate cc-sdlc marketplace](0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md) | Accepted | 2026-07-14 |
| 0038 | [Per-project doc-hygiene rulebook override lives at repo-root .dochygiene-rules.json, not in .cc-os/](0038-per-project-doc-hygiene-rulebook-override-lives-at-repo-root-dochygiene-rules-json-not-in-cc-os.md) | Accepted | 2026-07-14 |
| 0039 | [Doc-hygiene deletion autonomy is tiered on evidence quality and recoverability, not file type](0039-doc-hygiene-deletion-autonomy-is-tiered-on-evidence-quality-and-recoverability-not-file-type.md) | Accepted | 2026-07-14 |
| 0040 | [Doc-hygiene rules never write other tools' ignore surfaces (no propagate_ignore)](0040-doc-hygiene-rules-never-write-other-tools-ignore-surfaces-no-propagate-ignore.md) | Accepted | 2026-07-14 |
| 0041 | [Determinism promotion: hygiene nudges projects toward structurally-obvious completion conventions](0041-determinism-promotion-hygiene-nudges-projects-toward-structurally-obvious-completion-conventions.md) | Accepted | 2026-07-14 |
Retire Planka: os-backlog reworked to git-issues-only (ADR-0042) Executes OpenSpec change retire-planka-git-issues-only (archived, 25/25 tasks): - os-backlog v0.3.0: Planka lib/CLI/agents deleted; issue-create/issues helpers (tea/gh/repo-file dispatch); ten-label taxonomy, human-only next - planka: rejected fail-soft citing ADR-0042 in tracker grammar, config-write, and the os-status check - Skills, SessionStart note (~687 -> ~444 tokens), /to-issues, os-status fix rewritten to the single-tracker model - All boards snapshotted + pg-dumped (ovh-vps ~/planka-final-snapshot-2026-07-16); cards migrated to jared/cc-os#61-70, jared/ops#1-21, jared/llf-schema#7-10 - Planka server decommissioned; planka gem repo archived read-only - Delta specs synced to openspec/specs/ (issue-backlog, issue-state-labels) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014HWNfGWoWnhrub4EJa1M1Y
2026-07-16 19:48:40 +00:00
| 0042 | [Retire Planka: git issues are the single tracker for state and specs](0042-retire-planka-git-issues-are-the-single-tracker-for-state-and-specs.md) | Accepted | 2026-07-16 |
os-context: absolute delegation policy (ADR-0043) 10-orchestration.md rewritten from the per-task threshold heuristic to an absolute policy: main loop as executive, enumerated E-a..E-d exemptions, one persistent sonnet manager continued via SendMessage, opus escalation on observed failure only. Audit rubric rewritten to match (exemption decision procedure, exemption-chaining, delegation-overhead-mismatch, accepted-cost severity modifiers, read-write sub-tag). WS4 eval retired as a measurement instrument (contaminated + encodes superseded policy), kept as harness template. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-17 14:19:32 +00:00
| 0043 | [Absolute delegation policy: main loop as executive with enumerated exemptions](0043-absolute-delegation-policy-main-loop-as-executive-with-enumerated-exemptions.md) | Accepted | 2026-07-17 |
Migrate ADR log to docs/adr/, one file per decision The monolithic docs/memory-system/03-architecture-decisions.md had grown to 27 entries and was becoming hard to navigate and diff. Run /os-adr:migrate to split it into docs/adr/ (one file per ADR plus a generated README index and migration report), promoting the cc-os retrofit ahead of pilot projects per the ADR-020 amendment recorded in the monolith. The monolith is retained as the historical source (tagged with migration_source frontmatter) but new decisions now go in docs/adr/. Update CLAUDE.md's layout and conventions sections and docs/implementation-status.md's timeline/rollout notes to point at the new location. Closes out the /os-status:fix run; refs ADR-020.
2026-07-12 22:10:31 +00:00
<!-- adr-index:end -->