Spec: os-backlog issue lifecycle implementation (from map #239) #250
Labels
No labels
P0
P1
P2
P3
bug
create
delete
enhancement
filed-by/agent
filed-by/user
frozen
lint-rule
needs-info
needs-triage
next
plugin/cc-architect
plugin/os
plugin/os-adr
plugin/os-aidd-lint
plugin/os-backlog
plugin/os-context
plugin/os-doc-hygiene
plugin/os-sdlc
plugin/os-vault
project/cc-os
ready-for-agent
ready-for-human
recurring
review
update
waiting
wayfinder:grilling
wayfinder:map
wayfinder:map
wayfinder:research
wayfinder:task
wayfinder:task
wontfix
worklist/deviations
worklist/lint-rule
worklist/new-implement-build
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
jared/cc-os#250
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Spec generated from wayfinder map #239 (os-backlog issue lifecycle & templates); revised 2026-08-04 after a Codex second-opinion review (14 findings; accepted defects and clarifications folded in below and into the design doc). Design source of truth:
docs/os-backlog-lifecycle.md+ ADR-0092..0096, merged to main (ea9d019). This issue is the spec parent — the work rides on its child implementation tickets (Spec: #250in each body), per the design's own one-agent-session ticket standard.Problem Statement
As a solo freelancer running an always-on backlog across projects, I have no decided, enforced lifecycle for issues. Captures, tickets, and maps are informal; templates live inside os-sdlc where other consumers can't reach them; "ready-for-agent" is an honesty-system label with no machine check; agents close issues without a consistent evidence trail; and wayfinder decomposition uses conventions os-backlog knows nothing about. The result is lifecycle leaks: under-specified tickets picked up by agents, follow-ups lost at close time, and no structural way to tell what state an issue is actually in.
Solution
Implement the decided os-backlog lifecycle: capture → refine → check-out → work → close. Canonical spec/ticket/capture templates move into os-backlog. A deterministic Ruby template validator computes an issue's structural tier (capture/ticket/map) and gates the self-applied
ready-for-agentlabel at refine-exit and again at pickup. Decision children carry fenced-YAML weighted-recommendation blocks; a recommender-blind Ruby sweep CLI (bin/decision-sweep) auto-closes cheap-reversal recommendations at ≥85% confidence and routes the rest to a human. Every AI close carries a three-part resolution comment. Wayfinder's map conventions are documented in os-backlog and its issues are exempt from readiness sweeps.User Stories
ready-for-agentonly after the template validator passes and all decision children are closed, so that the label is a machine-backed claim.ready-for-human, so that only genuinely contested decisions reach me.ready-for-agentpickup (rerun validator, verify paths/ADRs/children, cold-read for clarifying questions), so that stale tickets bounce to refine instead of producing wrong work.reviewlabel, so that there's no duplicate sign-off step./os-backlog:captureto emit the minimal capture template, so that captures are structurally recognizable to the validator.wayfinder:map/wayfinder:<type>labels,Map: #NNN, andBlocked by #NNNdocumented in os-backlog references, so that there's one vocabulary, not two.wayfinder:*issues skipped in readiness sweeps, so that map children (whose type label encodes routing) aren't flagged as unlabeled limbo.Implementation Decisions
wayfinder:maplabel ⇒ map; required template sections present ⇒ ticket; otherwise capture. Recurring/cross-project/wayfinder-child are flavors on a tier.spec,ticket,capture) live in os-backlog's references, promoted from os-sdlc's spec-and-ticket layer; os-sdlc links, never inlines (ADR-0093). Capture template is title +## Context./os-adr:findon touched paths, issue linking, decision children, readiness labels.recommendation,confidence(integer %),reversal_cost(cheap|moderate|expensive),reasoning(one line), below the prose memo. Sweep CLI holds the gate (≥85% AND cheap) hardcoded; pass ⇒ adopt + close with three-part comment; fail (any gate, or malformed/missing block) ⇒ named-gate comment +ready-for-human. Thisready-for-humanis the sweep's routing verdict, not a readiness-tier claim: it applies even towayfinder:*children, which readiness sweeps still skip (the one exception to the wayfinder exemption — ADR-0096, amended).Blocked by #NNNline to the parent ticket's body per child; "all decision children closed" is computed from those lines; an unfetchable reference is a validation failure, never silently skipped.ready-for-agent) and pickup; never at capture. Normative section semantics: present iff the##heading exactly matches the template (case-sensitive, any order) and the body is non-empty after stripping HTML comments/placeholders; duplicate headings and wrong depth are malformed; the test fixtures are the authority for accepted/rejected forms.ready-for-agentpickups only; any clarifying question strips the label with a comment and bounces. Post-bounce state: assignee removed,ready-for-agentstripped, one bounce comment naming the question; re-bounce is idempotent. Link grammar for context-load:Spec: #NNkey case-insensitive at line start, at most one; a dead/unfetchable link is a checkpoint failure ⇒ bounce.ready-for-agentandready-for-humanare mutually exclusive; tooling finding both stripsready-for-agentwith a comment and keepsready-for-human.## Resolutioncomment mandatory on AI closes, enforced at the os-backlog surface — the close command/skill refuses without a valid resolution comment; direct-API closes are out of protocol, not policed by code. Human closes encouraged, not policed. Merge approval subsumesreviewfor pipeline-worked tickets, recognized mechanically by a PR/branch link in the start or resolution comment. Recurring issues carry arecurringlabel as the flavor's mechanical marker.wayfinder:<type>supersedes readiness labels.bin/refresh-pluginsafter plugin edits.Testing Decisions
plugins/os-adr/) and os-aidd-lint's Tier 1 cop tests; the actor/evaluator split mirrors os-aidd-lint's charter-judge.Out of Scope
Further Notes
docs/os-backlog-lifecycle.md) is merged to main; implementation is unblocked.Spec: #250, sequenced byBlocked by #NNNlines: templates → capture/validator(+shared lib) → sweep → refine/check-out, with close-protocol and wayfinder-docs unblocked from the start.Resolution
Done: Spec parent complete: all child tickets (#251-#257, #261, #256) shipped — templates, capture/validator + shared lib, decision-sweep, close protocol, wayfinder docs, and finally the check-out protocol.
Evidence: branch main, commit
32ef3e6(final child #256); design docs/os-backlog-lifecycle.md + ADR-0092..0096 merged earlier (ea9d019)Follow-ups: #262 (sweep tracker-adapter fixes), #315, #316 remain open as post-spec follow-ups; refine-skill enhancements shipped under #255 — none dropped.