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
This commit is contained in:
jared
parent
ef8b7e4a52
commit
15807ef342
30
CLAUDE.md
30
CLAUDE.md
|
|
@ -2,8 +2,9 @@
|
|||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this
|
||||
repository. It is orientation only — implementation history, component details, and
|
||||
operational procedures live in [docs/implementation-status.md](docs/implementation-status.md)
|
||||
(read it on demand, e.g. before touching a plugin or claiming something isn't built yet).
|
||||
operational procedures live in the [docs/implementation-status.md](docs/implementation-status.md)
|
||||
index and its `docs/implementation-status/` leaf files (read on demand, e.g. before touching
|
||||
a plugin or claiming something isn't built yet).
|
||||
|
||||
## What this repository is
|
||||
|
||||
|
|
@ -32,9 +33,10 @@ topic you need.
|
|||
is the architecture, `03-architecture-decisions.md` is the historical ADR log (see
|
||||
`docs/adr/` above), `04-build-plan.md` the build outline with step status,
|
||||
`06-graphify-evaluation.md` justifies the Graphify pivot.
|
||||
- **`docs/implementation-status.md`** — the status timeline, full per-component detail for
|
||||
every shipped plugin (os-vault, os-context, os-status, os-doc-hygiene, os-adr),
|
||||
eval-harness records, and plugin rename/cache-refresh procedures.
|
||||
- **`docs/implementation-status.md`** — the status index: headline timeline + per-component
|
||||
one-liners. Full detail (per-plugin build history, eval-harness records) lives in leaf
|
||||
files under `docs/implementation-status/`, read on demand; plugin rename/cache-refresh
|
||||
runbooks are in `docs/implementation-status/operational-procedures.md`.
|
||||
- **`docs/graphify/`** — verified handbook for the Graphify knowledge-graph tool. Skim
|
||||
`00-README.md` for the model; keep `09-best-practices-checklist.md` open when running it.
|
||||
Claims are provenance-tagged (`[github]` trustworthy; `[interview]` / `[unverified claim]`
|
||||
|
|
@ -69,8 +71,9 @@ is deferred to last (ADR-013).
|
|||
|
||||
## Implemented components (inventory)
|
||||
|
||||
All build-plan steps required for the memory system are complete (2026-06-15). Full detail
|
||||
for each item is in [docs/implementation-status.md](docs/implementation-status.md) — read it
|
||||
All build-plan steps required for the memory system are complete (2026-06-15).
|
||||
[docs/implementation-status.md](docs/implementation-status.md) is the index; full detail per
|
||||
item is in its leaf files under `docs/implementation-status/` — read the relevant leaf
|
||||
before modifying any of these:
|
||||
|
||||
- **os-vault** (`plugins/os-vault/`) — vault write/query/reorganize/onboard-project/
|
||||
|
|
@ -133,10 +136,13 @@ OpenSpec artifacts comes from `docs/` and this file.
|
|||
you make such a choice → record it with `/os-adr:create`. A task that reverses an Accepted
|
||||
ADR is not complete until the superseding ADR exists.
|
||||
- **Keep records current:** when a build step completes, (a) mark it done in
|
||||
`docs/memory-system/04-build-plan.md`, (b) record it in
|
||||
`docs/implementation-status.md` (timeline entry + component pointer), and (c) update the
|
||||
design paragraph in THIS file only if the design itself changed. Never append status
|
||||
history to this file — it goes in implementation-status.md.
|
||||
`docs/memory-system/04-build-plan.md`, (b) record it per the index+progressive-disclosure
|
||||
convention: a **one-line** headline entry in `docs/implementation-status.md` plus the
|
||||
detail in the relevant `docs/implementation-status/<component>.md` leaf file (create one
|
||||
if needed; don't restate what an ADR already records), and (c) update the design paragraph
|
||||
in THIS file only if the design itself changed. Never append status history to this file,
|
||||
and never let the index file regrow into a changelog — the os-doc-hygiene `file_length`
|
||||
signal (400 lines / ~4k tokens) enforces this.
|
||||
- **Plugin and skill naming:** before naming ANY new cc-os plugin, skill, or slash command,
|
||||
Read `~/Documents/SecondBrain/cc-os-plugin-skill-naming-convention.md` and follow it. In
|
||||
brief: plugins are `os-[domain]`; skills are verb-first kebab-case, invoked as
|
||||
|
|
@ -144,4 +150,4 @@ OpenSpec artifacts comes from `docs/` and this file.
|
|||
in SKILL.md frontmatter** (it collapses the slash command to a bare unnamespaced form).
|
||||
- **After editing any plugin source** (SKILL.md, hooks, CLIs), run `bin/refresh-plugins` —
|
||||
source edits don't reach sessions until the cache is refreshed. Rename/move procedure and
|
||||
cache details: docs/implementation-status.md → "Operational procedures".
|
||||
cache details: `docs/implementation-status/operational-procedures.md`.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
id: "0032"
|
||||
date: 2026-07-13
|
||||
status: Accepted
|
||||
supersedes:
|
||||
superseded-by:
|
||||
affected-paths: [docs/implementation-status.md, docs/implementation-status/, plugins/os-doc-hygiene/scripts/scanner.py, CLAUDE.md]
|
||||
affected-components: [docs, os-doc-hygiene]
|
||||
---
|
||||
|
||||
# 0032 — AI-maintained knowledge files are indexes with progressive disclosure
|
||||
|
||||
## Context
|
||||
|
||||
AI-read markdown files grow unbounded when maintained append-only: docs/implementation-status.md reached 729 lines (~9k estimated tokens) and was read routinely at main-loop rates, paying the full context cost on every read even when only one component's status was needed. The os-doc-hygiene scanner gained a deterministic `file_length` signal (2026-07-13, issue #25 part 1; defaults 400 lines / 4000 estimated tokens) that now flags every oversized doc, but a signal without a target structure only reports the problem. The same growth pattern threatens CLAUDE.md and any other file the AI is instructed to keep current.
|
||||
|
||||
## Decision
|
||||
|
||||
AI-maintained knowledge files are **indexes with progressive disclosure**: the main file holds only headline entries and one-liners with pointers; full detail lives in leaf files (e.g. `docs/implementation-status/<component>.md`) read on demand. Detail that merely restates a decision already recorded in `docs/adr/` is removed, not moved — the ADR is the durable record. Operational runbooks referenced from CLAUDE.md land in a stable leaf file (`docs/implementation-status/operational-procedures.md`), never silently dropped. The os-doc-hygiene `file_length` signal (400 lines / ~4k tokens) is the enforcement mechanism: a flagged AI-maintained file is distilled back to index form rather than left to grow. Applied first to docs/implementation-status.md (2026-07-13); applies later to CLAUDE.md cleanup (see the os-context prompt-files card).
|
||||
|
||||
## Consequences
|
||||
|
||||
Easier: routine reads cost one small index instead of the whole history; per-component detail is fetched only when working on that component; the length signal makes drift objective and cheap to catch; ADRs stop being duplicated in prose. Harder: recording a completed step now touches two files (one-line index entry + leaf detail); cross-file links must be kept unbroken (a link-integrity pass belongs to any restructure); readers must follow a pointer for depth instead of scrolling one file.
|
||||
|
||||
## Alternatives rejected
|
||||
|
||||
1) Keep append-only files and rely on the classifier's bloat/distill/split taxonomy downstream — rejected: oversized files were only caught if some other signal fired, and by then the context cost had already been paid for weeks. 2) Periodic manual pruning of the monolith with no structural convention — rejected: pruning decisions are re-litigated every time and history gets lost inconsistently; an index+leaf structure makes the "where does this go" decision mechanical. 3) Move stale sections into leaf files too (archive everything) — rejected: detail already recorded in an ADR is duplication; the ADR system exists to be the durable decision record.
|
||||
|
|
@ -38,4 +38,5 @@ One file per decision, `NNNN-kebab-title.md`, created via `/os-adr:create`.
|
|||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
<!-- adr-index:end -->
|
||||
|
|
|
|||
|
|
@ -1,729 +1,106 @@
|
|||
# cc-os implementation status & changelog
|
||||
# cc-os implementation status — index
|
||||
|
||||
_Last updated: 2026-07-12. This is the append-only implementation-status record moved out of
|
||||
`CLAUDE.md` (2026-07-08, task B1 of
|
||||
[system-prompt-profiles-tasks.md](plans/system-prompt-profiles-tasks.md)). CLAUDE.md keeps
|
||||
orientation only; when a build step completes, record it HERE (plus
|
||||
`docs/memory-system/04-build-plan.md`), and touch CLAUDE.md only if the current design or
|
||||
conventions changed._
|
||||
_Last updated: 2026-07-13. This file is an **index with progressive disclosure** (see the
|
||||
index+PD convention ADR): headline timeline entries and per-component one-liners live here;
|
||||
full per-component detail lives in leaf files under `docs/implementation-status/`, read on
|
||||
demand. When a build step completes, add a **one-line** timeline entry here and put the
|
||||
detail in (or create) the relevant leaf file; decisions go to `docs/adr/` — an ADR is the
|
||||
durable record, so don't duplicate its content here. Touch `CLAUDE.md` only if the current
|
||||
design or conventions changed. (History: moved out of CLAUDE.md 2026-07-08; distilled from
|
||||
the previous 729-line append-only changelog 2026-07-13, issue #25.)_
|
||||
|
||||
## Status timeline
|
||||
## Status timeline (headlines)
|
||||
|
||||
**Recent pivot (2026-06-03):** Graphify **replaces** the originally-planned Ruby/SQLite
|
||||
tag-index CLI and also covers the deferred QMD semantic layer. `04-build-plan.md` and
|
||||
`06-graphify-evaluation.md` reflect this; if an older doc still describes the Ruby CLI, defer
|
||||
to those two and fix the stale doc.
|
||||
Decisions are recorded in `docs/adr/` (see `docs/adr/README.md`); entries below that only
|
||||
restated an ADR were removed in the 2026-07-13 distill. Component-level detail for each
|
||||
entry is in the leaf file named.
|
||||
|
||||
**Decisions locked (2026-06-04):** Six-facet tag taxonomy + `scope/` (ADR-011); reuse
|
||||
`~/Documents/SecondBrain` vault rather than creating a new one (ADR-012); build-first /
|
||||
migrate-incrementally — build full system against a fixture set first, defer bulk vault
|
||||
migration to last, onboard projects one at a time (ADR-013).
|
||||
- **2026-06-03** — Graphify pivot: replaces the planned Ruby/SQLite tag-index CLI and the
|
||||
deferred QMD layer (ADR-0010; rationale: `docs/memory-system/06-graphify-evaluation.md`).
|
||||
- **2026-06-04** — Core design decisions locked: facet taxonomy, vault reuse, build-first
|
||||
order (ADR-0011/0012/0013).
|
||||
- **2026-06-05** — Empirical: Graphify is a structure extractor, not a topic clusterer;
|
||||
hubs/wikilinks must be authored (ADR-0014; findings:
|
||||
`docs/memory-system/07-graph-connectivity-findings.md`).
|
||||
- **2026-06-09** — os-vault plugin live; build-plan Steps 1/2a/2b/3/4/5a/6 complete; single
|
||||
global memsearch store decided (ADR-0015). Detail:
|
||||
[implementation-status/os-vault.md](implementation-status/os-vault.md).
|
||||
- **2026-06-12** — Plugin source moved into cc-os git; bash→Python deep-module port; symlink
|
||||
cutover (ADR-0016).
|
||||
- **2026-06-15** — Step 5b vault git sync automated; llf-schema pilot onboarded; **all
|
||||
required build steps complete**. Detail: os-vault leaf.
|
||||
- **2026-06-17** — Assessment-first project onboarding + `.graphifyignore` (ADR-0017).
|
||||
- **2026-06-30** — SB Content Plan Phase 1 complete (schema reconciliation, templates,
|
||||
design-template skill). Detail: os-vault leaf; Phase 2 (issue #7) open as steady-state
|
||||
epic.
|
||||
- **2026-07-03** — Plugin renamed `memory` → `os-vault`; marketplace-manifest failure mode
|
||||
found (ADR-0018, runbook in
|
||||
[implementation-status/operational-procedures.md](implementation-status/operational-procedures.md)).
|
||||
os-doc-hygiene and os-orchestration migrated in from cc-plugins (ADR-0019); os-adr plugin
|
||||
built + migration pilot passed + Eval A/B baselines (ADR-0020/0021). Detail: os-adr /
|
||||
os-doc-hygiene / os-context leaves.
|
||||
- **2026-07-04** — Stale-plugin-cache incident resolved; `bin/refresh-plugins` created
|
||||
(runbook: operational-procedures leaf). os-adr Eval B wording loop closed the gap (sonnet
|
||||
8/8, haiku 7/8). Detail: os-adr leaf.
|
||||
- **2026-07-06** — os-status plugin built (ADR-0022); os-vault WS2 + os-orchestration
|
||||
WS1/E1–E3 eval harnesses + baseline grids; os-adr Eval C harness + saturated frozen grid.
|
||||
Detail: os-status / os-vault / os-context / os-adr leaves.
|
||||
- **2026-07-07/08** — os-vault WS2 wording loop and os-orchestration WS4 economics loop
|
||||
complete and shipped; run-sets AND reserves now contaminated for future wording tuning —
|
||||
next signal is production IRL audits. Detail: os-vault / os-context leaves.
|
||||
- **2026-07-10** — Multi-machine freshness closed (SessionStart ff-only pull); os-backlog
|
||||
AFK slices shipped + live-verified, planka-api 0.2.0 migration (ADR-0023/0025); first
|
||||
orchestration IRL re-audit done + biweekly audit semi-automated. Detail: os-vault /
|
||||
os-backlog / os-context leaves.
|
||||
- **2026-07-12** — `/os-status:fix` unified setup/update command (ADR-0026) +
|
||||
`/os-backlog:route`; fix tune-up + `.cc-os/` state consolidation (ADR-0027); cc-os ADR
|
||||
retrofit — 27-ADR monolith migrated to `docs/adr/` (ADR-0020 amendment); os-shortcuts
|
||||
plugin + `/wrap` (ADR-0028); os-backlog card-move + afk-ready-skips-Review (ADR-0029).
|
||||
Detail: os-status / os-backlog / os-adr leaves.
|
||||
- **2026-07-13** — os-orchestration renamed/generalized to os-context prompt composer
|
||||
(ADR-0031) + three new prompt files; `/readonly` decided as plan-mode convention, no
|
||||
skill (ADR-0030); os-doc-hygiene `file_length` scanner signal shipped (issue #25 part 1);
|
||||
this file distilled to index+PD (issue #25 parts 2–3, ADR-0032). os-backlog slice 7
|
||||
shipped: SessionStart injection note + /to-issues tracker routing (issue #16); board-id
|
||||
cache via BoardResolver (issue #22). Detail: os-context / os-doc-hygiene / os-backlog
|
||||
leaves.
|
||||
|
||||
**Empirical finding locked (2026-06-05):** Graphify is a structure extractor, not a topic
|
||||
clusterer — no emergent hub nodes appear even at `--mode deep`; hub notes + wikilinks must be
|
||||
author-provided during migration (not deferred). Migration scaffolding is now a first-class
|
||||
deliverable. Open question: do facet tags create graph edges? (ADR-014; findings:
|
||||
`docs/memory-system/07-graph-connectivity-findings.md`).
|
||||
**Remaining optional items:** additional project onboarding (one at a time, per ADR-0013);
|
||||
bulk vault migration; os-adr rollout to pilot projects; os-backlog slice #17 and routing
|
||||
rollout.
|
||||
|
||||
**Implementation status (2026-06-09):** The global Claude Code plugin is live
|
||||
(`~/.claude/plugins/os-vault/`). Steps 1, 2a, 2b, 3, and 6 of the build plan are complete
|
||||
(including the `onboard-project` skill, previously TODO under Step 6/Part D). Step 1
|
||||
completed 2026-06-09: vault-conventions.md exists, all 6 fixture notes seeded, and 14
|
||||
Graphify handbook + memory-system design notes migrated to the vault as migration
|
||||
scaffolding. Step 4 (memsearch) completed 2026-06-09: plugin installed via marketplace,
|
||||
MEMSEARCH_DIR set global (~/.memsearch), Stop hook verified producing daily memory files,
|
||||
search confirmed working. Step 5a (memsearch episodic git sync) completed 2026-06-09:
|
||||
dedicated private Forgejo repo (`forgejo.swansoncloud.com/jared/memsearch`), whitelist
|
||||
`.gitignore` (memory/*.md only), auto-commit+push via cc-os `session-end.sh` hook (ADR-015;
|
||||
relocated to `memsearch_sync.py` by ADR-016, 2026-06-12). Step 5b (Obsidian vault → VPS
|
||||
sync) remained at that date.
|
||||
## Implemented components (one-liners)
|
||||
|
||||
**Decision (2026-06-09):** Single global memsearch store for ALL clients — cross-client
|
||||
commingling is the accepted, intended design (ADR-015 resolved). One private Forgejo repo
|
||||
(`forgejo.swansoncloud.com/jared/memsearch`), not per-client repos. Forward direction:
|
||||
minimize/eliminate dedicated per-client working directories; work projects locally or use a
|
||||
single general `clients/` dir for non-local client work — memory is captured globally
|
||||
regardless of cwd. No `clients/` directory structure designed yet; open item.
|
||||
Read the leaf file before modifying a component.
|
||||
|
||||
**Implementation status (2026-06-12):** os-vault plugin source moved into git at
|
||||
`cc-os/plugins/os-vault/` and bash hooks ported to Python (deep-module architecture: shared
|
||||
`config.py`, `hook_io.py`, `session_state.py`; thin entry-point scripts). Cutover via symlink
|
||||
`~/.claude/plugins/os-vault → cc-os/plugins/os-vault/` and settings.json hook rewrite.
|
||||
memsearch sync split into dedicated `memsearch_sync.py` SessionEnd hook (relocation of
|
||||
ADR-015 behavior, not reversal). Fresh-session test passed 2026-06-12. See ADR-016.
|
||||
|
||||
**Implementation status (2026-06-15):** Step 5b done and automated — vault
|
||||
(`~/Documents/SecondBrain`) initialized as git repo, pushed to private Forgejo
|
||||
(`ssh://git@forgejo.swansoncloud.com:2222/jared/SecondBrain.git`); 52 files, git chosen over
|
||||
Syncthing. Auto-commit+push wired via `vault_sync.py` SessionEnd hook (third SessionEnd
|
||||
hook, runs after `session_end.py` so the daily journal note is included; push-only —
|
||||
SessionStart pull is an optional future item for multi-machine). Step 2e pilot done —
|
||||
llf-schema (`/home/jared/dev/llf-schema`, PHP 8.2 WordPress plugin) onboarded via
|
||||
`/os-vault:onboard-project` skill: 605 nodes / 930 edges / 52 communities; Ollama doc pass
|
||||
lossy on WordPress docs but AST pass solid. Step 2d closed — live vault `graphify-out/` is
|
||||
the baseline; fixture-only build superseded.
|
||||
|
||||
**Implementation status (2026-06-17):** `/os-vault:onboard-project` skill now uses
|
||||
assessment-first onboarding: surveys the repo structure, classifies exclude candidates by
|
||||
TYPE (11 categories: fetched deps, build output, caches, VCS internals, editor/AI-tooling
|
||||
dirs, lockfiles, coverage/logs, bulk data, binaries, secrets, graphify-out/ — illustrative
|
||||
names, not fixed templates), generates a per-project `.graphifyignore`, confirms with the
|
||||
user, then extracts the graph using `qwen25-coder-7b-16k` (config.yaml `ollama_model`;
|
||||
16k-context build of qwen2.5-coder:7b — larger context window cuts chunk count per doc, the
|
||||
main speed lever). Fixes issue where repos with large dependency trees routed non-code files
|
||||
through the Ollama doc pass (see ADR-017).
|
||||
|
||||
**Implementation status (2026-06-30):** Phase 1 of the SecondBrain Content Plan complete
|
||||
(`docs/memory-system/09-sb-content-plan.md`, issues #1–#6).
|
||||
`~/Documents/SecondBrain/vault-conventions.md` reconciled to a single authoritative typed
|
||||
frontmatter schema (removed the contradictory block; canonical filenames are slug-only,
|
||||
`source:` is a frontmatter field not a tag, `scope` is a field not a tag). New
|
||||
`/os-vault:design-template` skill added
|
||||
(`cc-os/plugins/os-vault/skills/design-template/SKILL.md`) — routes between template-design
|
||||
(4-step process + injection-economics filter) and new-type creation (9-step lifecycle).
|
||||
Three vault note templates created in `~/Documents/SecondBrain/_templates/` (`howto.md`,
|
||||
`convention.md`, `reference.md`; `reference` carries a four-subtype variant selector —
|
||||
pattern/framework, api-integration, role-definitions, design-rules), each dogfooded against
|
||||
a real note. Four proof-of-concept vault notes patched (cookbook subtype →
|
||||
pattern/framework, glossary de-duped to a wikilink, design-mode scope → project, tags +
|
||||
`last_reviewed` added). Phase 2 (issue #7) remains open as the steady-state
|
||||
migration/onboarding epic (no code). See `docs/memory-system/09-sb-content-plan.md`.
|
||||
|
||||
**Plugin renamed `memory` → `os-vault` (2026-07-03):** directory renamed in git,
|
||||
`~/.claude/plugins/os-vault` symlink and `settings.json`'s `enabledPlugins` updated — but
|
||||
the `local-plugins` marketplace manifest
|
||||
(`~/.claude/plugins/.claude-plugin/marketplace.json`) still declared the old
|
||||
`memory`/`./memory` entry, and `installed_plugins.json` still had a cached
|
||||
`memory@local-plugins` install record. Skills (and therefore slash commands) never
|
||||
registered under the new name as a result; hooks kept working because they're wired by
|
||||
absolute path in `settings.json`, independent of plugin resolution. Fixed by editing the
|
||||
marketplace manifest to `"os-vault"`/`"./os-vault"`, then
|
||||
`claude plugin marketplace update local-plugins`,
|
||||
`claude plugin install os-vault@local-plugins`,
|
||||
`claude plugin uninstall memory@local-plugins`. See ADR-018 and the "Renaming or moving a
|
||||
local plugin" procedure below.
|
||||
|
||||
**Resolved (2026-07-04):** os-adr's skills failed to register on first install due to stale
|
||||
plugin caches — the cache that was installed on 2026-07-03 17:21:48 was missing
|
||||
`hooks/hooks.json`, `bin/adr-detect`, `bin/adr-find`, `bin/adr-migrate`. Root cause:
|
||||
unknown, but the caches were restored via plugin uninstall/reinstall. A parallel issue
|
||||
affected os-doc-hygiene (cache retained deleted `commands/` directory). Fixed by manually
|
||||
refreshing both caches, then created `bin/refresh-plugins` automation to prevent future
|
||||
drift — see "Editing a local plugin (cache refresh)" below. Investigation result: stale
|
||||
caches (not manifest-naming issues) were the cause; slash command registration works
|
||||
correctly once caches are fresh.
|
||||
|
||||
**Multi-machine freshness closed (2026-07-10):** `session_start.py` gained a fast-forward-only
|
||||
`git pull` (`timeout 10 git pull --ff-only --quiet`) for both `cfg.vault_path` and
|
||||
`cfg.memsearch_dir`, run before the staleness check — silent on success, quiet one-line stderr
|
||||
note on failure (offline machine), never blocking session start. Closes the push-only gap noted
|
||||
below; mirrors the push style of `vault_sync.py`/`memsearch_sync.py` in the opposite direction.
|
||||
|
||||
**os-backlog AFK slices shipped (2026-07-10):** PRD published as Forgejo issue #9 (state
|
||||
pointer: Planka card `1816234194716592051`); sliced into issues #10–#17 via `/to-issues`.
|
||||
The five AFK slices are implemented and committed: #10 plugin scaffold + `board-ensure`
|
||||
(uniform lists/labels incl. new `semi` autonomy label, Planka 2.1.1 quirks, `archived--`
|
||||
rename convention), #11 `tracker` key in `.cc-os/config` + os-status `tracker-configured`
|
||||
check, #12 pure routing resolver CLI, #13 `/os-backlog:capture` + `/os-backlog:list`
|
||||
skills + card CLI, #15 `card-triage` + `board-audit` named agents. All deterministic parts
|
||||
covered by stubbed-client tests (34 runs os-backlog, 49 os-status). Semi slices #14
|
||||
(routing/migration skill), #16 (injection note + /to-issues routing), #17 (ops board +
|
||||
rubric category + routing ADR) await human decision gates. 2026-07-10 (later): planka-api
|
||||
gem 0.1.0 installed locally (`rake install`, rbenv 4.0.2; publish/versioning still parked
|
||||
behind gem issue 13) and live verification completed against production Planka —
|
||||
`snapshot`, `board-ensure` (created the missing `semi` label on the cc-os board), and
|
||||
`card-add` + `card-label` all succeeded with bot credentials sourced from ovh-vps
|
||||
(`~/services/planka/bot-credentials.env`) in a subshell. Follow-up captured as a `hitl`
|
||||
Backlog card: get planka_bot into credvault (credvault has no import path — rotate vs.
|
||||
add import capability is a human decision).
|
||||
|
||||
**os-backlog migrated to planka-api 0.2.0 typed returns (2026-07-10):** commit `8df0cb7`
|
||||
moved the gem from 0.1.0 hash-return to 0.2.0, which returns `Planka::Types` value objects
|
||||
instead of parsed-JSON hashes. `board_ensurer.rb` and `cards.rb` were rewritten on typed
|
||||
accessors (`card.id`, `card.list_id`, …); `Cards#snapshot` now builds explicit string-keyed
|
||||
hashes from `BoardDetail#lists`/`#cards`/`#labels`/`#card_labels` (`BoardDetail` replaces the
|
||||
old `included`-hash shape). Test fakes in `tests/test_helper.rb` were rebuilt to return real
|
||||
`Planka::Types` records instead of hashes. JSON output stays byte-compatible, so skill/agent
|
||||
contracts are unchanged. A follow-up fix (issue #18, same day) found the migration had
|
||||
silently dropped one field from `Cards#snapshot`'s per-card hash; restored the full 19-key
|
||||
camelCase card key set (`id`, `createdAt`, `updatedAt`, `type`, `position`, `name`,
|
||||
`description`, `dueDate`, `isDueCompleted`, `stopwatch`, `commentsTotal`, `isClosed`,
|
||||
`listChangedAt`, `boardId`, `listId`, `creatorUserId`, `prevListId`, `coverAttachmentId`,
|
||||
`isSubscribed`, plus `labels`) with a regression test pinning the key set including
|
||||
`listChangedAt`. Suite green at 35 runs (was 34 pre-#18).
|
||||
|
||||
**os-backlog live verification (0.2.0) (2026-07-10):** end-to-end re-verification of
|
||||
`bin/os-backlog` against the real Planka instance with the installed 0.2.0 gem (issue #20).
|
||||
Local machine had no `PLANKA_*` env/credvault entry, so the plugin tree was rsynced to
|
||||
`ovh-vps:/tmp/os-backlog-verify` (where `planka-api` 0.2.0 is also installed) and exercised
|
||||
there with bot credentials sourced from `~/services/planka/bot-credentials.env` in a
|
||||
subshell, per the established pattern — credential contents were never read or printed.
|
||||
Results: `tests/all.rb` 35 runs/0 failures on ovh-vps; `board-ensure cc-os --project Dev` run
|
||||
twice both reported `(existing)` with no lists/labels created (idempotent); `card-add`
|
||||
created a card on Backlog; `card-label` attached `afk-ready`; `card-comment` posted a
|
||||
comment; `snapshot --board cc-os` showed the card with the full 20-key set (19 card fields +
|
||||
`labels`) including `"listChangedAt": "2026-07-10T21:04:37.013Z"` and `"labels":
|
||||
["afk-ready"]`. The test card was deleted via `Planka::Client#cards.delete` (the CLI has no
|
||||
delete subcommand) and a follow-up snapshot confirmed it was gone; the rsynced verification
|
||||
tree on ovh-vps was removed afterward. No regressions vs. the pre-0.2.0 behavior.
|
||||
|
||||
**Unified setup/update command + tracker routing skill shipped (2026-07-12):** ADR-026
|
||||
decided the unified per-project setup/update command lives in os-status as `/os-status:fix`
|
||||
(rejected: new `os-project` plugin, literal `/cc-os:init`). Built in parallel (issues #21,
|
||||
#14, both sonnet-delegated): **os-status** gained the `fix` skill (runs the check registry
|
||||
via a new `python3 hooks/checks.py --json` runner, drives each failing check's owning-plugin
|
||||
remediation, idempotent — re-run is the update path), a `remediation` pointer on every
|
||||
`Check`, two new checks (`project-graph-present` → `/os-vault:onboard-project`;
|
||||
`config-version-current` vs `CURRENT_CONFIG_VERSION`, stamped as `version=` in
|
||||
`.cc-os/config` by fix via `state.write_config_value`), and a banner header naming
|
||||
`/os-status:fix` as the single entry point; suite 64 tests (was 36). **os-backlog** gained
|
||||
`/os-backlog:route` (issue #14): `inspect` + `config-write` dispatcher subcommands
|
||||
(`lib/backlog/tracker.rb` validates the four tracker formats + classifies git remotes,
|
||||
`lib/backlog/inspector.rb` finds in-repo issue files; `Config.merge` preserves other keys),
|
||||
with destination choice and live-history migration as named human gates in the skill; suite
|
||||
54 runs/110 assertions (was 35). Human gates preserved throughout: fix never fabricates a
|
||||
tracker value and never edits global settings.json. Rollout per #14 acceptance (onboard
|
||||
cc-os itself, then one more project) still pending.
|
||||
|
||||
**Fix tune-up + per-project state consolidation (2026-07-12, issues #23/#24, ADR-027):** the
|
||||
credvault smoke-test of `/os-status:fix` (session cd1ae1cd) was audited against the SKILL.md
|
||||
contract; the run was on-contract but surfaced four gaps (stale snoozes never cleared,
|
||||
`.cc-os/config` format split between the Ruby and Python writers, ad-hoc gitignore hygiene,
|
||||
an unprompted commit) plus root-dotdir sprawl. Fixes (both sonnet-delegated, in parallel):
|
||||
**os-status** — `clear_snooze` helper + self-clearing snoozes when a check evaluates ok/note
|
||||
(both SessionStart and `--json` runners); its own state (`snooze-*`, `suppress-*`,
|
||||
`state.json`) relocated to `.cc-os/status/` with legacy fallback read + migrate-on-write
|
||||
(shared `config` stays at `.cc-os/config`); `write_config_value` normalizes the whole file to
|
||||
`key=value` (no spaces); fix SKILL.md now scopes out committing, adds an explicit
|
||||
"`.cc-os/` in .gitignore" step, and clarifies when re-runs are needed; suite 80 tests (was
|
||||
64). **os-backlog** — `Config` already emitted the normalized format; locked in by new tests
|
||||
(58 runs, was 54). **os-doc-hygiene** — state moved `.dochygiene/` → `.cc-os/dochygiene/`
|
||||
(ADR-027) with canonical-then-legacy fallback reads and auto-migration (+ legacy dir removal)
|
||||
on first write; scanner self-excludes `.cc-os/`; all four SKILL.md files updated; suite 279
|
||||
passed. `graphify-out/` explicitly exempt from consolidation (ADR-027). Re-run of
|
||||
`/os-status:fix` in credvault is the pending IRL verification.
|
||||
|
||||
**cc-os ADR retrofit (2026-07-12, via `/os-status:fix`):** the 27-ADR monolithic
|
||||
`docs/memory-system/03-architecture-decisions.md` was migrated to `docs/adr/` with
|
||||
`/os-adr:migrate`, promoted ahead of the pilot projects (ADR-020 amended in place: migrate
|
||||
pilot had already passed its gate, migrate is non-destructive, and the monolith's context
|
||||
cost was real and growing). Mechanics: the detector only scans `docs/{adr,decisions,decision}/`
|
||||
+ `DECISIONS.md`, so the source was shimmed in via a format-normalized copy under
|
||||
`docs/decisions/` (bullet-label `- **Context**: …` → line-start `**Context:** …` so the
|
||||
bold-label parser could extract sections; Rationale/Cross-references left as bullets so they
|
||||
ride inside Decision/Alternatives content). Result: 27/27 converted, flag rate 3.7% (one low:
|
||||
0016), consequences filled per file from source material (sonnet-delegated), 0004/0005/0006
|
||||
marked Superseded by 0010 with frontmatter links, `migration_source` repointed at the real
|
||||
monolith path, shim removed. The monolith is retained untouched as the historical source; new
|
||||
decisions go through `/os-adr:create`. CLAUDE.md updated (docs/adr/ layout entry,
|
||||
trigger-phrased decisions convention, os-adr rollout line). Remaining os-adr rollout: pilot
|
||||
projects one at a time, then wider.
|
||||
|
||||
**os-shortcuts plugin + `/wrap` shipped (2026-07-12, ADR-028, Planka card):** new plugin
|
||||
`plugins/os-shortcuts/` for user-invoked QOL commands — the "keybindings" of cc-os; domain
|
||||
boundary vs automatic hook injection (os-orchestration / future os-context) recorded in
|
||||
ADR-028; skills only, no hooks. First resident `/os-shortcuts:wrap` encodes the session-close
|
||||
ritual from the 2026-07-09 workflow audit (typed 20+ times): git review → commits per repo
|
||||
conventions → doc/todo sweep deferring to project CLAUDE.md → Done/In-flight/Next handoff.
|
||||
Registered in the local-plugins marketplace, enabled in settings.json, installed via
|
||||
`claude plugin install os-shortcuts@local-plugins`. Sonnet-delegated build. `/readonly`
|
||||
remains a separate open card (decide vs plan mode first).
|
||||
|
||||
**os-backlog card-move + afk-ready-skips-Review (2026-07-12, ADR-029):** the process policy
|
||||
always intended the AI to move worked cards, but the CLI had no move command, so worked/blocked
|
||||
cards accumulated in place with comments. Added `card-move --board --card --to` over
|
||||
planka-api `Cards#move`, with column-ownership rules enforced in `lib/backlog/cards.rb`
|
||||
(never into/out of Next; hitl cards never moved; never out of Done; →Done only for
|
||||
afk-ready cards). Autonomy semantics amended per user decision: afk-ready ships straight to
|
||||
Done (no Review sift); semi still stops at Review. capture/list SKILL.md updated to the
|
||||
"working a card means moving it" contract. Suite 68 runs/153 assertions (was 58/130).
|
||||
Sonnet-delegated build.
|
||||
|
||||
**os-context rename + prompt files + /readonly decision + doc-length signal (2026-07-13,
|
||||
ADR-030/031):** worked the four `semi` backlog cards after a Codex plan review. (1)
|
||||
os-orchestration renamed/generalized to **os-context** (ADR-031 supersedes ADR-019): the
|
||||
SessionStart hook is now a composer globbing `prompts/session-start/*.md` in filename order
|
||||
with enforced line budgets (warn 120 / refuse 240); `ORCHESTRATION.md` became
|
||||
`10-orchestration.md` with byte-identical output (tested); os-status audit references and
|
||||
`~/.local/state` path updated (old state path symlinked; `OS_ORCH_AUDIT_LEDGER` env var name
|
||||
kept). (2) Authored `20-kickoff-conventions.md`, `30-standing-safety.md`,
|
||||
`40-decision-memos.md` (43 lines; total injection 102/120); decision-memo auto-memory file
|
||||
deleted per single-source rule. (3) `/readonly` decided as convention-only — plan mode is
|
||||
the enforcement layer, no skill built (ADR-030). (4) os-doc-hygiene scanner gained a
|
||||
deterministic `file_length` signal (defaults 400 lines / 4000 tokens, `--max-lines` /
|
||||
`--max-tokens`); flags `docs/implementation-status.md`; suite 286 passed. Issue #25 Parts
|
||||
2–3 (index-with-progressive-disclosure distill + convention ADR) remain human-gated and
|
||||
open. Sonnet-delegated builds.
|
||||
|
||||
**Remaining optional items:** additional project onboarding (one at a time, per ADR-013); bulk
|
||||
vault migration. All required build steps complete as of 2026-06-15.
|
||||
|
||||
## Implemented components
|
||||
|
||||
**Global os-vault plugin** — `cc-os/plugins/os-vault/` (git-tracked, 2026-06-12); symlinked
|
||||
into `~/.claude/plugins/os-vault`
|
||||
- Hooks: `hooks/` — `session_start.py` (SessionStart; staleness check + detached graph
|
||||
rebuild, and, as of 2026-07-10, a fast-forward-only `git pull` for `cfg.vault_path` and
|
||||
`cfg.memsearch_dir` before the staleness check — silent on success, quiet one-line stderr
|
||||
note on failure, never blocking), `session_context.py` (project graph path only),
|
||||
`post_tool_use_write.py`, `session_end.py` (vault journal), `memsearch_sync.py` (second
|
||||
SessionEnd hook; memsearch auto-commit+push, 30s timeout), `vault_sync.py` (third
|
||||
SessionEnd hook; vault auto-commit+push to forgejo.swansoncloud.com/jared/SecondBrain, 30s
|
||||
timeout; mirrors memsearch_sync.py)
|
||||
- Shared modules: `config.py` (load_config → frozen Config dataclass), `hook_io.py`
|
||||
(read_input → HookInput dataclass), `session_state.py` (record_touch/read_touches;
|
||||
encapsulates `/tmp/claude-vault-touched-$SESSION_ID` contract)
|
||||
- Skills: `skills/` — query, write, reorganize, onboard-project (assessment-first
|
||||
onboarding: surveys repo, classifies excludes by type (11 categories), writes per-project
|
||||
`.graphifyignore`, confirms with user, then extracts using `qwen25-coder-7b-16k` — per
|
||||
ADR-017), design-template (routes template-design ↔ new-type-creation: 4-step
|
||||
template-design process + injection-economics filter, 9-step new-type lifecycle; backs
|
||||
Phase 1 of the SB Content Plan — see `docs/memory-system/09-sb-content-plan.md`)
|
||||
- Config: `config.yaml` — vault path, Ollama model (qwen25-coder-7b-16k), env vars
|
||||
- Hook wiring: `~/.claude/settings.json` (hook entries invoke `/usr/bin/python3` with
|
||||
absolute paths into cc-os)
|
||||
- Isolation seam (2026-07-06, WS2): `OS_VAULT_PATH` env var overrides `vault_path` for the
|
||||
write skill and every hook via `config.load_config()`; `OS_VAULT_SKIP_REBUILD` suppresses
|
||||
the SessionStart graphify rebuild. Added for the eval harness; zero production impact when
|
||||
unset.
|
||||
- Write-behavior eval (2026-07-06, WS2): `plugins/os-vault/eval/` — held-out unprompted
|
||||
vault-write discrimination eval (Eval B/C playbook: ambiguity ladder L1 explicit → L3
|
||||
conceptual, paired positives/negatives, 6 run-set scenarios on a new `reportgen` Ruby
|
||||
fixture + 6 frozen reserve twins in a different knowledge domain, isolated sandbox vault,
|
||||
headless-only runner, deterministic-first Ruby checker with narrow frozen offer-detection
|
||||
judge fallback stubbable via `OS_VAULT_EVAL_JUDGE_CMD`, model-free `bin/self-test` 21/21).
|
||||
**Scenario Task blocks are held-out — never run informally; the reserve set is never even
|
||||
read informally.** Procedure: `plugins/os-vault/eval/README.md`.
|
||||
- Untuned baseline grid (2026-07-06, run-set × sonnet/haiku × 3 reps + 1 counted canary, 37
|
||||
reps, zero harness errors): **positives 1/19, negatives 18/18**. Headline: at L1 (explicit
|
||||
cue) both tiers persist the knowledge every rep but route it to Claude Code's built-in
|
||||
auto-memory (`~/.claude/projects/<slug>/memory/`) instead of the vault; L2/L3 mostly don't
|
||||
persist at all; zero over-triggering anywhere. TSV:
|
||||
`eval/results/2026-07-06-baseline-grid.tsv`; full analysis: vault note
|
||||
[[os-vault-write-eval-baseline-grid-results]].
|
||||
- WS2 wording loop COMPLETE (2026-07-07, 4 iterations + confirm + held-out reserve; run-set
|
||||
AND reserve now contaminated): shipped destination-ladder write SKILL.md + SessionStart
|
||||
USAGE_NOTE (mechanical triggers + before-final-reply checkpoint), mechanical vault-root
|
||||
resolution (`${OS_VAULT_PATH:-$HOME/Documents/SecondBrain}` — fixed real-vault breaches
|
||||
found on iteration 1), fixture CLAUDE.md "Cross-project memory" section (**the
|
||||
real-project adoption template**, required to reach haiku at L2/L3; includes ADR-vs-vault
|
||||
disambiguation), candidates 2–4 unscored, post-reserve YAML-colon quoting rule. Confirm
|
||||
grid sonnet 18/18 / haiku 16/18; reserve (held-out) positives 8/18 strict / trigger-axis
|
||||
13/18, negatives 17/18 (vs baseline 1/19, 18/18). Residual gaps: YAML-hostile titles,
|
||||
haiku L2 no-trigger, generalization-laundering over-trigger. One checker false-positive
|
||||
fixed+rescored mid-loop (breach regex vs `2>/dev/null`); negative-criterion redesign
|
||||
pre-registered. TSVs: `eval/results/2026-07-07-wording-*.tsv`; loop log:
|
||||
`autoresearch/classic-260707-1253/loop-log.md`; analysis: vault note
|
||||
[[os-vault-write-eval-wording-loop-results]]. Next signal is production IRL audits.
|
||||
|
||||
**Global os-orchestration plugin** — `cc-os/plugins/os-orchestration/` (git-tracked,
|
||||
2026-07-03); symlinked into `~/.claude/plugins/os-orchestration`
|
||||
|
||||
**Renamed to os-context (2026-07-13):** generalized into a prompt-composer SessionStart
|
||||
plugin. `plugins/os-orchestration/` → `plugins/os-context/`; `ORCHESTRATION.md` moved to
|
||||
`prompts/session-start/10-orchestration.md`; `hooks/inject.py` now globs
|
||||
`prompts/session-start/*.md`, sorts by filename, and concatenates into one
|
||||
additionalContext block (byte-identical output to the old single-file behavior when only
|
||||
`10-orchestration.md` is present), with a deterministic line-count budget (warn >120
|
||||
lines, refuse >240 lines). `/os-orchestration:audit-sessions` → `/os-context:audit-sessions`;
|
||||
`~/.local/state/os-orchestration/` → `~/.local/state/os-context/` (os-status's
|
||||
`orchestration-audit-due` check and ledger env-var default updated to match). The
|
||||
timeline entries below predate the rename and refer to the plugin by its former name.
|
||||
- Hooks: `hooks/` — `inject.py` (composes `prompts/session-start/*.md` as additionalContext
|
||||
to all sessions)
|
||||
- Behavior: SessionStart hook injects an `ORCHESTRATION.md` markdown doc (hardcoded; lives
|
||||
in plugin source) as additionalContext, carrying the canonical global
|
||||
session-orchestration rule set for Claude Code across all projects.
|
||||
- Migration: migrated from a standalone repo (`~/dev/cc-plugins/orchestration/`, 2026-07-03)
|
||||
and integrated into cc-os. Supersedes the per-project copy-pasted orchestration text
|
||||
blocks that previously existed in individual project CLAUDE.md files (including a stricter
|
||||
local override that cc-os had carried — now removed; see ADR-019).
|
||||
- Session audit (WS1, 2026-07-06): 10 stratified real sessions audited via
|
||||
`audit/bin/extract` (Ruby fact-sheet extractor, dual-use as future eval checker) +
|
||||
parallel sonnet auditors + verified synthesis. Findings + E1–E4 eval-scenario backlog:
|
||||
`docs/orchestration-audit/2026-07-06-findings.md`. Headlines: model param was silently
|
||||
overridden to haiku on all 23 verified spawns — root cause found post-audit:
|
||||
`CLAUDE_CODE_SUBAGENT_MODEL=haiku` in `~/.claude/settings.json` env block (set by an
|
||||
earlier session as a cost measure; removed 2026-07-06; the Fable-5 correlation was
|
||||
coincidental timing). Omitted model param inherits the main-loop model (opus/sonnet) —
|
||||
misses cluster in pre-rollout and ops sessions; no over-sharing/full-dump failures
|
||||
anywhere.
|
||||
- Wording fixes shipped (2026-07-06, post-audit): ORCHESTRATION.md rewritten with
|
||||
trigger-conditioned when→then phrasing for the three verified clusters — explicit
|
||||
`model:` before every Agent call (cluster 2), subagent model self-report on sonnet/opus
|
||||
spawns (cluster 1 — the E1 canary proved `resolvedModel` is NOT model-visible in the
|
||||
launch result; self-report is the only observable channel), don't re-cover your own ground
|
||||
before delegating (cluster 3). Delegation thresholds unchanged. Cache refreshed via
|
||||
`bin/refresh-plugins`. Deterministic env-override detection (warn on
|
||||
`CLAUDE_CODE_SUBAGENT_MODEL`) is delegated to WS3's status-check design.
|
||||
- Eval harness E1–E3 (2026-07-06): `plugins/os-orchestration/eval/` — scripted headless
|
||||
orchestration-behavior eval scored by the audit extractor (extended with per-segment read
|
||||
targets). 6 run-set scenarios (E1P/N downgrade detection with
|
||||
`CLAUDE_CODE_SUBAGENT_MODEL=haiku` runner stub; E2P/N explicit-model fan-out vs
|
||||
no-delegation-on-trivial; E3P/N delegate-investigation vs orienting-reads-correct) + 6
|
||||
frozen reserve twins; new Node.js "relaystation" fixture with deterministic sandbox-time
|
||||
log generation; deterministic-first checker (`eval/bin/check`, narrow frozen haiku-judge
|
||||
fallback for E1 language axes only, stubbable via `ORCH_EVAL_JUDGE_CMD`); model-free
|
||||
`bin/self-test` 21/21 green incl. shipped-instruction-compliant conformance transcripts.
|
||||
FAIL axes map only to verified audit misses; tier choice informational. **Scenario Task
|
||||
blocks are held-out — never run informally.** Procedure:
|
||||
`plugins/os-orchestration/eval/README.md`.
|
||||
- Baseline grid run (2026-07-06, run-set × sonnet/haiku × 3 reps + 2 counted canaries, all
|
||||
counted, zero harness errors): negatives 18/18 PASS both tiers (zero over-delegation, zero
|
||||
false downgrade claims); positives 1/18 on the delegate-at-all axis — but transcript
|
||||
verification shows most positive FAILs are *superior direct strategies* (E2P sonnet: one
|
||||
scripted bulk edit; E3P sonnet: surgical greps over 400KB logs), which the WS1 audit
|
||||
itself scored as justified non-delegation, vs genuine miss shapes (E3P haiku: whole 112KB
|
||||
logs into own context; E2P haiku: 20-call per-file grind). Conditional rules validated
|
||||
where engaged: 14/14 spawns explicit-model; the one delegating E1P rep flagged the stubbed
|
||||
downgrade via self-report. Criterion redesign for E2P/E3P A-axes pre-registered (anchor
|
||||
thresholds independently, NOT to this grid) before any rescore/tuning; reserve stays
|
||||
frozen. ORCHESTRATION.md gained a scripted-bulk-edit carve-out. TSV:
|
||||
`eval/results/2026-07-06-baseline-grid.tsv`; full analysis: vault note
|
||||
[[os-orchestration-eval-baseline-grid-results]].
|
||||
- WS4 economics loop COMPLETE + SHIPPED (2026-07-08; run-set AND reserve now contaminated
|
||||
for future wording tuning): ORCHESTRATION.md v3 shipped — cost-asymmetry +
|
||||
tier-conditional threshold opener, symmetric delegate-when/work-directly-when trigger
|
||||
lists (replaces "delegate only when"), batching rule (~5–8 items per grouped spawn,
|
||||
SendMessage reuse), async rule, Workflow effort dial; explicit-model/self-report/
|
||||
don't-re-cover-ground rules unchanged. Harness extended first (commit b226601): real token
|
||||
econ axes — subagent transcripts persist at
|
||||
`<projects>/<flat-cwd>/<session-id>/subagents/agent-*.jsonl` with per-message usage blocks
|
||||
(solves the mini-audit's instrumentation gap; vault note
|
||||
[[claude-code-subagent-transcripts-and-token-accounting]]) — E5 batching pair + reserve
|
||||
twins (authored by subagent, held-out content never entered the tuning session), fable
|
||||
column, pre-registered E2P/E3P criterion redesign landed (scripted-direct PASS branch;
|
||||
74KB ingestion anchor + id-keyed root-cause concepts). Results: E5P 0/6 → majority-PASS
|
||||
both tiers incl. reserve twin 5/5 (fable median mltok 43% of baseline, H3 met); negatives
|
||||
clean everywhere (36/36 across confirm+reserve). Residual gaps: E1P sonnet delegate-at-all
|
||||
(fixture too small — needs bigger fixture before meaningful), fable downgrade-flag ~1/4
|
||||
judge flicker. 15 baseline reps were session-limit-truncated and mechanically
|
||||
excluded+replaced (limit-banner sweep now a standard step, promoted to the autoresearch
|
||||
howto). TSVs: `eval/results/2026-07-08-*.tsv`; loop log:
|
||||
`autoresearch/classic-260708-1039/`; vault note
|
||||
[[os-orchestration-ws4-econ-wording-results]]. IRL re-audit of ~5 real Fable sessions
|
||||
scheduled ~2026-07-22.
|
||||
- **First IRL re-audit DONE (2026-07-10, ahead of schedule):** 19 production transcripts
|
||||
post-2026-07-08 audited by 3 parallel agents against the shipped rules (run:
|
||||
`autoresearch/improve-260710-1057/`, plan in `improvement-plan.md`). Solved surfaces:
|
||||
model-param discipline (~48/49 spawns pinned), over-delegation guardrail. Tier 1 findings
|
||||
→ ORCHESTRATION.md wording patch shipped same day (grid validation impossible —
|
||||
run-set/reserve contaminated — so this is a one-shot production patch, not a wording
|
||||
loop): (1) settled-design mid-session fan-out trigger, (2) never-sleep-poll rule, (3) own
|
||||
eval/benchmark loops named as mechanical sequences, (4) unfamiliar-tree ~5-call Explore
|
||||
trigger. SendMessage worked example deliberately skipped (no violations found;
|
||||
injected-token budget). Acceptance check = next IRL audit (~2–3 weeks; baseline:
|
||||
settled-design drift 8/19 sessions). Side finding needing separate repro: harness ignored
|
||||
explicit `model: "sonnet"` pins on general-purpose agents (env override unset — distinct
|
||||
from WS1 cause); the self-report line caught it.
|
||||
- **IRL audit semi-automated (2026-07-10):** recurring biweekly audit formalized, working
|
||||
from any cwd. Deterministic layer: `audit/bin/audit-stats` (Ruby, composes the existing
|
||||
`audit/bin/extract` fact-sheets) enumerates production transcripts since the last run
|
||||
(excludes `-tmp-orch-*`/`-tmp-claude-*` sandboxes, `*-eval` dirs, active/trivial
|
||||
sessions), writes `~/.local/state/os-orchestration/audit/run-<date>/`
|
||||
(stats.tsv/flags.md/sheets) and appends the trend ledger `metrics.tsv` (seeded with the
|
||||
2026-07-10 run: 23 sessions, 52 spawns, 1 missing model). Judgment layer: new skill
|
||||
`/os-orchestration:audit-sessions` (rubric in `references/`) — sonnet auditor fan-out
|
||||
over flagged regions only, tiered synthesis, run-over-run trend verdicts, stops before
|
||||
any wording edit. Nudge: os-status check `orchestration-audit-due` warns when the
|
||||
ledger's last row is ≥14 days old (missing ledger = machine not opted in, silent; env
|
||||
override `OS_ORCH_AUDIT_LEDGER` for tests). Planka recurrence-manifest entry skipped:
|
||||
the gem's offsets are deliberately `+1y/+6m/+3m/+1m` only (issue 11) — a `+2w` offset is
|
||||
a gem change blocked on the parked publish/versioning decisions; the os-status nudge is
|
||||
the trigger for now.
|
||||
|
||||
**Global os-status plugin** — `cc-os/plugins/os-status/` (git-tracked, 2026-07-06);
|
||||
symlinked into `~/.claude/plugins/os-status`
|
||||
- Purpose: aggregated deterministic SessionStart status checks for the cc-os plugin family —
|
||||
per-project artifacts (ADR system, vault hub note) and environment hazards (subagent model
|
||||
env override). Built via OpenSpec change `add-os-status-plugin` (supersedes the WS3 plan
|
||||
doc); decision record ADR-022.
|
||||
- Architecture: checks are **in-process** plain Python functions in `hooks/checks.py` with
|
||||
the uniform signature `check(ctx) -> CheckResult(status, message)` plus one registry entry
|
||||
(no per-plugin subprocess protocol, no per-project code copies — both rejected in ADR-022
|
||||
after perspective review). Three states: `ok` (silent), `note` (near-zero-token
|
||||
additionalContext line, never snoozed/suppressed), `warn` (aggregated into at most one
|
||||
banner; once-per-day snooze + permanent `suppress-<check>` markers in gitignored
|
||||
per-project `.cc-os/` — state only, never code; `.cc-os/config` holds optional
|
||||
`hub`/`vault_path` key=value overrides).
|
||||
- Initial checks: `subagent-model-env-override` (env + `~/.claude/settings.json` `env`
|
||||
block; runs outside git projects too — catches the WS1 Cluster 1 incident deterministically
|
||||
at session start), `adr-system-present` (verbatim port of os-adr's hook behavior incl.
|
||||
`.os-adr/suppress`), `vault-hub-note-present` (config slug first, else `type/hub` +
|
||||
`project/<name>` facet-tag scan of the vault; missing → warn naming `/os-vault:write`).
|
||||
- Added 2026-07-12 (ADR-026, issue #21): `/os-status:fix` skill — the unified project
|
||||
setup/update command; runs the registry via `python3 hooks/checks.py --json` (each result
|
||||
now carries a `remediation` pointer), drives the owning plugin's remediation per failing
|
||||
check, stamps `version=` into `.cc-os/config` (`CURRENT_CONFIG_VERSION`); idempotent, so
|
||||
re-running is the update path. New checks `project-graph-present` and
|
||||
`config-version-current`; warn banner names `/os-status:fix` as the single entry point.
|
||||
- Tests: `python3 tests/hook_test.py` (64, model-free; 36 pre-#21) incl. byte-identity of
|
||||
PRESENT_NOTE/ABSENT_NOTE against os-adr's source. Invariants in `invariants.md`.
|
||||
Smoke-tested 2026-07-06 (cache==source, real headless session fired the hook,
|
||||
env-override canary warns).
|
||||
|
||||
**Global os-doc-hygiene plugin** — `cc-os/plugins/os-doc-hygiene/` (git-tracked,
|
||||
2026-07-03); symlinked into `~/.claude/plugins/os-doc-hygiene`
|
||||
- Hooks: `hooks/hooks.json` → SessionStart hook (matcher: startup|resume) runs
|
||||
`scripts/reminder.py` via `${CLAUDE_PLUGIN_ROOT}` (5s timeout), emitting a deterministic
|
||||
zero-token reminder banner
|
||||
- Behavior: Monitors stale and bloated project documentation per-project under
|
||||
`.dochygiene/` state dir (gitignored). SessionStart reminder is deterministic (no AI
|
||||
tokens, once/day snooze). Skills (verb-first, no `commands/` dispatcher — invoked directly
|
||||
as `/os-doc-hygiene:<skill>`, per [[cc-os-plugin-skill-naming-convention]]): `check`
|
||||
(AI-assisted classification of staleness signals, emits machine+human reports), `clean`
|
||||
(AI-assisted or deterministic patch application with git-safe scoped cleanup), `status`
|
||||
(read-only lifecycle-timestamp read), `sweep` (check then clean in sequence).
|
||||
Reversion-protected via invariants.md + golden-example test fixtures.
|
||||
- Migration: migrated from standalone repo (`~/dev/cc-plugins/doc-hygiene/`, 2026-07-03) and
|
||||
integrated into cc-os. No content conflicts detected. Renamed from `doc-hygiene` to
|
||||
`os-doc-hygiene` per cc-os plugin naming convention. Skills renamed
|
||||
`hygiene-check`/`hygiene-clean` → `check`/`clean`, and the `commands/hygiene.md`
|
||||
dispatcher removed in favor of two new skills (`status`, `sweep`), aligning with the
|
||||
`os-vault`/`os-orchestration` pattern of no `commands/` directory (2026-07-03).
|
||||
|
||||
**Global os-adr plugin** — `cc-os/plugins/os-adr/` (git-tracked, 2026-07-03); symlinked into
|
||||
`~/.claude/plugins/os-adr`
|
||||
- Purpose: Architecture Decision Records, consistently in every project — one
|
||||
customized-Nygard template (frontmatter
|
||||
`id`/`date`/`status`/`supersedes`/`superseded-by`/`affected-paths`/`affected-components`;
|
||||
Context/Decision/Consequences/Alternatives-rejected sections),
|
||||
`docs/adr/NNNN-kebab-title.md` one-file-per-decision + fully-regenerated
|
||||
`docs/adr/README.md` index. Built from `docs/adr-system/` (requirements `04`, PRD `05`,
|
||||
eval sketches `06`) via OpenSpec change `add-os-adr-plugin`.
|
||||
- Core: Ruby OO library `lib/adr/` (`Record`, `Repository`, `Index`, `Template`, `Detector`,
|
||||
`Migrator`, `MigrationReport`, `Finder`; Sandi Metz style, injected paths) behind thin
|
||||
CLIs in `bin/` (`adr-new`, `adr-init`, `adr-detect`, `adr-migrate`, `adr-find`). Tests:
|
||||
`ruby tests/all.rb` (47) + `python3 tests/hook_test.py` (15), all model-free. Behavioral
|
||||
invariants in `invariants.md`.
|
||||
- Hook: **moved to os-status (2026-07-06)** — the SessionStart existence check now runs as
|
||||
the `adr-system-present` check in the os-status plugin (`hooks.json` here is empty;
|
||||
`hooks/session_start.py` stays as the wording source of record, byte-copied into
|
||||
os-status). Behavior unchanged: present → near-zero-token usage note naming
|
||||
`/os-adr:create` + `/os-adr:find`; absent → once-per-day init/migrate suggestion, silenced
|
||||
permanently by `.os-adr/suppress` (still honored); silent outside git projects.
|
||||
- Skills (verb-first, no `commands/`): `create` (one-invocation templated+numbered+indexed
|
||||
ADR with mechanical supersession), `init`, `migrate` (non-destructive: detect surveyed
|
||||
shapes → mechanical heuristic fill → LLM fills only manifest-listed interpretive fields
|
||||
via `--apply-fills` → `migration_confidence` frontmatter + `docs/adr/migration-report.md`;
|
||||
old-system deletion only as an explicit separate user-approved step), `find`
|
||||
(deterministic-first retrieval: affected-paths/components match → Accepted-only filter →
|
||||
one-hop Graphify query-path expansion with graceful degradation → AI judgment over the
|
||||
candidate set only).
|
||||
- Migration pilot passed 2026-07-03 (sandboxed project copies; gate threshold 25%
|
||||
low-confidence flags): viking-warrior-training-log 0%, delta-refinery 0%, llf-schema 8.3%.
|
||||
Retrieval verified end-to-end against the real llf-schema project graph. Resolved: ADRs
|
||||
need no Graphify tag/edge convention — retrieval layer 3 expands the *query* paths via
|
||||
graph-node `source_file`s.
|
||||
- Eval A harness (2026-07-03, ADR-021): `plugins/os-adr/eval/` — prompted skill-execution
|
||||
eval across model tiers (haiku/sonnet). Two fixtures (generated with the plugin's own
|
||||
CLIs), six scenarios (S1 create, S2 create+supersede, S3 find/conflict, S4
|
||||
find/distractor, S5 init, S6 migrate+fills), deterministic Ruby checker (`eval/bin/check`,
|
||||
structural invariants, TSV mode for autoresearch), sandbox + headless-runner scripts,
|
||||
runner-prompt template. Primary run mode: in-session Agent-tool subagents with pinned
|
||||
`model:`; optimized via the `/autoresearch` Classic loop over SKILL.md *wording only*
|
||||
(checker/fixtures/scenarios frozen during a loop). Procedure:
|
||||
`plugins/os-adr/eval/README.md`. Self-tested both directions; grid run 2026-07-03, all
|
||||
scenarios × both tiers passing. Distinct from the held-out Eval B (unprompted behavior) —
|
||||
do not conflate.
|
||||
- Eval B harness (2026-07-03, OpenSpec change `add-os-adr-eval-b-harness`):
|
||||
`plugins/os-adr/eval-b/` — held-out unprompted-behavior eval (requirements 4–5). 7
|
||||
scenarios (W1–W3 write-trigger, R1–R4 retrieval) authored from the frozen shapes in
|
||||
`docs/adr-system/06-eval-scenarios.md`; dedicated Ruby webhook-relay fixture with a 6-ADR
|
||||
history (Superseded pair + near-miss distractors, generated via the plugin's own CLIs);
|
||||
R4's one-hop graph reach uses a real `graphify update` AST build (model-free, rebuilt via
|
||||
`eval-b/bin/build-fixture-graph`, never committed). **Headless-only runner**
|
||||
(`eval-b/bin/run` — fresh `claude -p` per rep, cwd = sandbox, so the real SessionStart
|
||||
hook fires; in-session subagents are invalid here, unlike Eval A) and a two-axis
|
||||
deterministic-first checker (`eval-b/bin/check`): axis (a) unprompted consultation,
|
||||
mechanical from transcript tool_use blocks; axis (b) correct-ADR citation (R1–R4) or
|
||||
new-ADR-file with a narrow frozen-rubric haiku judge fallback (W1–W3, `judge-rubric.md`,
|
||||
stubbable via `ADR_EVAL_B_JUDGE_CMD`). `R4-nograph` is the graph-degradation variant
|
||||
(expected FAIL). Self-tested both directions model-free via `eval-b/bin/self-test`.
|
||||
**Scenario Task blocks are held-out — never run them informally.** Procedure:
|
||||
`plugins/os-adr/eval-b/README.md`. Grid run 2026-07-03 (1 rep/cell): haiku 0/8 PASS;
|
||||
sonnet 5/8 PASS (fails W3, R1). `R4-nograph` FAILed on both tiers as expected. Full
|
||||
results + observations: vault note [[os-adr-eval-b-grid-results-and-observations]].
|
||||
- **Initial iteration complete (2026-07-03):** plugin build, migration pilot, Eval A grid
|
||||
(clean pass), and Eval B grid (baseline) all done — closes the first pass on os-adr.
|
||||
- **Wording experiment complete (2026-07-04):** the follow-up `/autoresearch` loop over
|
||||
Eval B wording ran (5 iterations, checker/fixtures/scenarios/rubric frozen; fixture
|
||||
CLAUDE.md declared a wording surface upfront) and closed the gap — final full grid
|
||||
**sonnet 8/8, haiku 7/8** (from 5/8 / 0/8 baseline; haiku's one miss is a W3 axis-b
|
||||
judge-boundary flicker). Winning wording shipped in `hooks/session_start.py`
|
||||
(PRESENT_NOTE), find/create SKILL.mds, and `eval-b/fixture/project/CLAUDE.md` (new — the
|
||||
trigger-phrased "Architecture decisions" section, the template for real-project adoption).
|
||||
Confirmed mechanisms: trigger-conditioned when→then phrasing beats inventory phrasing on
|
||||
both tiers; each rule must live where its precondition is visible (the reversal→supersede
|
||||
rule in the find skill's act-on-findings step fixed W3); lower tiers need *mechanical*
|
||||
triggers — semantic triggers only reach sonnet. Open: channel ablation never run;
|
||||
R4-nograph now passes both tiers, so the graph-degradation check no longer differentiates.
|
||||
Full hypothesis→result mapping: vault note [[os-adr-eval-b-wording-experiment-hypotheses]].
|
||||
**Before designing or running any autoresearch eval, Read
|
||||
`~/Documents/SecondBrain/howto/running-autoresearch-skill-evals.md`.**
|
||||
- **Eval B W3 stability check (2026-07-06):** 7 headless reps of haiku × W3 (all reps
|
||||
counted): axis (a) consultation 7/7 PASS; axis (b) recording-offer ~5/7 (~75–85%) — one
|
||||
FAIL plausibly infra, one a genuine behavioral miss. Verdict: intermittent flicker, not a
|
||||
hard gap — grid claim stays **haiku 7/8**, W3 characterized as an ~1-in-4/5 axis-b miss.
|
||||
Haiku cleared for daily use with that caveat. Recorded in the vault good-enough gate:
|
||||
[[os-adr-eval-b-wording-experiment-hypotheses]].
|
||||
- **Eval C harness built, NOT yet run as designed (2026-07-06):** `plugins/os-adr/eval-c/` —
|
||||
ambiguity-ladder DISCRIMINATION eval (held-out; Eval B is contaminated by the wording
|
||||
loop). 3 levels (explicit → moderate → conceptual framing) × paired positive/negative
|
||||
scenarios; run-set (6, job-execution domain) + frozen reserve-set (6, notifications
|
||||
domain). New Python fixture (`taskq` async job queue, 6-ADR history generated via the
|
||||
plugin's own CLIs, trigger-phrased CLAUDE.md section copied from eval-b). Scoring:
|
||||
positives = both axes; negatives FAIL **only on unneeded ADR creation**. Model-free
|
||||
`bin/self-test` green, including a truthful-citation-must-PASS guard. **Scenario Task
|
||||
blocks are held-out — never run informally.** Methodology: vault notes
|
||||
[[eval-methodology-ladder]] and [[eval-methodology-irl-feedback-loop]]; vault also gained
|
||||
an `eval-results` note type + `_templates/eval-results.md` (2026-07-06).
|
||||
- **Eval C frozen grid run (2026-07-06):** run-set × {sonnet, haiku} × 3 reps/cell (36
|
||||
headless reps, all counted) — **12/12 cells PASS at ≥2/3 majority; haiku 18/18 reps,
|
||||
sonnet 17/18**. Zero over-trigger ADR creation on any negative at any level; every
|
||||
positive pass was via governing-ADR citation (16) or judge-recognized proposal (1), never
|
||||
duplicate creation. Sonnet's one FAIL rep (P1-L1) is a final-message-citation boundary
|
||||
artifact, not a behavioral miss. Two harness defects fixed on the first live rep, BEFORE
|
||||
the grid, with Task blocks/fixtures/rubric untouched: (1) `bin/run` pipefail bug; (2)
|
||||
positive axis-b contradiction fixed via a mechanical `cited-governing` PASS branch + two
|
||||
new self-test guards (`B-via:` now recorded in TSV). Verdict: the Eval B wording
|
||||
**generalizes** — grid saturated, ceiling not found; next signal is production (rollout +
|
||||
IRL session audits), not another lab rung. Run-set is now the baseline; wording tuning
|
||||
against it moves measurement to the reserve-set. Full results: vault note
|
||||
[[os-adr-eval-c-frozen-grid-results]].
|
||||
- **Remaining (rollout order, amended 2026-07-12):** the cc-os retrofit is done (promoted
|
||||
ahead of pilots — see the 2026-07-12 timeline entry and the ADR-020 amendment); remaining:
|
||||
real-project migration/adoption one at a time via `/os-adr:migrate` — pilot projects, then
|
||||
wider. When onboarding real projects,
|
||||
add the trigger-phrased "Architecture decisions" CLAUDE.md section (copy from
|
||||
`eval-b/fixture/project/CLAUDE.md`; candidate: emit it from `/os-adr:init`/`migrate`).
|
||||
|
||||
**Graphify** — v0.8.31 at `/home/jared/.local/bin/graphify`
|
||||
- Vault graph: `~/Documents/SecondBrain/graphify-out/` — disposable, structural index
|
||||
rebuilt by SessionStart hook; handles relational/graph queries. Distinct from
|
||||
vault-index.json (planned, Plan B Phase 1): a flat `{tag: [{path, title, summary}]}`
|
||||
lookup rebuilt at SessionEnd, queried by the `/memory-find` skill for fast tag-based SB
|
||||
note discovery.
|
||||
- Project graph: `<project-root>/graphify-out/` — same pattern; gitignore it in each project
|
||||
repo
|
||||
- Vault conventions: `~/Documents/SecondBrain/vault-conventions.md` — frontmatter contract +
|
||||
tag taxonomy (canonical name decided 2026-06-09; formerly referred to as CONVENTIONS.md)
|
||||
|
||||
**memsearch** — v0.4.6 via Claude Code plugin marketplace (`memsearch@memsearch-plugins`)
|
||||
- Hooks: Stop, SessionStart, UserPromptSubmit, SessionEnd (ship with plugin)
|
||||
- Memory store: `~/.memsearch/memory/YYYY-MM-DD.md` daily files (global, cross-project, all
|
||||
clients — one store by design)
|
||||
- Index: `~/.memsearch/milvus.db` (Milvus Lite, local); embeddings via ONNX bge-m3
|
||||
- Config: `MEMSEARCH_DIR=~/.memsearch` in `~/.zshrc` for global scope
|
||||
- Skills: `/memory-recall`, `/memory-config` (ship with plugin)
|
||||
- Git sync: `~/.memsearch` is a dedicated private Forgejo repo
|
||||
(`forgejo.swansoncloud.com/jared/memsearch`); whitelist `.gitignore` commits only
|
||||
`memory/*.md`; auto-commit+push wired into `memsearch_sync.py` SessionEnd hook (relocated
|
||||
from `session-end.sh` by ADR-016, 2026-06-12; behavior preserved — see ADR-015)
|
||||
|
||||
**Obsidian vault git sync** — `~/Documents/SecondBrain` (2026-06-15)
|
||||
- Remote: `ssh://git@forgejo.swansoncloud.com:2222/jared/SecondBrain.git` (private Forgejo;
|
||||
web: `https://forgejo.swansoncloud.com/jared/SecondBrain`)
|
||||
- 52 files tracked (notes, journal, templates, vault-conventions.md, CLAUDE.md, .obsidian
|
||||
config); `graphify-out/` excluded via `.gitignore`
|
||||
- Auto-commit+push via `vault_sync.py` SessionEnd hook (mirrors `memsearch_sync.py`;
|
||||
push-only — SessionStart pull is optional future item for multi-machine)
|
||||
|
||||
**Global os-backlog plugin** — `cc-os/plugins/os-backlog/` (git-tracked, 2026-07-10);
|
||||
symlinked into `~/.claude/plugins/os-backlog`; PRD Forgejo issue #9, slices #10–#17
|
||||
- Purpose: the AI's process-management surface over Planka — deterministic tracker routing
|
||||
(Planka = task state by default; git issues = implementation specs only), mid-session
|
||||
capture, pull-only listing, board lifecycle, and the three-value autonomy convention
|
||||
(`hitl`/`semi`/`afk-ready`).
|
||||
- Lib (Ruby, os-adr `lib/`+`bin/` pattern, installed planka-api gem only (0.2.0, typed
|
||||
`Planka::Types` returns as of 2026-07-10) — no source
|
||||
coupling): `board_spec.rb` (uniform lists/labels contract), `board_ensurer.rb`
|
||||
(idempotent create/repair; Planka 2.1.1 `type` fields, shared-project + owner-manager
|
||||
visibility fix, label color candidates with fallback; `archived--` rename convention),
|
||||
`config.rb` (`.cc-os/config` parser), `resolver.rb` (pure repo→board decision:
|
||||
`use`/`activate`/`stop-and-discuss`; no network), `cards.rb` (add-at-Backlog, snapshot,
|
||||
attach_label, comment).
|
||||
- CLI: `bin/os-backlog` — `board-ensure`, `activate`, `archive`, `resolve`, `card-add`,
|
||||
`cards`, `snapshot`, `card-label`, `card-comment`, `card-move` (2026-07-12, ADR-029 —
|
||||
ownership rules enforced in lib); every path fails soft (one-line error,
|
||||
exit 1) when the gem/Planka is unavailable.
|
||||
- Skills: `/os-backlog:capture`, `/os-backlog:list`, `/os-backlog:route` (2026-07-12, issue
|
||||
#14 — tracker onboarding conversation over new `inspect`/`config-write` subcommands and
|
||||
`lib/backlog/tracker.rb`/`inspector.rb`; destination choice + live-history migration are
|
||||
named human gates) — carry the column-ownership rules (AI
|
||||
creates at Backlog, Doing→Review at most, never Next or Review→Done, never self-assigns
|
||||
`hitl`); list is pull-only per notification policy v2.
|
||||
- Agents: `agents/card-triage.md` (priority + autonomy labels only; ambiguity → `hitl`),
|
||||
`agents/board-audit.md` (four drift classes; writes at most comments).
|
||||
- Tests: `tests/` — 54 runs/110 assertions (35 pre-#14) against an in-memory
|
||||
`FakePlankaClient`; no live
|
||||
API. Companion os-status check `tracker-configured` (issue #11) validates the `tracker`
|
||||
key grammar and nudges unconfigured git projects (daily-snoozed).
|
||||
- Outstanding: Semi slices #16/#17 (injection note + /to-issues routing, ops board + rubric
|
||||
category + routing ADR); #14 (routing skill) shipped 2026-07-12 — rollout (onboard cc-os,
|
||||
then one more project) pending. Live verification
|
||||
completed 2026-07-10 (snapshot / board-ensure / card-add / card-label against production;
|
||||
gem 0.1.0 locally installed via `rake install`); re-verified 2026-07-10 (later) against the
|
||||
installed 0.2.0 gem post-migration — see "os-backlog migrated to planka-api 0.2.0" and
|
||||
"os-backlog live verification (0.2.0)" timeline entries above.
|
||||
|
||||
### os-shortcuts (plugin)
|
||||
|
||||
Global plugin: user-invoked QOL shortcut commands (ADR-028). Skills only — never hooks;
|
||||
automatic injection belongs to os-orchestration / the planned os-context.
|
||||
|
||||
- Skills: `/os-shortcuts:wrap` — session-close ritual (git review, commits per repo
|
||||
conventions, doc/todo sweep deferring to project CLAUDE.md, handoff summary). Shipped
|
||||
2026-07-12.
|
||||
- Expected future residents: additional shortcuts as audit findings warrant (`/readonly`
|
||||
card is open — decide vs plan mode before implementing).
|
||||
- **os-vault** — vault write/query/reorganize/onboard-project/design-template skills,
|
||||
SessionStart/End hooks, vault + memsearch git sync, WS2 write-behavior eval →
|
||||
[implementation-status/os-vault.md](implementation-status/os-vault.md)
|
||||
- **os-context** (ex os-orchestration) — SessionStart prompt composer
|
||||
(`prompts/session-start/*.md`), orchestration rules, audit-sessions skill, E1–E5 eval
|
||||
harness + IRL audit machinery →
|
||||
[implementation-status/os-context.md](implementation-status/os-context.md)
|
||||
- **os-status** — aggregated in-process SessionStart checks + `/os-status:fix` unified
|
||||
setup/update command →
|
||||
[implementation-status/os-status.md](implementation-status/os-status.md)
|
||||
- **os-doc-hygiene** — stale/bloated-doc monitoring; check/clean/status/sweep skills;
|
||||
deterministic scanner incl. `file_length` signal →
|
||||
[implementation-status/os-doc-hygiene.md](implementation-status/os-doc-hygiene.md)
|
||||
- **os-adr** — ADR system (Ruby `lib/adr/` + CLIs; create/init/migrate/find skills; Eval
|
||||
A/B/C harnesses; cc-os retrofit done) →
|
||||
[implementation-status/os-adr.md](implementation-status/os-adr.md)
|
||||
- **os-backlog** — Planka process surface: board lifecycle, capture/list/route skills,
|
||||
card CLI with column-ownership rules, triage/audit agents →
|
||||
[implementation-status/os-backlog.md](implementation-status/os-backlog.md)
|
||||
- **os-shortcuts** — user-invoked QOL commands, skills only, never hooks (ADR-0028);
|
||||
resident: `/os-shortcuts:wrap` session-close ritual (shipped 2026-07-12). No leaf file
|
||||
yet — this entry is the full detail.
|
||||
- **Graphify / memsearch / vault git sync** — external memory infrastructure (versions,
|
||||
paths, sync topology) →
|
||||
[implementation-status/memory-infrastructure.md](implementation-status/memory-infrastructure.md)
|
||||
|
||||
## Operational procedures
|
||||
|
||||
### Renaming or moving a local plugin
|
||||
|
||||
Renaming a plugin directory under a directory-source marketplace (like `local-plugins`, whose
|
||||
source is `~/.claude/plugins` itself) requires updating **three** places, not just the
|
||||
directory and `settings.json`:
|
||||
|
||||
1. **Plugin directory / symlink** — the actual files (or symlink target, for plugins that
|
||||
live in a git repo like `cc-os/plugins/os-vault/`).
|
||||
2. **Marketplace manifest** — `~/.claude/plugins/.claude-plugin/marketplace.json` (for
|
||||
`local-plugins`) lists each plugin's `name` and `source` path explicitly; this does
|
||||
**not** auto-discover from the directory listing. Update the entry to match the new
|
||||
name/path.
|
||||
3. **`settings.json` `enabledPlugins`** — the `<name>@<marketplace>` key must match the
|
||||
manifest entry from step 2.
|
||||
|
||||
Then refresh the plugin manager's state so it re-resolves the marketplace and drops the
|
||||
stale install record:
|
||||
|
||||
```bash
|
||||
claude plugin marketplace update <marketplace-name> # re-validates the manifest
|
||||
claude plugin install <new-name>@<marketplace-name> # creates the new install record
|
||||
claude plugin uninstall <old-name>@<marketplace-name> # drops the stale one
|
||||
claude plugin list # verify: new name enabled, old name gone
|
||||
claude plugin details <new-name>@<marketplace-name> # verify skills/agents/hooks resolved
|
||||
```
|
||||
|
||||
Skipping step 2 is the failure mode to watch for: hooks (wired by absolute path in
|
||||
`settings.json`) keep working, masking the fact that skills/slash-commands silently stopped
|
||||
registering under the plugin's new name.
|
||||
|
||||
### Editing a local plugin (cache refresh)
|
||||
|
||||
Plugin source edits (including SKILL.md wording, hook scripts, or CLI code) do not reach
|
||||
running sessions until the cache is refreshed. Claude Code caches plugins when installed,
|
||||
copying them to `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/`. To refresh a
|
||||
stale cache after source edits:
|
||||
|
||||
```bash
|
||||
bin/refresh-plugins [marketplace-names...] # refresh all or specific local marketplaces
|
||||
```
|
||||
|
||||
This uninstalls and reinstalls each plugin, forcing the cache to repopulate. See
|
||||
`bin/refresh-plugins --help` for usage. After refreshing,
|
||||
`claude plugin details <name>@<marketplace>` should show updated skill descriptions and hook
|
||||
counts. Directory-source marketplaces (e.g., `local-plugins` sourced from
|
||||
`~/.claude/plugins`, `cc-plugins` sourced from `~/dev/cc-plugins`) are the only ones that
|
||||
need manual refresh — public marketplaces auto-update.
|
||||
Runbooks (plugin rename/move, plugin cache refresh via `bin/refresh-plugins`) live in
|
||||
[implementation-status/operational-procedures.md](implementation-status/operational-procedures.md)
|
||||
— stable leaf, referenced from CLAUDE.md.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,38 @@
|
|||
# Memory infrastructure (Graphify, memsearch, vault git sync) — detail
|
||||
|
||||
_Leaf file of [../implementation-status.md](../implementation-status.md). Read on demand._
|
||||
|
||||
## Graphify — v0.8.31 at `/home/jared/.local/bin/graphify`
|
||||
|
||||
- Vault graph: `~/Documents/SecondBrain/graphify-out/` — disposable, structural index
|
||||
rebuilt by SessionStart hook; handles relational/graph queries. Distinct from
|
||||
vault-index.json (planned, Plan B Phase 1): a flat `{tag: [{path, title, summary}]}`
|
||||
lookup rebuilt at SessionEnd, queried by the `/memory-find` skill for fast tag-based SB
|
||||
note discovery.
|
||||
- Project graph: `<project-root>/graphify-out/` — same pattern; gitignore it in each project
|
||||
repo. Exempt from the `.cc-os/` state consolidation (ADR-0027).
|
||||
- Vault conventions: `~/Documents/SecondBrain/vault-conventions.md` — frontmatter contract +
|
||||
tag taxonomy (canonical name decided 2026-06-09; formerly referred to as CONVENTIONS.md).
|
||||
|
||||
## memsearch — v0.4.6 via Claude Code plugin marketplace (`memsearch@memsearch-plugins`)
|
||||
|
||||
- Hooks: Stop, SessionStart, UserPromptSubmit, SessionEnd (ship with plugin)
|
||||
- Memory store: `~/.memsearch/memory/YYYY-MM-DD.md` daily files (global, cross-project, all
|
||||
clients — one store by design; ADR-0015)
|
||||
- Index: `~/.memsearch/milvus.db` (Milvus Lite, local); embeddings via ONNX bge-m3
|
||||
- Config: `MEMSEARCH_DIR=~/.memsearch` in `~/.zshrc` for global scope
|
||||
- Skills: `/memory-recall`, `/memory-config` (ship with plugin)
|
||||
- Git sync: `~/.memsearch` is a dedicated private Forgejo repo
|
||||
(`forgejo.swansoncloud.com/jared/memsearch`); whitelist `.gitignore` commits only
|
||||
`memory/*.md`; auto-commit+push wired into os-vault's `memsearch_sync.py` SessionEnd hook
|
||||
(relocated from `session-end.sh` by ADR-0016; behavior per ADR-0015)
|
||||
|
||||
## Obsidian vault git sync — `~/Documents/SecondBrain` (2026-06-15)
|
||||
|
||||
- Remote: `ssh://git@forgejo.swansoncloud.com:2222/jared/SecondBrain.git` (private Forgejo;
|
||||
web: `https://forgejo.swansoncloud.com/jared/SecondBrain`)
|
||||
- 52 files tracked at initialization (notes, journal, templates, vault-conventions.md,
|
||||
CLAUDE.md, .obsidian config); `graphify-out/` excluded via `.gitignore`
|
||||
- Auto-commit+push via os-vault's `vault_sync.py` SessionEnd hook (mirrors
|
||||
`memsearch_sync.py`); SessionStart fast-forward pull added 2026-07-10 for multi-machine
|
||||
freshness (see [os-vault.md](os-vault.md))
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
# Operational procedures
|
||||
|
||||
_Stable runbooks referenced from CLAUDE.md. Keep this file's procedures current — they are
|
||||
the canonical copies._
|
||||
|
||||
## Renaming or moving a local plugin
|
||||
|
||||
Renaming a plugin directory under a directory-source marketplace (like `local-plugins`, whose
|
||||
source is `~/.claude/plugins` itself) requires updating **three** places, not just the
|
||||
directory and `settings.json`:
|
||||
|
||||
1. **Plugin directory / symlink** — the actual files (or symlink target, for plugins that
|
||||
live in a git repo like `cc-os/plugins/os-vault/`).
|
||||
2. **Marketplace manifest** — `~/.claude/plugins/.claude-plugin/marketplace.json` (for
|
||||
`local-plugins`) lists each plugin's `name` and `source` path explicitly; this does
|
||||
**not** auto-discover from the directory listing. Update the entry to match the new
|
||||
name/path.
|
||||
3. **`settings.json` `enabledPlugins`** — the `<name>@<marketplace>` key must match the
|
||||
manifest entry from step 2.
|
||||
|
||||
Then refresh the plugin manager's state so it re-resolves the marketplace and drops the
|
||||
stale install record:
|
||||
|
||||
```bash
|
||||
claude plugin marketplace update <marketplace-name> # re-validates the manifest
|
||||
claude plugin install <new-name>@<marketplace-name> # creates the new install record
|
||||
claude plugin uninstall <old-name>@<marketplace-name> # drops the stale one
|
||||
claude plugin list # verify: new name enabled, old name gone
|
||||
claude plugin details <new-name>@<marketplace-name> # verify skills/agents/hooks resolved
|
||||
```
|
||||
|
||||
Skipping step 2 is the failure mode to watch for: hooks (wired by absolute path in
|
||||
`settings.json`) keep working, masking the fact that skills/slash-commands silently stopped
|
||||
registering under the plugin's new name. See ADR-0018.
|
||||
|
||||
## Editing a local plugin (cache refresh)
|
||||
|
||||
Plugin source edits (including SKILL.md wording, hook scripts, or CLI code) do not reach
|
||||
running sessions until the cache is refreshed. Claude Code caches plugins when installed,
|
||||
copying them to `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/`. To refresh a
|
||||
stale cache after source edits:
|
||||
|
||||
```bash
|
||||
bin/refresh-plugins [marketplace-names...] # refresh all or specific local marketplaces
|
||||
```
|
||||
|
||||
This uninstalls and reinstalls each plugin, forcing the cache to repopulate. See
|
||||
`bin/refresh-plugins --help` for usage. After refreshing,
|
||||
`claude plugin details <name>@<marketplace>` should show updated skill descriptions and hook
|
||||
counts. Directory-source marketplaces (e.g., `local-plugins` sourced from
|
||||
`~/.claude/plugins`, `cc-plugins` sourced from `~/dev/cc-plugins`) are the only ones that
|
||||
need manual refresh — public marketplaces auto-update.
|
||||
|
|
@ -0,0 +1,121 @@
|
|||
# os-adr — component detail
|
||||
|
||||
_Leaf file of [../implementation-status.md](../implementation-status.md). Read on demand._
|
||||
|
||||
**Global os-adr plugin** — `cc-os/plugins/os-adr/` (git-tracked, 2026-07-03); symlinked into
|
||||
`~/.claude/plugins/os-adr`. Decision records: ADR-0020 (build + open-question resolutions,
|
||||
amended 2026-07-12 for the cc-os retrofit promotion), ADR-0021 (Eval A design).
|
||||
|
||||
## Component inventory
|
||||
|
||||
- Purpose: Architecture Decision Records, consistently in every project — one
|
||||
customized-Nygard template (frontmatter
|
||||
`id`/`date`/`status`/`supersedes`/`superseded-by`/`affected-paths`/`affected-components`;
|
||||
Context/Decision/Consequences/Alternatives-rejected sections),
|
||||
`docs/adr/NNNN-kebab-title.md` one-file-per-decision + fully-regenerated
|
||||
`docs/adr/README.md` index. Built from `docs/adr-system/` (requirements `04`, PRD `05`,
|
||||
eval sketches `06`) via OpenSpec change `add-os-adr-plugin`.
|
||||
- Core: Ruby OO library `lib/adr/` (`Record`, `Repository`, `Index`, `Template`, `Detector`,
|
||||
`Migrator`, `MigrationReport`, `Finder`; Sandi Metz style, injected paths) behind thin
|
||||
CLIs in `bin/` (`adr-new`, `adr-init`, `adr-detect`, `adr-migrate`, `adr-find`). Tests:
|
||||
`ruby tests/all.rb` (47) + `python3 tests/hook_test.py` (15), all model-free. Behavioral
|
||||
invariants in `invariants.md`.
|
||||
- Hook: **moved to os-status (2026-07-06)** — the SessionStart existence check now runs as
|
||||
the `adr-system-present` check in the os-status plugin (`hooks.json` here is empty;
|
||||
`hooks/session_start.py` stays as the wording source of record, byte-copied into
|
||||
os-status). Behavior unchanged: present → near-zero-token usage note naming
|
||||
`/os-adr:create` + `/os-adr:find`; absent → once-per-day init/migrate suggestion, silenced
|
||||
permanently by `.os-adr/suppress` (still honored); silent outside git projects.
|
||||
- Skills (verb-first, no `commands/`): `create` (one-invocation templated+numbered+indexed
|
||||
ADR with mechanical supersession), `init`, `migrate` (non-destructive: detect surveyed
|
||||
shapes → mechanical heuristic fill → LLM fills only manifest-listed interpretive fields
|
||||
via `--apply-fills` → `migration_confidence` frontmatter + `docs/adr/migration-report.md`;
|
||||
old-system deletion only as an explicit separate user-approved step), `find`
|
||||
(deterministic-first retrieval: affected-paths/components match → Accepted-only filter →
|
||||
one-hop Graphify query-path expansion with graceful degradation → AI judgment over the
|
||||
candidate set only).
|
||||
- Migration pilot passed 2026-07-03 (sandboxed project copies; gate threshold 25%
|
||||
low-confidence flags): viking-warrior-training-log 0%, delta-refinery 0%, llf-schema 8.3%.
|
||||
Retrieval verified end-to-end against the real llf-schema project graph. Resolved: ADRs
|
||||
need no Graphify tag/edge convention — retrieval layer 3 expands the *query* paths via
|
||||
graph-node `source_file`s.
|
||||
|
||||
## Evals
|
||||
|
||||
- **Eval A harness (2026-07-03, ADR-0021):** `plugins/os-adr/eval/` — prompted
|
||||
skill-execution eval across model tiers (haiku/sonnet). Two fixtures (generated with the
|
||||
plugin's own CLIs), six scenarios (S1 create, S2 create+supersede, S3 find/conflict, S4
|
||||
find/distractor, S5 init, S6 migrate+fills), deterministic Ruby checker (`eval/bin/check`,
|
||||
structural invariants, TSV mode for autoresearch), sandbox + headless-runner scripts,
|
||||
runner-prompt template. Primary run mode: in-session Agent-tool subagents with pinned
|
||||
`model:`; optimized via the `/autoresearch` Classic loop over SKILL.md *wording only*.
|
||||
Procedure: `plugins/os-adr/eval/README.md`. Grid run 2026-07-03, all scenarios × both
|
||||
tiers passing. Distinct from the held-out Eval B — do not conflate.
|
||||
- **Eval B harness (2026-07-03, OpenSpec change `add-os-adr-eval-b-harness`):**
|
||||
`plugins/os-adr/eval-b/` — held-out unprompted-behavior eval (requirements 4–5). 7
|
||||
scenarios (W1–W3 write-trigger, R1–R4 retrieval) from the frozen shapes in
|
||||
`docs/adr-system/06-eval-scenarios.md`; Ruby webhook-relay fixture with a 6-ADR history
|
||||
(Superseded pair + near-miss distractors); R4's one-hop graph reach uses a real
|
||||
`graphify update` AST build (rebuilt via `eval-b/bin/build-fixture-graph`, never
|
||||
committed). **Headless-only runner** (`eval-b/bin/run` — fresh `claude -p` per rep, cwd =
|
||||
sandbox, so the real SessionStart hook fires) and a two-axis deterministic-first checker
|
||||
(`eval-b/bin/check`): (a) unprompted consultation, mechanical; (b) correct-ADR citation
|
||||
(R1–R4) or new-ADR-file with a narrow frozen-rubric haiku judge fallback (W1–W3,
|
||||
stubbable via `ADR_EVAL_B_JUDGE_CMD`). **Scenario Task blocks are held-out — never run
|
||||
informally.** Procedure: `plugins/os-adr/eval-b/README.md`. Baseline grid 2026-07-03:
|
||||
haiku 0/8, sonnet 5/8 (fails W3, R1); `R4-nograph` degradation variant FAILed both tiers
|
||||
as expected. Results: vault note [[os-adr-eval-b-grid-results-and-observations]].
|
||||
- **Wording experiment complete (2026-07-04):** `/autoresearch` loop over Eval B wording (5
|
||||
iterations; checker/fixtures/scenarios/rubric frozen) closed the gap — final full grid
|
||||
**sonnet 8/8, haiku 7/8** (haiku's one miss is a W3 axis-b judge-boundary flicker).
|
||||
Winning wording shipped in `hooks/session_start.py` (PRESENT_NOTE), find/create SKILL.mds,
|
||||
and `eval-b/fixture/project/CLAUDE.md` (the trigger-phrased "Architecture decisions"
|
||||
section — the template for real-project adoption). Confirmed mechanisms:
|
||||
trigger-conditioned when→then phrasing beats inventory phrasing on both tiers; each rule
|
||||
must live where its precondition is visible (the reversal→supersede rule in the find
|
||||
skill's act-on-findings step fixed W3); lower tiers need *mechanical* triggers — semantic
|
||||
triggers only reach sonnet. Open: channel ablation never run; R4-nograph now passes both
|
||||
tiers so no longer differentiates. Full mapping: vault note
|
||||
[[os-adr-eval-b-wording-experiment-hypotheses]]. **Before designing or running any
|
||||
autoresearch eval, Read
|
||||
`~/Documents/SecondBrain/howto/running-autoresearch-skill-evals.md`.**
|
||||
- **Eval B W3 stability check (2026-07-06):** 7 headless reps of haiku × W3: axis (a) 7/7
|
||||
PASS; axis (b) ~5/7 — intermittent flicker, not a hard gap; grid claim stays **haiku
|
||||
7/8**; haiku cleared for daily use with that caveat. Recorded in
|
||||
[[os-adr-eval-b-wording-experiment-hypotheses]].
|
||||
- **Eval C harness (2026-07-06):** `plugins/os-adr/eval-c/` — ambiguity-ladder
|
||||
DISCRIMINATION eval (held-out; Eval B is contaminated by the wording loop). 3 levels
|
||||
(explicit → moderate → conceptual) × paired positive/negative scenarios; run-set (6,
|
||||
job-execution domain) + frozen reserve-set (6, notifications domain). Python `taskq`
|
||||
fixture with 6-ADR history and the eval-b trigger-phrased CLAUDE.md section. Scoring:
|
||||
positives = both axes; negatives FAIL **only on unneeded ADR creation**. Model-free
|
||||
`bin/self-test` green. **Scenario Task blocks are held-out — never run informally.**
|
||||
Methodology: vault notes [[eval-methodology-ladder]] and
|
||||
[[eval-methodology-irl-feedback-loop]]; vault gained an `eval-results` note type +
|
||||
template (2026-07-06).
|
||||
- **Eval C frozen grid run (2026-07-06):** run-set × {sonnet, haiku} × 3 reps/cell (36
|
||||
headless reps, all counted) — **12/12 cells PASS at ≥2/3 majority; haiku 18/18 reps,
|
||||
sonnet 17/18**. Zero over-trigger ADR creation on any negative; every positive pass via
|
||||
governing-ADR citation (16) or judge-recognized proposal (1), never duplicate creation.
|
||||
Sonnet's one FAIL rep is a final-message-citation boundary artifact. Two harness defects
|
||||
fixed on the first live rep, BEFORE the grid (run pipefail bug; mechanical
|
||||
`cited-governing` PASS branch + two self-test guards). Verdict: the Eval B wording
|
||||
**generalizes** — grid saturated; next signal is production (rollout + IRL session
|
||||
audits). Full results: vault note [[os-adr-eval-c-frozen-grid-results]].
|
||||
|
||||
## cc-os retrofit and rollout
|
||||
|
||||
- **cc-os ADR retrofit (2026-07-12, via `/os-status:fix`):** the 27-ADR monolithic
|
||||
`docs/memory-system/03-architecture-decisions.md` was migrated to `docs/adr/` with
|
||||
`/os-adr:migrate`, promoted ahead of the pilot projects (ADR-0020 amended in place).
|
||||
Mechanics: the detector only scans `docs/{adr,decisions,decision}/` + `DECISIONS.md`, so
|
||||
the source was shimmed in via a format-normalized copy under `docs/decisions/`
|
||||
(bullet-label → line-start bold-label so the parser could extract sections). Result: 27/27
|
||||
converted, flag rate 3.7% (one low: 0016), consequences filled per file from source
|
||||
material (sonnet-delegated), 0004/0005/0006 marked Superseded by 0010 with frontmatter
|
||||
links, `migration_source` repointed at the real monolith path, shim removed. The monolith
|
||||
is retained untouched as the historical source; new decisions go through `/os-adr:create`.
|
||||
- **Remaining (rollout order, amended 2026-07-12):** real-project migration/adoption one at
|
||||
a time via `/os-adr:migrate` — pilot projects, then wider. When onboarding real projects,
|
||||
add the trigger-phrased "Architecture decisions" CLAUDE.md section (copy from
|
||||
`eval-b/fixture/project/CLAUDE.md`; candidate: emit it from `/os-adr:init`/`migrate`).
|
||||
|
|
@ -0,0 +1,89 @@
|
|||
# os-backlog — component detail
|
||||
|
||||
_Leaf file of [../implementation-status.md](../implementation-status.md). Read on demand._
|
||||
|
||||
**Global os-backlog plugin** — `cc-os/plugins/os-backlog/` (git-tracked, 2026-07-10);
|
||||
symlinked into `~/.claude/plugins/os-backlog`; PRD Forgejo issue #9 (state pointer: Planka
|
||||
card `1816234194716592051`), slices #10–#17. Decision records: ADR-0023 (own plugin, not an
|
||||
os-vault extension), ADR-0025 (standard Ruby plugin structure), ADR-0029 (card-move +
|
||||
column ownership).
|
||||
|
||||
## Component inventory
|
||||
|
||||
- Purpose: the AI's process-management surface over Planka — deterministic tracker routing
|
||||
(Planka = task state by default; git issues = implementation specs only), mid-session
|
||||
capture, pull-only listing, board lifecycle, and the three-value autonomy convention
|
||||
(`hitl`/`semi`/`afk-ready`; amended per ADR-0029: afk-ready ships straight to Done, semi
|
||||
stops at Review).
|
||||
- Lib (Ruby, os-adr `lib/`+`bin/` pattern, installed planka-api gem only — no source
|
||||
coupling): `board_spec.rb` (uniform lists/labels contract), `board_ensurer.rb`
|
||||
(idempotent create/repair; Planka 2.1.1 `type` fields, shared-project + owner-manager
|
||||
visibility fix, label color candidates with fallback; `archived--` rename convention),
|
||||
`config.rb` (`.cc-os/config` parser), `resolver.rb` (pure repo→board decision:
|
||||
`use`/`activate`/`stop-and-discuss`; no network), `cards.rb` (add-at-Backlog, snapshot,
|
||||
attach_label, comment, move with ownership rules), `tracker.rb` + `inspector.rb`
|
||||
(2026-07-12, issue #14 — tracker-format validation/remote classification + in-repo
|
||||
issue-file discovery; `Config.merge` preserves other keys).
|
||||
- CLI: `bin/os-backlog` — `board-ensure`, `activate`, `archive`, `resolve`, `card-add`,
|
||||
`cards`, `snapshot`, `card-label`, `card-comment`, `card-move` (2026-07-12, ADR-0029),
|
||||
`inspect`, `config-write`; every path fails soft (one-line error, exit 1) when the
|
||||
gem/Planka is unavailable.
|
||||
- Skills: `/os-backlog:capture`, `/os-backlog:list` (pull-only per notification policy v2),
|
||||
`/os-backlog:route` (2026-07-12, issue #14 — tracker onboarding conversation; destination
|
||||
choice + live-history migration are named human gates) — carry the column-ownership rules
|
||||
(AI creates at Backlog, Doing→Review at most, never Next, never self-assigns `hitl`;
|
||||
"working a card means moving it" contract added 2026-07-12).
|
||||
- Agents: `agents/card-triage.md` (priority + autonomy labels only; ambiguity → `hitl`),
|
||||
`agents/board-audit.md` (four drift classes; writes at most comments).
|
||||
- Tests: `tests/` — 68 runs/153 assertions as of 2026-07-12 (35 → 54 → 58 → 68 across the
|
||||
slices) against an in-memory `FakePlankaClient`; no live API. Companion os-status check
|
||||
`tracker-configured` (issue #11) validates the `tracker` key grammar and nudges
|
||||
unconfigured git projects (daily-snoozed).
|
||||
|
||||
## Build and verification history
|
||||
|
||||
- **AFK slices shipped (2026-07-10):** #10 plugin scaffold + `board-ensure` (uniform
|
||||
lists/labels incl. new `semi` autonomy label), #11 `tracker` key in `.cc-os/config` +
|
||||
os-status check, #12 pure routing resolver CLI, #13 capture/list skills + card CLI, #15
|
||||
`card-triage` + `board-audit` named agents. Live verification same day: planka-api gem
|
||||
0.1.0 installed locally (`rake install`, rbenv 4.0.2; publish/versioning parked behind gem
|
||||
issue 13); `snapshot`, `board-ensure` (created the missing `semi` label on the cc-os
|
||||
board), `card-add` + `card-label` all succeeded against production Planka with bot
|
||||
credentials sourced from ovh-vps (`~/services/planka/bot-credentials.env`) in a subshell.
|
||||
Follow-up captured as a `hitl` Backlog card: get planka_bot into credvault (no import
|
||||
path — rotate vs. add import capability is a human decision).
|
||||
- **planka-api 0.2.0 typed-returns migration (2026-07-10, commit `8df0cb7`):** 0.2.0 returns
|
||||
`Planka::Types` value objects instead of parsed-JSON hashes. `board_ensurer.rb` and
|
||||
`cards.rb` rewritten on typed accessors; `Cards#snapshot` builds explicit string-keyed
|
||||
hashes from `BoardDetail#lists`/`#cards`/`#labels`/`#card_labels`. Test fakes rebuilt to
|
||||
return real `Planka::Types` records. JSON output stays byte-compatible, so skill/agent
|
||||
contracts are unchanged. Follow-up fix (issue #18, same day): the migration had silently
|
||||
dropped one field from the per-card snapshot hash; restored the full 19-key camelCase card
|
||||
key set plus `labels`, with a regression test pinning the key set including
|
||||
`listChangedAt`.
|
||||
- **Live verification 0.2.0 (2026-07-10, issue #20):** local machine had no `PLANKA_*`
|
||||
env/credvault entry, so the plugin tree was rsynced to `ovh-vps:/tmp/os-backlog-verify`
|
||||
and exercised there with bot credentials sourced in a subshell (contents never read or
|
||||
printed). Results: tests 35 runs/0 failures on ovh-vps; `board-ensure cc-os` idempotent
|
||||
(twice `(existing)`, nothing created); card-add/card-label/card-comment/snapshot all
|
||||
correct with the full 20-key set; test card deleted via `Planka::Client#cards.delete`
|
||||
(the CLI has no delete subcommand) and confirmed gone; verification tree removed. No
|
||||
regressions vs. pre-0.2.0.
|
||||
- **Slice 7 (2026-07-13, issue #16):** SessionStart injection note shipped
|
||||
(`hooks/session_start.py` + `hooks/hooks.json`, os-adr-style plugin-local hook): WHEN→THEN
|
||||
rules for capture / routing / promotion / column ownership / autonomy labels, ADR-0029
|
||||
semantics (the issue body's "afk-ready → Review" was wrong — caught in Codex review),
|
||||
rules only, zero board state, ~447 tokens. `/to-issues` (global skill,
|
||||
`~/.agents/skills/to-issues/`) gained a destination-tracker step reading the
|
||||
`.cc-os/config` tracker key; the `planka:`/unset default publishes slices as git issues
|
||||
on the repo remote + one Planka pointer card (spec/state boundary preserved — human gate
|
||||
decided 2026-07-13). `Backlog::Tracker.issues_destination` + 6 routing tests.
|
||||
- **Board-id cache (2026-07-13, issue #22):** `Backlog::BoardResolver` with injected config
|
||||
read/write lambdas; `board_id=` cached in `.cc-os/config` beside `tracker=` (name stays
|
||||
source of truth; id honored only for `planka:` trackers and validated against the
|
||||
returned board name; 404/mismatch/any cache failure degrades to name lookup and rewrites
|
||||
the cache; write failures never fail the command). Comment-preserving `Config.set`
|
||||
mirrors os-status's writer. 14 new tests; suite 90 runs / 198 assertions / 0 failures.
|
||||
- **Outstanding:** slice #17 (ops board + rubric category + routing ADR; blocked-by #16 now
|
||||
cleared) awaits its human decision gates; #14 routing-skill rollout (onboard cc-os
|
||||
itself, then one more project) pending.
|
||||
|
|
@ -0,0 +1,101 @@
|
|||
# os-context (formerly os-orchestration) — component detail
|
||||
|
||||
_Leaf file of [../implementation-status.md](../implementation-status.md). Read on demand._
|
||||
|
||||
**Global os-context plugin** — `cc-os/plugins/os-context/` (git-tracked); symlinked into
|
||||
`~/.claude/plugins/os-context`. Migrated 2026-07-03 from a standalone repo
|
||||
(`~/dev/cc-plugins/orchestration/`), superseding per-project orchestration text (ADR-0019);
|
||||
renamed and generalized from os-orchestration 2026-07-13 (ADR-0031). Entries below predating
|
||||
the rename refer to the plugin by its former name.
|
||||
|
||||
## Component inventory
|
||||
|
||||
- Hooks: `hooks/inject.py` — SessionStart prompt composer: globs
|
||||
`prompts/session-start/*.md`, sorts by filename, concatenates into one additionalContext
|
||||
block for all sessions, with a deterministic line-count budget (warn >120 lines, refuse
|
||||
>240 lines). Byte-identical output to the old single-file `ORCHESTRATION.md` behavior when
|
||||
only `10-orchestration.md` is present (tested).
|
||||
- Prompt files (2026-07-13): `10-orchestration.md` (the canonical session-orchestration +
|
||||
delegation-economics rules; formerly `ORCHESTRATION.md`), `20-kickoff-conventions.md`,
|
||||
`30-standing-safety.md`, `40-decision-memos.md` (43 lines; total injection 102/120).
|
||||
Decision-memo auto-memory file deleted per single-source rule.
|
||||
- Skill: `/os-context:audit-sessions` (formerly `/os-orchestration:audit-sessions`).
|
||||
- State: `~/.local/state/os-context/` (old `os-orchestration` path symlinked;
|
||||
`OS_ORCH_AUDIT_LEDGER` env var name kept). os-status's `orchestration-audit-due` check
|
||||
updated to match.
|
||||
|
||||
## Session audits and wording iterations
|
||||
|
||||
- **WS1 session audit (2026-07-06):** 10 stratified real sessions audited via
|
||||
`audit/bin/extract` (Ruby fact-sheet extractor, dual-use as future eval checker) +
|
||||
parallel sonnet auditors + verified synthesis. Findings + E1–E4 eval-scenario backlog:
|
||||
`docs/orchestration-audit/2026-07-06-findings.md`. Headlines: model param silently
|
||||
overridden to haiku on all 23 verified spawns — root cause
|
||||
`CLAUDE_CODE_SUBAGENT_MODEL=haiku` in `~/.claude/settings.json` env block (removed
|
||||
2026-07-06); omitted model param inherits the main-loop model; no over-sharing/full-dump
|
||||
failures anywhere.
|
||||
- **Wording fixes shipped (2026-07-06, post-audit):** ORCHESTRATION.md rewritten with
|
||||
trigger-conditioned when→then phrasing for the three verified clusters — explicit
|
||||
`model:` before every Agent call, subagent model self-report on sonnet/opus spawns (the E1
|
||||
canary proved `resolvedModel` is NOT model-visible in the launch result; self-report is
|
||||
the only observable channel), don't re-cover your own ground before delegating.
|
||||
Delegation thresholds unchanged. Deterministic env-override detection delegated to
|
||||
os-status (WS3).
|
||||
- **Eval harness E1–E3 (2026-07-06):** `plugins/os-context/eval/` — scripted headless
|
||||
orchestration-behavior eval scored by the audit extractor (extended with per-segment read
|
||||
targets). 6 run-set scenarios (E1P/N downgrade detection with runner stub; E2P/N
|
||||
explicit-model fan-out vs no-delegation-on-trivial; E3P/N delegate-investigation vs
|
||||
orienting-reads-correct) + 6 frozen reserve twins; Node.js "relaystation" fixture with
|
||||
deterministic sandbox-time log generation; deterministic-first checker (`eval/bin/check`,
|
||||
narrow frozen haiku-judge fallback for E1 language axes only, stubbable via
|
||||
`ORCH_EVAL_JUDGE_CMD`); model-free `bin/self-test` 21/21. **Scenario Task blocks are
|
||||
held-out — never run informally.** Procedure: `plugins/os-context/eval/README.md`.
|
||||
- **Baseline grid (2026-07-06,** run-set × sonnet/haiku × 3 reps + 2 counted canaries):
|
||||
negatives 18/18 PASS both tiers (zero over-delegation, zero false downgrade claims);
|
||||
positives 1/18 on delegate-at-all — but transcript verification shows most positive FAILs
|
||||
are *superior direct strategies* (scripted bulk edit; surgical greps over 400KB logs),
|
||||
which the WS1 audit itself scored as justified non-delegation, vs genuine miss shapes
|
||||
(haiku: whole 112KB logs into own context; 20-call per-file grind). 14/14 spawns
|
||||
explicit-model; the one delegating E1P rep flagged the stubbed downgrade via self-report.
|
||||
E2P/E3P A-axis criterion redesign pre-registered; reserve stayed frozen. ORCHESTRATION.md
|
||||
gained a scripted-bulk-edit carve-out. TSV: `eval/results/2026-07-06-baseline-grid.tsv`;
|
||||
analysis: vault note [[os-orchestration-eval-baseline-grid-results]].
|
||||
- **WS4 economics loop COMPLETE + SHIPPED (2026-07-08;** run-set AND reserve now
|
||||
contaminated for future wording tuning): ORCHESTRATION.md v3 shipped — cost-asymmetry +
|
||||
tier-conditional threshold opener, symmetric delegate-when/work-directly-when trigger
|
||||
lists, batching rule (~5–8 items per grouped spawn, SendMessage reuse), async rule,
|
||||
Workflow effort dial; explicit-model/self-report/don't-re-cover-ground rules unchanged.
|
||||
Harness extended first (commit b226601): real token-econ axes — subagent transcripts
|
||||
persist at `<projects>/<flat-cwd>/<session-id>/subagents/agent-*.jsonl` with per-message
|
||||
usage blocks (vault note [[claude-code-subagent-transcripts-and-token-accounting]]) — E5
|
||||
batching pair + reserve twins (subagent-authored, held out), fable column, pre-registered
|
||||
E2P/E3P criterion redesign landed. Results: E5P 0/6 → majority-PASS both tiers incl.
|
||||
reserve twin 5/5 (fable median mltok 43% of baseline); negatives clean everywhere
|
||||
(36/36). Residual gaps: E1P sonnet delegate-at-all (fixture too small), fable
|
||||
downgrade-flag ~1/4 judge flicker. 15 truncated baseline reps mechanically
|
||||
excluded+replaced (limit-banner sweep promoted to the autoresearch howto). TSVs:
|
||||
`eval/results/2026-07-08-*.tsv`; loop log: `autoresearch/classic-260708-1039/`; vault
|
||||
note [[os-orchestration-ws4-econ-wording-results]].
|
||||
- **First IRL re-audit DONE (2026-07-10, ahead of schedule):** 19 production transcripts
|
||||
post-2026-07-08 audited by 3 parallel agents (run: `autoresearch/improve-260710-1057/`).
|
||||
Solved surfaces: model-param discipline (~48/49 spawns pinned), over-delegation guardrail.
|
||||
Tier 1 findings → same-day one-shot ORCHESTRATION.md production patch (grid validation
|
||||
impossible — sets contaminated): settled-design mid-session fan-out trigger,
|
||||
never-sleep-poll rule, own eval/benchmark loops named as mechanical sequences,
|
||||
unfamiliar-tree ~5-call Explore trigger. Acceptance check = next IRL audit (~2–3 weeks;
|
||||
baseline: settled-design drift 8/19 sessions). Side finding needing separate repro:
|
||||
harness ignored explicit `model: "sonnet"` pins on general-purpose agents (env override
|
||||
unset — distinct from WS1 cause); the self-report line caught it.
|
||||
- **IRL audit semi-automated (2026-07-10):** recurring biweekly audit formalized, working
|
||||
from any cwd. Deterministic layer: `audit/bin/audit-stats` (Ruby, composes
|
||||
`audit/bin/extract` fact-sheets) enumerates production transcripts since the last run
|
||||
(excludes sandboxes, `*-eval` dirs, active/trivial sessions), writes
|
||||
`~/.local/state/os-context/audit/run-<date>/` (stats.tsv/flags.md/sheets) and appends the
|
||||
trend ledger `metrics.tsv` (seeded 2026-07-10: 23 sessions, 52 spawns, 1 missing model).
|
||||
Judgment layer: `/os-context:audit-sessions` (rubric in `references/`) — sonnet auditor
|
||||
fan-out over flagged regions only, tiered synthesis, run-over-run trend verdicts, stops
|
||||
before any wording edit. Nudge: os-status check `orchestration-audit-due` warns when the
|
||||
ledger's last row is ≥14 days old (missing ledger = machine not opted in, silent; env
|
||||
override `OS_ORCH_AUDIT_LEDGER` for tests). Planka recurrence-manifest entry skipped
|
||||
(gem offsets are `+1y/+6m/+3m/+1m` only; a `+2w` offset is blocked on parked gem
|
||||
publish/versioning decisions).
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
# os-doc-hygiene — component detail
|
||||
|
||||
_Leaf file of [../implementation-status.md](../implementation-status.md). Read on demand._
|
||||
|
||||
**Global os-doc-hygiene plugin** — `cc-os/plugins/os-doc-hygiene/` (git-tracked,
|
||||
2026-07-03); symlinked into `~/.claude/plugins/os-doc-hygiene`.
|
||||
|
||||
- Hooks: `hooks/hooks.json` → SessionStart hook (matcher: startup|resume) runs
|
||||
`scripts/reminder.py` via `${CLAUDE_PLUGIN_ROOT}` (5s timeout), emitting a deterministic
|
||||
zero-token reminder banner (once/day snooze).
|
||||
- Behavior: monitors stale and bloated project documentation; per-project state under
|
||||
`.cc-os/dochygiene/` (gitignored; moved from `.dochygiene/` 2026-07-12 per ADR-0027, with
|
||||
canonical-then-legacy fallback reads and auto-migration + legacy dir removal on first
|
||||
write; scanner self-excludes `.cc-os/`).
|
||||
- Skills (verb-first, no `commands/` dispatcher — invoked directly as
|
||||
`/os-doc-hygiene:<skill>`, per [[cc-os-plugin-skill-naming-convention]]): `check`
|
||||
(AI-assisted classification of staleness signals, emits machine+human reports), `clean`
|
||||
(AI-assisted or deterministic patch application with git-safe scoped cleanup), `status`
|
||||
(read-only lifecycle-timestamp read), `sweep` (check then clean in sequence).
|
||||
Reversion-protected via invariants.md + golden-example test fixtures.
|
||||
- Scanner signals: broken refs, version skew, churn, archive ratio, frontmatter markers,
|
||||
and — added 2026-07-13 (issue #25 part 1) — a deterministic `file_length` signal
|
||||
(defaults 400 lines / 4000 estimated tokens, `--max-lines` / `--max-tokens`; token
|
||||
estimate via `scripts/token_estimator.py`). Objective facts only; classification lives
|
||||
downstream. Suite 286 passed as of 2026-07-13 (279 at the ADR-0027 move).
|
||||
- Migration: migrated from standalone repo (`~/dev/cc-plugins/doc-hygiene/`, 2026-07-03) and
|
||||
integrated into cc-os; no content conflicts. Renamed `doc-hygiene` → `os-doc-hygiene` per
|
||||
the cc-os naming convention; skills renamed `hygiene-check`/`hygiene-clean` →
|
||||
`check`/`clean`; the `commands/hygiene.md` dispatcher was removed in favor of two new
|
||||
skills (`status`, `sweep`), aligning with the no-`commands/`-directory pattern
|
||||
(2026-07-03).
|
||||
|
|
@ -0,0 +1,47 @@
|
|||
# os-status — component detail
|
||||
|
||||
_Leaf file of [../implementation-status.md](../implementation-status.md). Read on demand._
|
||||
|
||||
**Global os-status plugin** — `cc-os/plugins/os-status/` (git-tracked, 2026-07-06);
|
||||
symlinked into `~/.claude/plugins/os-status`. Decision record: ADR-0022 (architecture),
|
||||
ADR-0026 (`/os-status:fix`), ADR-0027 (state location). Built via OpenSpec change
|
||||
`add-os-status-plugin` (supersedes the WS3 plan doc).
|
||||
|
||||
- Purpose: aggregated deterministic SessionStart status checks for the cc-os plugin family —
|
||||
per-project artifacts (ADR system, vault hub note) and environment hazards (subagent model
|
||||
env override).
|
||||
- Architecture: checks are **in-process** plain Python functions in `hooks/checks.py` with
|
||||
the uniform signature `check(ctx) -> CheckResult(status, message)` plus one registry entry
|
||||
(no per-plugin subprocess protocol, no per-project code copies — both rejected in
|
||||
ADR-0022). Three states: `ok` (silent), `note` (near-zero-token additionalContext line,
|
||||
never snoozed/suppressed), `warn` (aggregated into at most one banner; once-per-day snooze
|
||||
+ permanent `suppress-<check>` markers in gitignored per-project `.cc-os/status/` — state
|
||||
only, never code; shared `.cc-os/config` holds optional `hub`/`vault_path` key=value
|
||||
overrides).
|
||||
- Initial checks: `subagent-model-env-override` (env + `~/.claude/settings.json` `env`
|
||||
block; runs outside git projects too — catches the WS1 Cluster 1 incident deterministically
|
||||
at session start), `adr-system-present` (verbatim port of os-adr's hook behavior incl.
|
||||
`.os-adr/suppress`), `vault-hub-note-present` (config slug first, else `type/hub` +
|
||||
`project/<name>` facet-tag scan of the vault; missing → warn naming `/os-vault:write`).
|
||||
Later additions: `tracker-configured` (2026-07-10, os-backlog issue #11),
|
||||
`orchestration-audit-due` (2026-07-10), `project-graph-present` and
|
||||
`config-version-current` (2026-07-12).
|
||||
- Added 2026-07-12 (ADR-0026, issue #21): `/os-status:fix` skill — the unified project
|
||||
setup/update command; runs the registry via `python3 hooks/checks.py --json` (each result
|
||||
carries a `remediation` pointer), drives the owning plugin's remediation per failing
|
||||
check, stamps `version=` into `.cc-os/config` (`CURRENT_CONFIG_VERSION`); idempotent, so
|
||||
re-running is the update path. Warn banner names `/os-status:fix` as the single entry
|
||||
point. Human gates preserved: fix never fabricates a tracker value and never edits global
|
||||
settings.json.
|
||||
- Fix tune-up (2026-07-12, issues #23/#24): the credvault smoke-test of `/os-status:fix`
|
||||
(session cd1ae1cd) was on-contract but surfaced four gaps. Fixes: `clear_snooze` helper +
|
||||
self-clearing snoozes when a check evaluates ok/note (both runners); own state relocated
|
||||
to `.cc-os/status/` with legacy fallback read + migrate-on-write (ADR-0027);
|
||||
`write_config_value` normalizes the whole file to `key=value` (no spaces); fix SKILL.md
|
||||
scopes out committing, adds an explicit "`.cc-os/` in .gitignore" step, clarifies when
|
||||
re-runs are needed. Re-run of `/os-status:fix` in credvault is the pending IRL
|
||||
verification.
|
||||
- Tests: `python3 tests/hook_test.py` (80 as of 2026-07-12; 64 post-#21; 36 initial) incl.
|
||||
byte-identity of PRESENT_NOTE/ABSENT_NOTE against os-adr's source. Invariants in
|
||||
`invariants.md`. Smoke-tested 2026-07-06 (cache==source, real headless session fired the
|
||||
hook, env-override canary warns).
|
||||
|
|
@ -0,0 +1,93 @@
|
|||
# os-vault — component detail
|
||||
|
||||
_Leaf file of [../implementation-status.md](../implementation-status.md). Read on demand._
|
||||
|
||||
**Global os-vault plugin** — `cc-os/plugins/os-vault/` (git-tracked, 2026-06-12); symlinked
|
||||
into `~/.claude/plugins/os-vault`. Renamed from `memory` 2026-07-03 (ADR-0018 records the
|
||||
marketplace-manifest lesson). Plugin sourcing/port architecture: ADR-0016.
|
||||
|
||||
## Component inventory
|
||||
|
||||
- Hooks: `hooks/` — `session_start.py` (SessionStart; staleness check + detached graph
|
||||
rebuild, and, as of 2026-07-10, a fast-forward-only `git pull` (`timeout 10 git pull
|
||||
--ff-only --quiet`) for `cfg.vault_path` and `cfg.memsearch_dir` before the staleness
|
||||
check — silent on success, quiet one-line stderr note on failure (offline machine), never
|
||||
blocking; closes the multi-machine push-only gap, mirroring the push style of the sync
|
||||
hooks in the opposite direction), `session_context.py` (project graph path only),
|
||||
`post_tool_use_write.py`, `session_end.py` (vault journal), `memsearch_sync.py` (second
|
||||
SessionEnd hook; memsearch auto-commit+push, 30s timeout), `vault_sync.py` (third
|
||||
SessionEnd hook; vault auto-commit+push to forgejo.swansoncloud.com/jared/SecondBrain, 30s
|
||||
timeout; mirrors memsearch_sync.py)
|
||||
- Shared modules: `config.py` (load_config → frozen Config dataclass), `hook_io.py`
|
||||
(read_input → HookInput dataclass), `session_state.py` (record_touch/read_touches;
|
||||
encapsulates `/tmp/claude-vault-touched-$SESSION_ID` contract)
|
||||
- Skills: `skills/` — query, write, reorganize, onboard-project (assessment-first
|
||||
onboarding: surveys repo, classifies excludes by type (11 categories), writes per-project
|
||||
`.graphifyignore`, confirms with user, then extracts using `qwen25-coder-7b-16k` — per
|
||||
ADR-0017), design-template (routes template-design ↔ new-type-creation: 4-step
|
||||
template-design process + injection-economics filter, 9-step new-type lifecycle; backs
|
||||
Phase 1 of the SB Content Plan — see `docs/memory-system/09-sb-content-plan.md`)
|
||||
- Config: `config.yaml` — vault path, Ollama model (qwen25-coder-7b-16k), env vars
|
||||
- Hook wiring: `~/.claude/settings.json` (hook entries invoke `/usr/bin/python3` with
|
||||
absolute paths into cc-os)
|
||||
- Isolation seam (2026-07-06, WS2): `OS_VAULT_PATH` env var overrides `vault_path` for the
|
||||
write skill and every hook via `config.load_config()`; `OS_VAULT_SKIP_REBUILD` suppresses
|
||||
the SessionStart graphify rebuild. Added for the eval harness; zero production impact when
|
||||
unset.
|
||||
|
||||
## Build-out history (2026-06-09 → 2026-06-30)
|
||||
|
||||
- **2026-06-09:** plugin live at `~/.claude/plugins/os-vault/`; build-plan Steps 1, 2a, 2b,
|
||||
3, 6 complete (incl. `onboard-project`). Step 1: vault-conventions.md, 6 fixture notes, 14
|
||||
Graphify handbook + design notes migrated as scaffolding. Step 4 (memsearch): installed
|
||||
via marketplace, `MEMSEARCH_DIR` global, Stop hook verified, search working. Step 5a
|
||||
(memsearch git sync): private Forgejo repo, whitelist `.gitignore` (memory/*.md only),
|
||||
auto-commit+push SessionEnd hook (ADR-0015; relocated to `memsearch_sync.py` by ADR-0016).
|
||||
- **2026-06-15:** Step 5b done — vault initialized as git repo, pushed to private Forgejo
|
||||
(52 files; git chosen over Syncthing); auto-commit+push via `vault_sync.py` (runs after
|
||||
`session_end.py` so the daily journal note is included). Step 2e pilot done — llf-schema
|
||||
(PHP 8.2 WordPress plugin) onboarded via `/os-vault:onboard-project`: 605 nodes / 930
|
||||
edges / 52 communities; Ollama doc pass lossy on WordPress docs but AST pass solid. Step
|
||||
2d closed — live vault `graphify-out/` is the baseline; fixture-only build superseded.
|
||||
All required build steps complete as of this date.
|
||||
- **2026-06-17:** onboard-project moved to assessment-first onboarding with per-project
|
||||
`.graphifyignore` (ADR-0017); extraction model `qwen25-coder-7b-16k` (16k-context build of
|
||||
qwen2.5-coder:7b — larger context window cuts chunk count per doc, the main speed lever).
|
||||
- **2026-06-30:** SB Content Plan Phase 1 complete (`docs/memory-system/09-sb-content-plan.md`,
|
||||
issues #1–#6): vault-conventions.md reconciled to one authoritative typed frontmatter
|
||||
schema (slug-only filenames; `source:` and `scope` are frontmatter fields, not tags); new
|
||||
`/os-vault:design-template` skill; three templates in `~/Documents/SecondBrain/_templates/`
|
||||
(`howto.md`, `convention.md`, `reference.md` with four-subtype variant selector), each
|
||||
dogfooded; four proof-of-concept notes patched. Phase 2 (issue #7) remains open as the
|
||||
steady-state migration/onboarding epic (no code).
|
||||
|
||||
## Write-behavior eval (WS2)
|
||||
|
||||
- Harness (2026-07-06): `plugins/os-vault/eval/` — held-out unprompted vault-write
|
||||
discrimination eval (Eval B/C playbook: ambiguity ladder L1 explicit → L3 conceptual,
|
||||
paired positives/negatives, 6 run-set scenarios on a new `reportgen` Ruby fixture + 6
|
||||
frozen reserve twins in a different knowledge domain, isolated sandbox vault,
|
||||
headless-only runner, deterministic-first Ruby checker with narrow frozen offer-detection
|
||||
judge fallback stubbable via `OS_VAULT_EVAL_JUDGE_CMD`, model-free `bin/self-test` 21/21).
|
||||
**Scenario Task blocks are held-out — never run informally; the reserve set is never even
|
||||
read informally.** Procedure: `plugins/os-vault/eval/README.md`.
|
||||
- Untuned baseline grid (2026-07-06, run-set × sonnet/haiku × 3 reps + 1 counted canary, 37
|
||||
reps, zero harness errors): **positives 1/19, negatives 18/18**. Headline: at L1 (explicit
|
||||
cue) both tiers persist the knowledge every rep but route it to Claude Code's built-in
|
||||
auto-memory instead of the vault; L2/L3 mostly don't persist at all; zero over-triggering
|
||||
anywhere. TSV: `eval/results/2026-07-06-baseline-grid.tsv`; full analysis: vault note
|
||||
[[os-vault-write-eval-baseline-grid-results]].
|
||||
- WS2 wording loop COMPLETE (2026-07-07, 4 iterations + confirm + held-out reserve; run-set
|
||||
AND reserve now contaminated): shipped destination-ladder write SKILL.md + SessionStart
|
||||
USAGE_NOTE (mechanical triggers + before-final-reply checkpoint), mechanical vault-root
|
||||
resolution (`${OS_VAULT_PATH:-$HOME/Documents/SecondBrain}` — fixed real-vault breaches
|
||||
found on iteration 1), fixture CLAUDE.md "Cross-project memory" section (**the
|
||||
real-project adoption template**, required to reach haiku at L2/L3; includes ADR-vs-vault
|
||||
disambiguation), candidates 2–4 unscored, post-reserve YAML-colon quoting rule. Confirm
|
||||
grid sonnet 18/18 / haiku 16/18; reserve (held-out) positives 8/18 strict / trigger-axis
|
||||
13/18, negatives 17/18 (vs baseline 1/19, 18/18). Residual gaps: YAML-hostile titles,
|
||||
haiku L2 no-trigger, generalization-laundering over-trigger. One checker false-positive
|
||||
fixed+rescored mid-loop (breach regex vs `2>/dev/null`); negative-criterion redesign
|
||||
pre-registered. TSVs: `eval/results/2026-07-07-wording-*.tsv`; loop log:
|
||||
`autoresearch/classic-260707-1253/loop-log.md`; analysis: vault note
|
||||
[[os-vault-write-eval-wording-loop-results]]. Next signal is production IRL audits.
|
||||
Loading…
Reference in New Issue