jared/cc-os

Watch

Fork 0

Document map drafting and the promote-map step #882

New issue

Closed

opened 2026-10-01 15:26:47 +00:00 by jared · 2 comments

jared commented

2026-10-01 15:26:47 +00:00

Owner

Problem

ADR-0258 decision 9 lets map-router draft maps/drafts/<name>.yaml, and makes promotion to maps/ a human decision driven by recurrence. The map-making skill and the map-router agent (#869) teach selection only. plugins/os-sdlc/references/escalation-procedure.md step 4 has no step where the orchestrator assesses whether a misfit will recur and captures a "promote map X" ticket.

Reproduce

n/a: prose change, nothing to reproduce.

Approach

plugins/os-sdlc/skills/map-making/SKILL.md: add a drafting section. When to draft (no approved map's fits: matches); where (<drafts root>/<name>.yaml, where the drafts root is Map.drafts_dir(env), the per-user data directory in ADR-0264); what a draft must hold (name, fits, entries, the waiting node, the map-router node, escalate routes, and every path from an entry to merge-ready through required-work and suite); how to read a validator error from the reroute gate and redraft (at most 2 rounds).
plugins/os-sdlc/agents/map-router.md: say when to draft instead of select, and that a drafted map is a file under the catalog drafts root (Map.drafts_dir(env)) and the handoff carries no draft flag.
plugins/os-sdlc/references/escalation-procedure.md: add the recurrence step. Before os-sdlc-reroute-request, the orchestrator decides whether this ticket shape is likely to recur. If yes, it lets map-router draft and captures a "promote map " ticket with /os-backlog:capture. Promotion to maps/ stays a human decision, and it is mv <drafts root>/<name>.yaml plugins/os-sdlc/maps/<name>.yaml followed by git add, not git mv, because a draft is unversioned until promoted (ADR-0264, amending ADR-0261; no Ruby promotion method). Each later run that would have used the draft is recorded as an os-backlog occurrence comment on the "promote map " ticket; that is the usage evidence for the decision. Drafts are never selectable by change-auditor reroutes.

Required work:

Teach drafting in the map-making skill — check: present Map.drafts_dir in plugins/os-sdlc/skills/map-making/SKILL.md
Teach drafting to map-router — check: present Map.drafts_dir in plugins/os-sdlc/agents/map-router.md
Add the promotion step to the escalation procedure — check: present promote map in plugins/os-sdlc/references/escalation-procedure.md

Acceptance criteria

Given the edited map-making skill, when map-router finds no approved map whose fits: matches, then the skill tells it where to write a draft, what the draft must contain, and how to redraft from a reroute-gate validator error.
Given the edited escalation procedure, when the orchestrator handles a misfit escalation, then a step tells it to assess recurrence and, if likely, capture a "promote map " ticket, and says promotion is a human decision made by mv plus git add, plus occurrence comments on that ticket.

Owner sketch

n/a: prose only.

Authoring guidance (user ruling, verbatim)

Use existing project agents/skills (plugins/os-sdlc/agents/.md, plugins/os-sdlc/skills/) as examples, plus the orwell-writing skill, the os-sdlc:technical-communication skill, cc-architect (plugins/cc-architect, incl. references/conventions/cc-os-naming.md: never name: in SKILL.md frontmatter, no commands/ dir), and the mattpocock-skills:writing-for-agents skill, to guide language and structure.

Origin

Trigger: user ruling on the map reroute design, 2026-10-01 (ADR-0258 decision 9)
Improvised this session: none
Chain: drafted maps are never promoted ← no step assesses recurrence ← DESIGN (docs/adr/0258)
Root candidate: #859
Where: plugins/os-sdlc/references/escalation-procedure.md
Improvised this session: none
Root candidate: #859
Session: 55a56279-83ee-47d5-a21e-ee67f9e28abd
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/55a56279-83ee-47d5-a21e-ee67f9e28abd.jsonl

Parent: #859
Blocked by: #869, #874, #881

## Problem ADR-0258 decision 9 lets map-router draft `maps/drafts/<name>.yaml`, and makes promotion to `maps/` a human decision driven by recurrence. The map-making skill and the map-router agent (#869) teach selection only. `plugins/os-sdlc/references/escalation-procedure.md` step 4 has no step where the orchestrator assesses whether a misfit will recur and captures a "promote map X" ticket. ## Reproduce n/a: prose change, nothing to reproduce. ## Approach 1. `plugins/os-sdlc/skills/map-making/SKILL.md`: add a drafting section. When to draft (no approved map's `fits:` matches); where (`<drafts root>/<name>.yaml`, where the drafts root is `Map.drafts_dir(env)`, the per-user data directory in ADR-0264); what a draft must hold (`name`, `fits`, `entries`, the waiting node, the map-router node, escalate routes, and every path from an entry to `merge-ready` through `required-work` and `suite`); how to read a validator error from the reroute gate and redraft (at most 2 rounds). 2. `plugins/os-sdlc/agents/map-router.md`: say when to draft instead of select, and that a drafted map is a file under the catalog drafts root (`Map.drafts_dir(env)`) and the handoff carries no draft flag. 3. `plugins/os-sdlc/references/escalation-procedure.md`: add the recurrence step. Before `os-sdlc-reroute-request`, the orchestrator decides whether this ticket shape is likely to recur. If yes, it lets map-router draft and captures a "promote map <name>" ticket with `/os-backlog:capture`. Promotion to `maps/` stays a human decision, and it is `mv <drafts root>/<name>.yaml plugins/os-sdlc/maps/<name>.yaml` followed by `git add`, not `git mv`, because a draft is unversioned until promoted (ADR-0264, amending ADR-0261; no Ruby promotion method). Each later run that would have used the draft is recorded as an `os-backlog occurrence` comment on the "promote map <name>" ticket; that is the usage evidence for the decision. Drafts are never selectable by change-auditor reroutes. Required work: 1. Teach drafting in the map-making skill — check: present `Map.drafts_dir` in `plugins/os-sdlc/skills/map-making/SKILL.md` 2. Teach drafting to map-router — check: present `Map.drafts_dir` in `plugins/os-sdlc/agents/map-router.md` 3. Add the promotion step to the escalation procedure — check: present `promote map` in `plugins/os-sdlc/references/escalation-procedure.md` ## Acceptance criteria 1. Given the edited map-making skill, when map-router finds no approved map whose `fits:` matches, then the skill tells it where to write a draft, what the draft must contain, and how to redraft from a reroute-gate validator error. 2. Given the edited escalation procedure, when the orchestrator handles a misfit escalation, then a step tells it to assess recurrence and, if likely, capture a "promote map <name>" ticket, and says promotion is a human decision made by `mv` plus `git add`, plus occurrence comments on that ticket. ## Owner sketch n/a: prose only. ## Authoring guidance (user ruling, verbatim) Use existing project agents/skills (plugins/os-sdlc/agents/*.md, plugins/os-sdlc/skills/*) as examples, plus the orwell-writing skill, the os-sdlc:technical-communication skill, cc-architect (plugins/cc-architect, incl. references/conventions/cc-os-naming.md: never `name:` in SKILL.md frontmatter, no commands/ dir), and the mattpocock-skills:writing-for-agents skill, to guide language and structure. ## Origin - Trigger: user ruling on the map reroute design, 2026-10-01 (ADR-0258 decision 9) - Improvised this session: none - Chain: drafted maps are never promoted ← no step assesses recurrence ← DESIGN (docs/adr/0258) - Root candidate: #859 - Where: plugins/os-sdlc/references/escalation-procedure.md - Improvised this session: none - Root candidate: #859 - Session: 55a56279-83ee-47d5-a21e-ee67f9e28abd - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/55a56279-83ee-47d5-a21e-ee67f9e28abd.jsonl Parent: #859 Blocked by: #869, #874, #881

jared added the

plugin/os-sdlc

filed-by/user

labels

2026-10-01 15:26:47 +00:00

jared added a new dependency

2026-10-01 15:29:50 +00:00

#869 Add map-router agent and map-making skill for reroute selection

jared added a new dependency

2026-10-01 15:29:50 +00:00

#874 Document reroute recovery in implement skill and escalation procedure

jared added a new dependency

2026-10-01 15:29:50 +00:00

#881 Accept drafted maps at the reroute gate with bounded validator feedback

jared added the

ready-for-agent

label

2026-10-01 15:30:02 +00:00

jared referenced this issue

2026-10-01 15:30:09 +00:00

no pipeline path for guard/characterization tests (unexpected_pass escalation) #859

jared referenced this issue

2026-10-01 20:25:09 +00:00

no pipeline path for guard/characterization tests (unexpected_pass escalation) #859

jared referenced this issue

2026-10-01 21:21:53 +00:00

Resolve drafted maps from maps/drafts/ through Map::Catalog #880

jared referenced this issue

2026-10-01 21:23:06 +00:00

no pipeline path for guard/characterization tests (unexpected_pass escalation) #859

jared referenced this issue

2026-10-02 16:08:17 +00:00

Rule where drafted maps live (plugin cache is wiped by refresh-plugins) #898

jared commented

2026-10-02 17:28:23 +00:00

Author

Owner

Work started on branch ticket-882 (os-sdlc pipeline, map poodr-ticket-implementation).

jared commented

2026-10-02 17:34:59 +00:00

Author

Owner

Resolution

Done: Documented map drafting and promotion. map-making SKILL.md gains a Draft a map section (drafts root Map.drafts_dir(env), redraft from map-update validator errors, (drafted) label, promotion is a human step). map-router.md: drafts one map when none fits and the misfit will recur; write the file, then map-update, fix and rerun on refusal; description updated. escalation-procedure.md step 4: recurrence decision, promote-map ticket via capture, promotion by mv plus index add per ADR-0264, occurrence comments per ADR-0261 decision 6, change-auditor reroutes never select a draft.

Evidence: Branch ticket-882: 15e15981, 494861a8, d2aaf0e2. Required-work greps: Map.drafts_dir in map-making SKILL.md (1), Map.drafts_dir in map-router.md (1), promote map in escalation-procedure.md (1). Hand-finished: implementation 15 escalated unexpected_pass (prose-only) and was abandoned with reason.

Follow-ups: Dropped: whether os-backlog occurrence accepts a non-recurring promote-map ticket is unverified; ADR-0261 decision 6 prescribes it and the CLI fails loudly if it refuses, so the first real promote ticket settles it.

## Resolution **Done:** Documented map drafting and promotion. map-making SKILL.md gains a Draft a map section (drafts root Map.drafts_dir(env), redraft from map-update validator errors, (drafted) label, promotion is a human step). map-router.md: drafts one map when none fits and the misfit will recur; write the file, then map-update, fix and rerun on refusal; description updated. escalation-procedure.md step 4: recurrence decision, promote-map ticket via capture, promotion by mv plus index add per ADR-0264, occurrence comments per ADR-0261 decision 6, change-auditor reroutes never select a draft. **Evidence:** Branch ticket-882: 15e15981, 494861a8, d2aaf0e2. Required-work greps: Map.drafts_dir in map-making SKILL.md (1), Map.drafts_dir in map-router.md (1), promote map in escalation-procedure.md (1). Hand-finished: implementation 15 escalated unexpected_pass (prose-only) and was abandoned with reason. **Follow-ups:** Dropped: whether os-backlog occurrence accepts a non-recurring promote-map ticket is unverified; ADR-0261 decision 6 prescribes it and the CLI fails loudly if it refuses, so the first real promote ticket settles it.

jared closed this issue

2026-10-02 17:34:59 +00:00

jared referenced this issue

2026-10-02 17:36:01 +00:00

no pipeline path for guard/characterization tests (unexpected_pass escalation) #859

jared referenced this issue from a commit

2026-10-02 17:43:17 +00:00

docs(os-sdlc): #882 document map drafting and promotion (hand-finished)

jared referenced this issue from a commit

2026-10-02 17:43:17 +00:00

docs(os-sdlc): #882 History row

jared referenced this issue from a commit