From 4cc524b3a505de0fd1474ca32a397b912470b9f4 Mon Sep 17 00:00:00 2001 From: jared Date: Thu, 16 Jul 2026 16:08:23 -0400 Subject: [PATCH] =?UTF-8?q?os-sdlc:=20observability=20node,=20ADR=20copy-t?= =?UTF-8?q?ag-audit=20pattern,=20to-issues=E2=86=92to-tickets=20rename=20a?= =?UTF-8?q?dopted?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - reference/pipeline-observability.md: new tenth concept node (run exhaust, predefined lifespans via os-doc-hygiene, copy-tag-audit pattern) - self-improvement-loops: ADR-audit mechanics via vault-copy hook + virgin-tag - spec-and-ticket-layer: to-tickets confirmed as Pocock v1.1 rename of to-issues (leftover skill removed from ~/.agents/skills) - OVERVIEW: map + index updated, grill queue recorded - repo docs: live /to-issues references swapped to /to-tickets Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01VgG2g9ooqbnBiZYGAonGYG --- CLAUDE.md | 2 +- docs/implementation-status.md | 2 +- docs/implementation-status/os-backlog.md | 6 +-- docs/issue-workflow.md | 10 ++-- plugins/os-backlog/skills/route/SKILL.md | 2 +- plugins/os-sdlc/OVERVIEW.md | 12 +++++ .../reference/pipeline-observability.md | 46 +++++++++++++++++++ plugins/os-sdlc/reference/pipeline-stages.md | 5 +- .../reference/self-improvement-loops.md | 13 ++++-- .../reference/spec-and-ticket-layer.md | 9 ++-- 10 files changed, 86 insertions(+), 21 deletions(-) create mode 100644 plugins/os-sdlc/reference/pipeline-observability.md diff --git a/CLAUDE.md b/CLAUDE.md index d44fe99..2cd2da2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -108,7 +108,7 @@ next signal is production IRL session audits. ## Issue tracking -Issues (created via `/to-issues`) live on self-hosted Forgejo (`jared/cc-os`), queried with +Issues (created via `/to-tickets`) live on self-hosted Forgejo (`jared/cc-os`), queried with the `tea` CLI — not GitHub/`gh`. See `docs/issue-workflow.md`. ## OpenSpec workflow diff --git a/docs/implementation-status.md b/docs/implementation-status.md index 405b967..9ae56fb 100644 --- a/docs/implementation-status.md +++ b/docs/implementation-status.md @@ -61,7 +61,7 @@ entry is in the leaf file named. (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 + shipped: SessionStart injection note + /to-tickets tracker routing (issue #16); board-id cache via BoardResolver (issue #22); slice 8 — Operations board + tracker-routing rubric category + ADR-0033 canonizing Planka-state/git-issues-spec (issue #17); route inspect issue-shape classification + split-by-kind default (issue #26); cross-project filing diff --git a/docs/implementation-status/os-backlog.md b/docs/implementation-status/os-backlog.md index 2cbdf14..d91c46e 100644 --- a/docs/implementation-status/os-backlog.md +++ b/docs/implementation-status/os-backlog.md @@ -73,8 +73,8 @@ column ownership). (`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 + rules only, zero board state, ~447 tokens. `to-issues` (now `to-tickets`; global skill, + then at `~/.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. @@ -89,7 +89,7 @@ column ownership). IRL audit (recurring)" (card `1818310715438531668`, P2 + semi, first progress comment `1818310889929966683`; recurrence contract: comment + move back to Backlog, never Done). Tracker-routing convention canonized as **ADR-0033** (Planka = state / git issues = specs, - tracker key grammar, pointer + promotion rules; cites route/to-issues/session-start + tracker key grammar, pointer + promotion rules; cites route/to-tickets/session-start rather than restating). os-context audit rubric gained category 8 `tracker-routing` (capture/route/promote compliance only). Bug found live and fixed: label color fallback only rescued `Planka::ValidationError`, but Planka rejects unknown colors as HTTP 400 diff --git a/docs/issue-workflow.md b/docs/issue-workflow.md index 34f653f..e90c070 100644 --- a/docs/issue-workflow.md +++ b/docs/issue-workflow.md @@ -1,8 +1,10 @@ # Issue workflow (Forgejo + tea) -_Last updated: 2026-06-30._ +_Last updated: 2026-07-16._ -How issues created by the `/to-issues` skill get tracked and implemented in this repo. +Note (2026-07-16): the `/to-issues` skill was renamed to `/to-tickets` in Matt Pocock's v1.1 skill set. + +How issues created by the `/to-tickets` skill get tracked and implemented in this repo. ## Tracker @@ -33,7 +35,7 @@ tea issues --repo jared/cc-os # view one issue's body ## Implement -There is **no auto-trigger and no `/grab` command**. Issues from `/to-issues` are written as independently-grabbable tracer-bullet slices. To implement: +There is **no auto-trigger and no `/grab` command**. Issues from `/to-tickets` are written as independently-grabbable tracer-bullet slices. To implement: 1. Pick the next **unblocked** issue (check the "Blocked by" line in the body — slices often form a linear chain). 2. Hand it to a coding session: _"implement issue #N from forgejo jared/cc-os"_. @@ -48,4 +50,4 @@ tea issues close --repo jared/cc-os ## Caveat -The Matt-Pocock `to-issues` / `triage` skills default to **GitHub** and were never wired to this Forgejo/`tea` backend for cc-os (no `docs/agents/` config, no `.scratch/`). Re-running them assumes GitHub. Running `/setup-matt-pocock-skills` and describing the `tea`/Forgejo workflow would wire them to the right tracker. +The Matt-Pocock `to-tickets` (formerly `to-issues`) / `triage` skills default to **GitHub** and were never wired to this Forgejo/`tea` backend for cc-os (no `docs/agents/` config, no `.scratch/`). Re-running them assumes GitHub. Running `/setup-matt-pocock-skills` and describing the `tea`/Forgejo workflow would wire them to the right tracker. diff --git a/plugins/os-backlog/skills/route/SKILL.md b/plugins/os-backlog/skills/route/SKILL.md index 66075d4..9ea342d 100644 --- a/plugins/os-backlog/skills/route/SKILL.md +++ b/plugins/os-backlog/skills/route/SKILL.md @@ -9,7 +9,7 @@ Register a project's issue tracker: figure out what already exists, propose wher Planka = state, git issues = specs (ADR-0033, `docs/adr/0033-tracker-routing-planka-is-state-git-issues-are-specs.md`) — the ADR is the canonical statement; the operative routing rules are: - **WHEN** the project's work is mostly ephemeral tasks, small fixes, or process/coordination (state: backlog/next/doing/review/done, nothing needing a durable written spec) → `planka:`. -- **WHEN** work is specified as text that must survive and be referenced (features, migrations, architecture-level changes, tracer-bullet slices from `/to-issues`, PRDs from `/to-prd`) → `forgejo:/` or `github:/`. +- **WHEN** work is specified as text that must survive and be referenced (features, migrations, architecture-level changes, tracer-bullet slices from `/to-tickets`, PRDs from `/to-prd`) → `forgejo:/` or `github:/`. - **WHEN** a project already tracks issues in-repo (`docs/issues/`, `ISSUES.md`) and wants to stay there → `repo:` (the escape hatch). - **WHEN** a code effort needs both state tracking and a durable spec → card-as-pointer + issue-chain-as-spec: the Planka card is a pointer (title + link) into the git issue chain holding the spec; never duplicate spec text into the card description. - **WHEN** a Planka-tracked effort accretes significant code/design decisions in card comments → flag promotion to the user (open a git issue chain for the spec, turn the card into a pointer); never promote silently. diff --git a/plugins/os-sdlc/OVERVIEW.md b/plugins/os-sdlc/OVERVIEW.md index bc5d9bf..453c275 100644 --- a/plugins/os-sdlc/OVERVIEW.md +++ b/plugins/os-sdlc/OVERVIEW.md @@ -37,8 +37,10 @@ graph TD PS --> AD[agent-design-principles] PS --> WP[worktree-parallelism] DG --> PF[plugin-factory] + PS --> PO[pipeline-observability] PS -.blocked stage.-> NAT[never-ask-twice] NAT <--> SIL[self-improvement-loops] + PO --> SIL SIL --> PF PS -.deferred.-> HZ[horizon] WP -.deferred.-> HZ @@ -54,6 +56,7 @@ graph TD | [deterministic-gates](reference/deterministic-gates.md) | settled | Hooks, not agents, run tests/lint; red/green asserted mechanically; green command pluggable per project | | [agent-design-principles](reference/agent-design-principles.md) | settled | Single job, minimal tool allowlist (programmer: no Bash), settled facts in via prompt, minimum out via return format | | [worktree-parallelism](reference/worktree-parallelism.md) | direction | Worktree-per-spec, sequential tickets within a spec, parallel across specs, human merge gate | +| [pipeline-observability](reference/pipeline-observability.md) | direction | What a run writes down (exhaust), where it lives, predefined lifespans (os-doc-hygiene); copy-tag-audit pattern feeds the loops | | [never-ask-twice](reference/never-ask-twice.md) | direction | The agency mechanism: two-tier lookup → mint-time scope classification → audit promotion; decision-category autonomy labels | | [self-improvement-loops](reference/self-improvement-loops.md) | direction | Session audits, ADR audits, eval harnesses, skill-lint — each catches a different drift | | [plugin-factory](reference/plugin-factory.md) | direction | Same factory builds plugins from a PRD; the eval harness is the green command | @@ -80,6 +83,15 @@ Everything in [horizon](reference/horizon.md) stays unbuilt until the interactiv factory is trusted. Open items live per-node in each doc's "Open questions" — this file carries none. +**Grill queue** (decided 2026-07-16): the critical path is +[spec-and-ticket-layer](reference/spec-and-ticket-layer.md) → +[pipeline-stages](reference/pipeline-stages.md) — grill in that order first. +Then [never-ask-twice](reference/never-ask-twice.md) + +[self-improvement-loops](reference/self-improvement-loops.md) (can run in +parallel with pipeline build; NAT's formalization ADR is independent), then +[horizon](reference/horizon.md). The remaining nodes' open questions are +implementation-time calls, not grill material. + ## Sources - Vault: `matt-pocock-skills-v1-1-changes.md`, `agentic-sdlc-ai-developer-workflow-taxonomy.md` diff --git a/plugins/os-sdlc/reference/pipeline-observability.md b/plugins/os-sdlc/reference/pipeline-observability.md new file mode 100644 index 0000000..2ce64b2 --- /dev/null +++ b/plugins/os-sdlc/reference/pipeline-observability.md @@ -0,0 +1,46 @@ +# pipeline observability + +_Status: direction — as of 2026-07-16_ +_Connects to: [pipeline-stages](pipeline-stages.md), [self-improvement-loops](self-improvement-loops.md), [never-ask-twice](never-ask-twice.md), [overview](../OVERVIEW.md)_ + +## Purpose + +Defines what a pipeline run writes down — its exhaust — where it goes, and how long it +lives. The self-improvement loops and the never-ask-twice promotion mechanism are only as +good as this exhaust; it was implicit in the original design and is made explicit here. +Load this before designing any run report, audit input, or blocked-stage log. + +## Design + +- **Every run emits exhaust**: stages executed, actor per stage, gate outcomes (red/green, + iterations consumed), blocked-stage reports (the questions the pipeline could not + auto-resolve — [never-ask-twice](never-ask-twice.md)'s raw input), and a human-facing + summary. This is the feed the loops in + [self-improvement-loops](self-improvement-loops.md) consume. +- **Every exhaust artifact has a predefined lifespan** (composes with os-doc-hygiene): + run-scoped scratch dies with the worktree; run reports persist on the ticket; anything + durable gets *promoted* to its proper home (ADR, vault note, issue comment) rather than + accumulating as clutter. No unbounded log directories. +- **Copy → tag → audit pattern** (deterministic where possible, per the three-actor test): + the write side is a hook (code actor), the review side is the periodic audit (agent + actor). Reference case — ADRs: the ADR-writing skill becomes a named agent whose hook + copies every new ADR into the vault at write time; the ADR audit then reads only *virgin* + (untagged) vault copies, keeps the durable ones, revises for clarity where needed, and + tags them audited — the next round checks only new virgin ADRs. The same pattern + generalizes to other streams (blocked-stage reports, run reports): mechanical capture at + write time, audit consumes the untagged backlog, tagging marks progress. + +## Open questions + +- Run-report format and home: an issue comment on the ticket (durable, in-tracker, visible + at merge review) vs. a file artifact — leaning issue comment. +- Lifespan policy per artifact class (scratch / run report / blocked-stage report) and how + os-doc-hygiene enforces it. +- Which exhaust stream gets the copy-tag-audit hook first (ADRs are the obvious pilot). + +## Sources + +- 2026-07-16 design session — user-identified gap ("I assumed this mechanism was baked into + the concept") + the ADR copy-tag-audit proposal +- os-doc-hygiene plugin (lifespan enforcement) +- ADR-0037 diff --git a/plugins/os-sdlc/reference/pipeline-stages.md b/plugins/os-sdlc/reference/pipeline-stages.md index 241d713..e05131c 100644 --- a/plugins/os-sdlc/reference/pipeline-stages.md +++ b/plugins/os-sdlc/reference/pipeline-stages.md @@ -1,7 +1,7 @@ # pipeline stages _Status: direction — as of 2026-07-16_ -_Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [worktree-parallelism](worktree-parallelism.md), [overview](../OVERVIEW.md)_ +_Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [worktree-parallelism](worktree-parallelism.md), [pipeline-observability](pipeline-observability.md), [overview](../OVERVIEW.md)_ ## Purpose @@ -29,7 +29,8 @@ Manually triggered by `/implement `. Stages, in order: aligns with both tests and spec. Order matters — misaligned tests invalidate a "code passes tests" result. 7. **Cleanup & report** (agent/code mix) — trims scratch artifacts, produces a summary for the - human. + human. What gets written, where, and for how long is defined in + [pipeline-observability](pipeline-observability.md). 8. **Human merge gate** — v1 has no automated merge; see [worktree-parallelism](worktree-parallelism.md). diff --git a/plugins/os-sdlc/reference/self-improvement-loops.md b/plugins/os-sdlc/reference/self-improvement-loops.md index 14ee7ca..eabc262 100644 --- a/plugins/os-sdlc/reference/self-improvement-loops.md +++ b/plugins/os-sdlc/reference/self-improvement-loops.md @@ -1,7 +1,7 @@ # self improvement loops _Status: direction — as of 2026-07-16_ -_Connects to: [never-ask-twice](never-ask-twice.md), [plugin-factory](plugin-factory.md), [overview](../OVERVIEW.md)_ +_Connects to: [never-ask-twice](never-ask-twice.md), [plugin-factory](plugin-factory.md), [pipeline-observability](pipeline-observability.md), [overview](../OVERVIEW.md)_ ## Purpose @@ -29,7 +29,11 @@ audit's own cost/latency never blocks a ticket. scope-classification judgment calls that slipped through at mint time. A wrong mint-time call is treated as a delay, not a loss — anything missed gets caught in the next ADR audit, so the loop is self-correcting rather than requiring the mint-time call to be - perfect. + perfect. Proposed mechanics (2026-07-16, user): the copy-tag-audit pattern from + [pipeline-observability](pipeline-observability.md) — a hook copies every new ADR into + the vault at write time; the audit reads only *virgin* (untagged) copies, keeps the + durable ones, revises for clarity, tags them audited; the next round checks only new + virgin ADRs. This makes the capture side deterministic and the audit's workload bounded. - **c. Eval harnesses** (exists — autoresearch pattern, already running for os-vault, os-adr, os-context) — catches capability regression. Functions as "the AI version of TDD" for plugin-type projects: a plugin's eval suite is the thing that must stay green across @@ -47,8 +51,9 @@ Together, these four loops are: ## Open questions -- ADR-audit criteria: what specifically counts as "stale," how missed promotions are - detected mechanically (diffing local ADRs against vault convention notes?), and cadence. +- ADR-audit criteria: what specifically counts as "stale" and "durable," and cadence. + (Mechanical detection is now sketched via the copy-tag-audit pattern above — remaining + question is the judgment rubric the audit applies to each virgin ADR.) - Whether ADR audits live in os-context (alongside the existing session-audit skill) or in os-adr (alongside `find`/`create`/`migrate`) — an ownership question, not yet settled. - Whether (a)-(d) should share a common audit-report format so diff --git a/plugins/os-sdlc/reference/spec-and-ticket-layer.md b/plugins/os-sdlc/reference/spec-and-ticket-layer.md index ed74d35..7cb8fc7 100644 --- a/plugins/os-sdlc/reference/spec-and-ticket-layer.md +++ b/plugins/os-sdlc/reference/spec-and-ticket-layer.md @@ -26,8 +26,9 @@ issue-tracker state for os-sdlc. - **to-spec** — publishes the sharpened plan to the issue tracker as a spec-bearing issue (or epic-equivalent) — the durable artifact other stages read from. - **to-tickets** — decomposes the spec into feature-specific, independently-implementable - increments, each its own issue, tracer-bullet style (same shape as the existing - `to-issues` skill, but scoped to a published spec rather than an ad hoc plan). + increments, each its own issue, tracer-bullet style. Confirmed 2026-07-16: this is + Pocock's v1.1 *rename* of `to-issues` ("a spec defines the destination; tickets are the + journey"), not a sibling — the leftover `to-issues` skill was removed the same day. - **`/implement`** — consumes exactly one ticket into the [pipeline-stages](pipeline-stages.md) pipeline. One ticket in, one worktree/branch out (see [worktree-parallelism](worktree-parallelism.md)). @@ -46,8 +47,6 @@ issue-tracker state for os-sdlc. (DeltaRefinery decomposed work into explicit levels; Pocock's wayfinder is looser). - Concrete spec issue template (sections, required fields) and ticket issue template (acceptance criteria shape, tracer-bullet slice size). -- Whether `to-tickets` reuses the existing `to-issues` skill directly or needs its own - spec-aware variant. ## Sources @@ -55,5 +54,5 @@ issue-tracker state for os-sdlc. - ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog) - `plugins/os-sdlc/OVERVIEW.md` - SecondBrain vault: `matt-pocock-skills-v1-1-changes.md` -- `plugins/os-backlog/` (tracker key, `issue-create`/`issues` CLI, `to-issues` skill) +- `plugins/os-backlog/` (tracker key, `issue-create`/`issues` CLI) - 2026-07-16 design session (this doc's origin)