--- name: ki-work-roadmap ki-kind: governance ki-applicability: declaration-only ki-depends-on: [] ki-shared-modules: [work-identifiers, roadmap-areas] ki-shared-dependencies: [ki-skills:rubric] owns: ['ROADMAP.md'] description: > Govern flat local work items, roadmap horizons, lifecycle detail, dependencies, root orientation, and done-before-prune commit boundaries. Use to audit or shape roadmap records; `ki-next`, `ki-plan`, `ki-implement`, and `ki-accept` apply the lifecycle, while Decision Records own durable rationale. argument-hint: 'audit | conform | help | educate | refresh' --- # Knowledge Islands repository roadmap standard This governance skill owns the shared flat forward-work model. A project repository keeps canonical work items directly under `docs/roadmap/` and one concise root orientation file; a Knowledge Base keeps the same record model directly under `Streams/Roadmap/`, with `ki-repo-kb-streams` owning that container. A repository either issues one repository-wide sequence or declares fixed area namespaces; a work item's `project` or `theme` gives its territory grouping. `ki-next` is the separate process skill that applies this skill's user-confirmed transition rules to select the next work; this governance skill has no process-skill dependency. Read [the repository-roadmap standard](references/standards-repository-roadmaps.md) before changing a roadmap shape or lifecycle. Read [the generated rubric](references/rubric.md) for the mechanical and judgment criteria. Work-item details live in [the work-item-format standard](references/standards-work-item-format.md). Tracked methodology sources and the REFRESH cadence live in [the source list](references/sources.md). A `status: triage` record captures substantive prospective work without adopting it; ideas that do not yet pass the graduation test start as `Idea:` bullets in the owning Project note or theme page, or wait in `_IDEAS.md` when neither owns them. The `ki-next` process skill owns capture, human-approved adoption, and later selection transitions. ## Shared model `ROADMAP.md` is a project-repository orientation: it points to `docs/roadmap/` and deliberately repeats no queue information. Each canonical item is a single file at `docs/roadmap/--.md` or `Streams/Roadmap/--.md`; where fixed issuing areas are declared, the identifier includes its immutable area code. The matching `_ISSUES.md` ledger remains in the same directory, so an issued number is never reused after pruning. The item’s `project`, `initiative`, and `component` fields group related work for reporting; the `horizon` field establishes queue position; and `status` records the common `draft` → `ready` → `in-progress` → `awaiting-review` → `done` delivery lifecycle. Triage is captured but unadopted: open intake is draft, while a human-approved rejected, duplicate, or merged disposition may close directly as retained Triage / done without fabricated delivery evidence. A concise adopted item becomes an execution plan by gaining task-list plan sections in the same file: new work starts `- [ ]`, and completed work becomes `- [x]`. The `ki-repo` table declares the stable uppercase `repo_code`; the roadmap table optionally declares fixed issuing areas as a map from code to title. The globally unique identifier is also used by dependencies. Records may carry an optional [`target` mapping](references/standards-work-item-format.md#target-dates) with date, due-or-milestone kind and outcome; it orders only within one horizon and priority. Project references must resolve in an available registry. UNATTENDED-FIELD remains undecided and adds no field. ## Operating modes Carries the universal **AUDIT · CONFORM · EDUCATE · REFRESH** modes. Invoked as `help` / `-h` / `?`, it emits generated HELP and stops. With no recognised mode, it emits the same HELP and, only in an interactive session, offers the mode choice and prompts for the target shown in `argument-hint`. ### Mode AUDIT Run `ki repo audit --skill ki-work-roadmap --repo ` for a project repository. The catalogue applies the mechanical criteria in [the generated rubric](references/rubric.md): concise root orientation; configured theme vocabulary; work-item placement, frontmatter, identity, theme grouping, lifecycle, and dependency integrity. A Knowledge Base uses `ki-repo-kb-streams` for container audit while its `Streams/Roadmap/` records follow this shared model. Then apply the rubric's judgment criteria by reading: item quality, horizon placement and transition readiness, stage-appropriate detail, final topic-oriented Discussion, honest lifecycle state, and coherent classification (`kind`, `purpose`, `project` or `theme`, `component`). Where declared `ki-trades` records exist, identify inbound submissions that need receiver review, outbound records with observable receiver progress that may warrant local follow-up, trade-aware hold conditions, and completion-observation references that prevent pruning a done item. Report structural or proposed local roadmap action only: never set a trade disposition, infer adoption or acceptance, move or prune a record, prioritize work, or edit another repository's state. Iterate until mechanical findings are clean and judgment findings are resolved. After changing the catalogue or contexts, run their colocated Bun tests for item identity, frontmatter, horizon, dependency, root orientation, KB, and safe-draft fixtures. ### Mode CONFORM Run `ki repo conform --skill ki-work-roadmap --repo --dry-run` to inspect the proposal. In a valid repository, CONFORM repairs the concise root orientation and scaffolds a missing `docs/roadmap/_ISSUES.md` ledger from the highest retained issue number. It never overwrites a malformed ledger, invents work items, moves horizons, removes or rewrites authored prose, reallocates identifiers, or changes lifecycle content. Re-run AUDIT afterward. ### Mode EDUCATE Run `ki repo educate --skill ki-work-roadmap --repo ` to render the catalogue's concern and families. To establish a new non-KB repository, scaffold the root orientation only when `ROADMAP.md` and `docs/roadmap/` are both absent. In a KB, use the `ki-repo-kb-streams` skill and create no repository-roadmap artifact. ### Mode REFRESH **Precondition:** REFRESH writes only the canonical skill files in `ki-agentic-harness`. If invoked from an installed copy, stop and redirect to that harness; route recurring base-specific pressure through the `ki-repo-kb` IMPROVE mode. On the cadence in [the source list](references/sources.md), compare actual repository-roadmap usage with [the repository-roadmap standard](references/standards-repository-roadmaps.md), [the work-item-format standard](references/standards-work-item-format.md), and [the generated rubric](references/rubric.md). Revisit the horizon model, item identity, theme grouping, CLI reporting, and execution quality bar. Update the source review dates and explain normative changes in the commit. ## Notes - Not every change needs a plan. A focused single-file or one-step fix can execute directly. - Exploration needs no plan; multi-file or multi-step implementation enriches its item before execution. - A plan answers “how”; a Decision Record answers “why”. Use `ki-decision-records` for the latter. - The `ki-next` process skill selects and promotes work through the readiness contract defined here. - The `ki-plan` process skill shapes an immediate draft through Ready. - `ki-implement` owns Ready → In progress → Awaiting review; `ki-accept` owns Awaiting review → Done and pruning by explicit work-record path or glob. - Lifecycle transitions may share a coherent planning, implementation, or closure commit; only pruning requires its own later commit after the `done` record has landed. - `ki-recap` and `ki-next` may recommend pruning; they never delete canonical work-item records. - The local `scripts/shared/rubric.ts` is the materialised compile-time contract from `ki-skills`; generic execution, findings, progress, transaction safety, rollback, and reporting belong to `ki`.