os-sdlc: observability node, ADR copy-tag-audit pattern, to-issues→to-tickets rename adopted
- 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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VgG2g9ooqbnBiZYGAonGYG
This commit is contained in:
jared
parent
79012c4fda
commit
4cc524b3a5
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 <N> --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 <N> --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.
|
||||
|
|
|
|||
|
|
@ -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:<board>`.
|
||||
- **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:<owner>/<repo>` or `github:<owner>/<repo>`.
|
||||
- **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:<owner>/<repo>` or `github:<owner>/<repo>`.
|
||||
- **WHEN** a project already tracks issues in-repo (`docs/issues/`, `ISSUES.md`) and wants to stay there → `repo:<path>` (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.
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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 <ticket>`. 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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue