mirror of
https://github.com/mvschwarz/openrig.git
synced 2026-11-07 05:56:21 -10:00
docs(reference): refresh the process guides against main (#785)
Four process guides re-verified against main for 0.6.6. Text only.
- sdlc-conventions: wave composition reads mission.yaml arrangement.waves, with the wave-map queue row only as the fallback when mission.yaml is missing or malformed; slice.yaml execution.depends_on takes precedence; the audit is rig scope audit --mission and exits 1 only on high-severity structural findings; the proof-lock does not fire a freeze; plan-lock --locked-artifacts and --re-approve described; scaffold outputs updated; stale section references fixed.
- product-journey-sdlc: selections carry explicit edges, some file must name the catalog, references resolve from the Git root of the repository holding the catalog YAML, and rig workflow guidance reads the effective selection.
- product-management-pass and release-boundary: the slice-create --intent flag and where the capability delta lives and expires.
Commands and flags checked against the help inventory of a clean build of a350c59b.
This commit is contained in:
1 parent
6ce7ec2089
commit
3db2b16741
4 files changed
+58
-35
No files matched your search
@@ -1,8 +1,8 @@
|
||||
# Product-journey SDLC components
|
||||
|
||||
This is a reusable menu for building the smallest complete user outcome. A
|
||||
mission or slice selects only the components its work needs and records their
|
||||
order in mission/slice YAML. This is **not a mode, pipeline, topology, rig
|
||||
mission or slice selects only the components its work needs and records them,
|
||||
with any explicit edges between them, in mission/slice YAML. This is **not a mode, pipeline, topology, rig
|
||||
shape, or mandatory gate set**. If no composition is present, use the light
|
||||
Part A flow in `sdlc-conventions.md`.
|
||||
|
||||
@@ -215,7 +215,8 @@ possible explanation.
|
||||
## Composition rules
|
||||
|
||||
1. `project.yaml` may declare project defaults; `mission.yaml` may select the
|
||||
catalog and override those defaults for the mission.
|
||||
catalog and override those defaults for the mission. Some file in that chain
|
||||
must name the catalog: there is no default catalog.
|
||||
2. `slice.yaml` selects or overrides the components for that slice.
|
||||
3. Edges are explicit data. Array order is presentation, not dependency.
|
||||
4. Select the fewest components that honestly fit the work.
|
||||
@@ -305,15 +306,19 @@ On a fresh start, restore, or new assignment:
|
||||
Do not choose a mission from an old onboarding packet or a folder's recency.
|
||||
3. Resolve SDLC selection in order: project defaults, mission defaults, then the
|
||||
active slice's explicit selection/override. A narrower explicit selection
|
||||
replaces the broader component list; it does not append every ancestor's
|
||||
gates. Follow an addressed wave map for its membership, review model and
|
||||
replaces the broader component list and its edges; it does not append every
|
||||
ancestor's gates. Follow an addressed wave map for its membership, review model and
|
||||
boundary; an explicit named-slice exception applies only to that slice.
|
||||
4. Read only the selected components and additional addressed context. Repository
|
||||
references resolve from the code repository root; installed references from
|
||||
references resolve from the Git root of the repository that holds the YAML
|
||||
declaring the catalog, which may not be the code checkout; installed references from
|
||||
`$OPENRIG_HOME/reference`; context-pack refs use `rig context get`. For a
|
||||
Markdown `#section` address, use `loading-addressable-markdown` rather than
|
||||
loading an entire unrelated manual. Expand the investigation when the task's
|
||||
evidence requires it: the address map is a starting point, not a search limit.
|
||||
For work running as a workflow instance, `rig workflow guidance <instance>`
|
||||
reads the effective selection, the selected catalog sections and the original
|
||||
intent; add `--component <id>` or `--full` to expand.
|
||||
5. State briefly the user outcome, current role, candidate, selected path and
|
||||
next completion boundary. No composition means the light Part A flow in
|
||||
`sdlc-conventions.md#a1-the-flow-in-one-pass`. Do not author a
|
||||
|
||||
@@ -31,7 +31,9 @@ measuring stick:
|
||||
3. **PRESENT DECISIONS DECISION-READY.** One at a time, lettered, recommendation
|
||||
first, records cited. The owner's ruling gates everything downstream —
|
||||
mechanically where possible (a blocked-on anchor), never by memory.
|
||||
4. **MINT SLICES AT PLAN TIME** with real one-paragraph intents.
|
||||
4. **MINT SLICES AT PLAN TIME** with real one-paragraph intents
|
||||
(`rig scope slice create <mission> <slug> --intent "..."`; without `--intent`
|
||||
the SPEC.md intent defaults to the title).
|
||||
5. **DEPOSIT THE DESIGN — the fidelity law.** Every design-bearing slice's SPEC.md
|
||||
carries the full design contract INLINE: the owner's words verbatim, the settled
|
||||
do-not-reopen decisions, the live evidence, the shape of done, the anti-goals. A
|
||||
|
||||
@@ -88,7 +88,11 @@ naming that exact delta AND a distinct successor delta file existing. A header a
|
||||
does not expire it; missing or unreadable inputs remain unknown/live. At the actual
|
||||
boundary, verify the event before recording expiry, then stop citing the expired
|
||||
delta. Do not create a successor merely to make the condition true. Candidate
|
||||
absorption is not proof of publication or served production adoption.
|
||||
absorption is not proof of publication or served production adoption. The delta is
|
||||
`CAPABILITY-DELTA-v<version>.md` in the release mission folder (scaffolded by
|
||||
`rig scope mission create release-X.Y.Z`); its `expiry.canon_path` and
|
||||
`expiry.successor_path` name the two inputs, and `rig scope audit --mission <name>`
|
||||
reports `expired_capability_delta` once both hold.
|
||||
|
||||
Private project topology, host practice, and release ownership go to the versioned
|
||||
project world instead of leaking into the public package. The new release's delta
|
||||
@@ -107,8 +111,8 @@ obligations start at ITS cut.
|
||||
packaged result, repairs any missed absorption as explicit debt, absorbs private
|
||||
project truth, re-primes, and observes whether a clean world-installed agent
|
||||
reaches the capability from its situation without being told its name.
|
||||
- A missing route is a release finding. Repair the smallest existing seam or deposit
|
||||
the evidenced gap into the derivable-context mission; do not create a second
|
||||
- A missing route is a release finding. Repair the smallest existing seam or record
|
||||
the evidenced gap as scoped follow-up work in the project; do not create a second
|
||||
capability registry, search service, or world store at the boundary.
|
||||
|
||||
## 8. What deliberately does NOT happen at the boundary
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# SDLC conventions — the markdown control plane
|
||||
|
||||
> **Source of truth:** this repo document is the living SSOT for the SDLC
|
||||
> conventions. Scaffold templates, the advisory scope audit, the
|
||||
> `mission-slice-sop` skill, and the shipped bootstrap overlay all point HERE —
|
||||
> conventions. Scaffold templates, the advisory scope audit and the
|
||||
> `mission-slice-sop` skill all point HERE —
|
||||
> they must not restate this document in full (restatement is how drift is born).
|
||||
|
||||
OpenRig is a software factory the human steers from a high altitude. The human
|
||||
@@ -37,7 +37,7 @@ one does not deprecate the others. Nothing below deletes or overrides an existin
|
||||
| **PRODUCT / MISSION PREPARATION** | **The product-management pass** — the layer above planning, run by the advisor/PM seat before planners touch a mission. The build is a lossy compression pipeline (PM intent → planner spec → builder code); nothing leaks downward by proximity, so this pass grounds in the raw sources, synthesizes ONE scope of record, presents owner decisions decision-ready, mints slices at plan time, deposits the full design contract INLINE in each design-bearing spec (owner words verbatim, settled decisions, evidence, shape of done, anti-goals), routes the complete reading list and internet-research assignments from the spec itself, frames each slice's planning-dial rung with its reason, and rereads every spec as the narrow downstream reader. The measuring stick: SPEC.md alone, plus what it explicitly routes to, reproduces the intent in a reader with none of the author's context. Full reference: `product-management-pass.md`. |
|
||||
| **PLAN** | **The planning dial** — planning rigor is a spectrum chosen per piece: P0 mini-requirements and pointers (simple, reversible work) · P1 an authored spec with a proof contract (the default) · P2 plus a research round before the spec freezes, run BEFORE build dispatch · P3 plus an adversarial pass by a non-author, judged against product goals, landing amendments with proof-contract teeth · P4 plus a blind from-scratch design diffed against priors before proceeding. Dial up by what the piece is, exactly as build care is priced below. Full reference: `planning-dial.md`. |
|
||||
| **BUILD** | **Part A, the simple flow** (below — the default) · **product-journey components** — a mission-selectable menu for greenfield work, drift recovery, public journey probes, one evidence-gated look at the layer below, minimal repair, independent QA/review, integration, and installed smoke; compose only what the work needs in mission/slice YAML, never as a new mode or mandatory pipeline. Full reference: `product-journey-sdlc.md` · **the wave model** — slices build in parallel in disjoint file territories, an integrator merges serially, and independent review fires once per wave (two reviewers with different vantages, never the writers; fix rounds re-earn verdicts at one final revision; per-slice discipline stays failing-test-first and verify-by-effect). The wave IS the care dial: what shares a wave decides how much review each piece gets · **Part B, the rigorous overlay** (below — only when assigned). These combine: a wave can carry one Part-B piece. Full wave reference: `wave-sdlc.md`. |
|
||||
| **DISPATCH DATA** | **The execution-data conventions (S27)** — three tiny data disciplines that make execution state derivable instead of hand-tabulated, consumed by `rig view show execution`. **EC-1, edges in frontmatter:** every open slice carries its hard edges in `depends_on:` (an inline JSON array; an explicit `[]` is a statement, absence is INDETERMINATE); soft/serialization edges are one machine-readable Territory line, exactly `SOFT-AFTER: [ids] — reason`. **EC-2, wave-as-data:** wave composition + review model live on a durable queue row tagged `wave-map` + `format:wave-map-v1` whose body carries one fenced ```json block (`{format:"wave-map-v1", mission, waves:[{id, slices, serialized_order?, review_model?}]}`) — composition only, never status labels (status derives at read time); the planning dial recorded at lock surfaces as the frontmatter field `approved-spec-dial:` beside the approve stamp. **EC-3, dispatch names the worktree:** build batons carry the exact body line `worktree_path=<path>` from dispatch onward — it is Q1's join key; batons without it join by naming only and the view marks them `fragile_join`. Existing batons are never rewritten. |
|
||||
| **DISPATCH DATA** | **The execution-data conventions (S27)** — three tiny data disciplines that make execution state derivable instead of hand-tabulated, consumed by `rig view show execution`. **EC-1, edges in frontmatter:** every open slice carries its hard edges in `depends_on:` (an inline JSON array; an explicit `[]` is a statement, absence is INDETERMINATE; when the slice's `slice.yaml` carries `execution.depends_on`, that list takes precedence); soft/serialization edges are one machine-readable Territory line, exactly `SOFT-AFTER: [ids] — reason`. **EC-2, wave-as-data:** wave composition + review model live in `mission.yaml` `arrangement.waves` (`{id, slices, review_model?}`; a slice may also name its wave in `slice.yaml` `execution.wave`). Only when the mission has no `mission.yaml`, or it is malformed, does the view fall back to the legacy form: the newest queue row tagged `format:wave-map-v1` and `mission:<mission>` whose body carries one fenced ```json block (`{format:"wave-map-v1", mission, waves:[{id, slices, serialized_order?, review_model?}]}`) — composition only, never status labels (status derives at read time); the planning dial recorded at lock surfaces as the frontmatter field `approved-spec-dial:` beside the approve stamp. **EC-3, dispatch names the worktree:** build batons carry the exact body line `worktree_path=<path>` from dispatch onward — it is Q1's join key; batons without it join by naming only and the view marks them `fragile_join`. Existing batons are never rewritten. |
|
||||
| **RELEASE** | The release ceremony conventions (publication identity, honest release notes) and the CAPABILITY-DELTA LIFECYCLE LAW: each release's delta is authored at the fence and bound to the exact candidate, then reconciled to the published cut. Expiry requires both the canon header naming the absorbed delta and a distinct successor delta existing; a draft header alone is insufficient. Verify the actual boundary event and stop citing an expired delta. Full statement: `release-boundary.md` §6. |
|
||||
| **BOUNDARY** | **The release boundary** — housekeeping run once per fence so the next release starts clean: seats reset or re-primed per their continuity needs, memory distilled (keep what changed a decision recently), every queue swept by destination and dispositioned, substrate torn down, boards frozen as records, a clean-box baseline captured. A checklist of judgment guides, not gates. Full reference: `release-boundary.md`. |
|
||||
|
||||
@@ -46,7 +46,7 @@ one does not deprecate the others. Nothing below deletes or overrides an existin
|
||||
> planning dial — `planning-dial.md` · the product-journey component catalog —
|
||||
> `product-journey-sdlc.md` · the wave model — `wave-sdlc.md` · the release
|
||||
> boundary (including the capability-delta lifecycle law) — `release-boundary.md` ·
|
||||
> the mission install — `mission-install.md` (lands with its own slice). The
|
||||
> the mission install — `mission-install.md`. The
|
||||
> summaries above remain the one-glance description; this document remains the SSOT
|
||||
> pointer for the whole menu.
|
||||
|
||||
@@ -99,17 +99,17 @@ Each slice directory carries:
|
||||
(numbered list). This is the human operator's first structured catchpoint;
|
||||
approval starts here.
|
||||
- **`## Proof contract`** — a checkbox list of promised deliverables (see
|
||||
§3). The UI's DELIVERED section pairs each item with its proof.
|
||||
B1). The UI's DELIVERED section pairs each item with its proof.
|
||||
- **`PROGRESS.md`** — the slice's current delivery state and retained outcome
|
||||
log. Record material changes with links to proof; historical checkboxes are
|
||||
testimony, not current acceptance authority. For a selected proof policy,
|
||||
`rig proof show <slice>` derives current readiness from the proof contract
|
||||
`rig proof show <mission>/slices/<slice>` derives current readiness from the proof contract
|
||||
and attributed judgments. In-process steps stay in the working agent's
|
||||
own todo tool.
|
||||
- **`PROOF.md`** — the retained proof summary, explicitly paired to the
|
||||
`SPEC.md` proof contract.
|
||||
- **`proof/`** — the proof-artifact directory. Curated canonical evidence
|
||||
lands here via `rig proof` with valid C1 headers (§5).
|
||||
lands here via `rig proof` with valid C1 headers (B3).
|
||||
|
||||
Legacy `README.md`, `IMPLEMENTATION-PRD.md`, and pre-convention trees remain
|
||||
readable indefinitely. New scaffolds do not create or mirror them, and repair
|
||||
@@ -128,7 +128,9 @@ Part B or add a mandatory review gate.
|
||||
|
||||
The three sections project into the UI's one review structure: a vertical
|
||||
stack of **INTENT → PLAN → DELIVERED**. A slice missing a section still
|
||||
renders (the projection degrades to a muted "—", never invents content) —
|
||||
renders (a missing Intent or Delivered source shows a muted "—", missing
|
||||
mini-requirements show "Not compliant · mini-requirements not authored";
|
||||
nothing is invented) —
|
||||
but it does not carry its weight in review.
|
||||
|
||||
## A3. Honesty rails (public surfaces + cited hashes)
|
||||
@@ -209,24 +211,29 @@ are losslessness checks on the decompression from intent to delivery, not
|
||||
paperwork. Scaffolding emits the sections; it must never mint ceremony.
|
||||
## A6. The audit (advisory, fail-open — always)
|
||||
|
||||
`rig scope audit` (and the advisory rows in `rig workspace validate` /
|
||||
`doctor`) checks these conventions: the section headings present, the proof
|
||||
contract well-formed, `proof/` artifacts carrying valid C1 headers, UI slices
|
||||
referencing a mockup. Every finding **records and advises — it never blocks a
|
||||
write path and never changes exit semantics into a gate**. Unknown is
|
||||
`rig scope audit --mission <name>` (and the advisory `sdlc_convention_sections`
|
||||
row in `rig workspace doctor`) checks these conventions: the section headings
|
||||
present, the proof contract well-formed, `proof/` artifacts carrying valid C1
|
||||
headers, UI slices referencing a mockup. Every convention finding is low or
|
||||
info severity: it **records and advises — it never blocks a write path and
|
||||
never changes the exit code**. (`rig scope audit` exits 1 only on high-severity
|
||||
structural findings, such as a missing `PROGRESS.md` or id.) Unknown is
|
||||
reported as unknown, not failure.
|
||||
## A7. Where the knowledge lives (the four pointers)
|
||||
|
||||
- **This document** — the SSOT.
|
||||
- **Scaffold**: `rig scope slice create` emits `SPEC.md` + `PROGRESS.md` +
|
||||
`PROOF.md` + `proof/` for every template kind; `rig scope mission create`
|
||||
emits an intent-bearing `SPEC.md` + `NOTES.md`. Core emits only this
|
||||
- **Scaffold**: `rig scope slice create` emits `SPEC.md` + `slice.yaml` +
|
||||
`PROGRESS.md` + `PROOF.md` + `proof/` for every template kind (and registers
|
||||
the slice in `mission.yaml`); `rig scope mission create` emits an
|
||||
intent-bearing `SPEC.md` + `mission.yaml` + `PROGRESS.md` + `NOTES.md` +
|
||||
`slices/` (plus `CAPABILITY-DELTA-v<version>.md` for a `release-X.Y.Z`
|
||||
mission). Core emits only this
|
||||
mode-neutral shape; mode plugins add richer material through the extension
|
||||
seam rather than teaching core a mode.
|
||||
- **Skill**: `mission-slice-sop` teaches **Part A**, the light default. **Part B**
|
||||
is defined below and applies only when assigned — never self-selected.
|
||||
- **Bootstrap**: the shipped agent overlay points fresh seats at the skill
|
||||
and this document at boot.
|
||||
- **Bootstrap**: the shipped pm-team rig culture points its seats at the skill
|
||||
and this document; the generic `openrig-start.md` overlay no longer does.
|
||||
|
||||
# PART B — THE RIGOROUS OVERLAY (assigned only)
|
||||
|
||||
@@ -266,7 +273,8 @@ deliverable, written as an observable outcome:
|
||||
that evidence it — that pairing is what the DELIVERED section renders, so
|
||||
the human never hunts through dozens of artifacts to find which one proves
|
||||
what.
|
||||
- **UI deliverables carry a planned mockup** (`plannedRef`): the planning
|
||||
- **UI deliverables carry a planned mockup** (`plannedRef`, written as an
|
||||
inline image on the checkbox line, e.g. `- [ ] … `): the planning
|
||||
agent produces the mockup and attaches it to the locked set. A UI slice
|
||||
with no mockup in its locked set is an incomplete plan. Non-UI slices
|
||||
(backend, skills, markdown) have no mockup and no `plannedRef` — that is
|
||||
@@ -283,14 +291,18 @@ append-only audit row land together):
|
||||
- **Plan-lock:** `rig scope slice approve <slice> --scope spec` — "the spec
|
||||
matches my intent; THIS artifact set is what gets built." Pins `SPEC.md`
|
||||
(and planned mockups, when present) out of everything else in the folder.
|
||||
`--locked-artifacts "SPEC.md,…"` names the set explicitly instead; a
|
||||
plan-lock on an unedited scaffold `SPEC.md` with nothing else to pin refuses.
|
||||
- **Proof-lock:** `rig scope slice approve <slice> --scope delivery`
|
||||
(the default scope) — the terminal "this is done" sign-off; fires the
|
||||
freeze.
|
||||
(the default scope) — the terminal "this is done" sign-off. (It does not
|
||||
render the frozen export; the approve result reports `freezeFired: false`.)
|
||||
|
||||
Approval is freeze/sign-off — **never** proven-green. Proven-green requires a
|
||||
recorded verdict (a C1 proof artifact, §5); presence of an approval stamp does
|
||||
recorded verdict (a C1 proof artifact, B3); presence of an approval stamp does
|
||||
not assert the work was proven. `--on-behalf-of` records delegation honestly
|
||||
(the actor stays the real invoking session).
|
||||
(the actor stays the real invoking session). A second approve of the same
|
||||
scope refuses; `--re-approve --reason "<why>"` supersedes the stamp and keeps
|
||||
the prior one in the audit log.
|
||||
|
||||
## B3. Proof drops and the C1 header (closed sets)
|
||||
|
||||
@@ -323,9 +335,9 @@ that it LOOKED at the evidence. `--media` names the curated media files
|
||||
(relative to the slice's `proof/` dir — co-located, never absolute) this
|
||||
drop stands behind; the composer projects them into the DELIVERED items'
|
||||
proof set. Validation happens at drop time; the audit
|
||||
(§6) backstops artifacts that arrived by other paths. **Hand-placing files
|
||||
(A6) backstops artifacts that arrived by other paths. **Hand-placing files
|
||||
in `proof/` without a drop is the anti-pattern**: the deliverable stays
|
||||
unpaired and `unverified` in the DELIVERED view — always attach media via
|
||||
unpaired and shows as `missing` in the DELIVERED view — always attach media via
|
||||
`--media` on a drop.
|
||||
|
||||
## B4. Role contracts (what makes the structure self-enforcing)
|
||||
|
||||
Reference in new issue
Block a user