devrites 7.1.2 → 7.2.0

package/pack/generated/dsh/skills/rite-plan/reference/replan-and-repair.md

@@ -0,0 +1,114 @@
+# Re-plan & repair modes
+
+`/rite-plan` runs in one of these modes. Pick from `$ARGUMENTS` or infer from state.
+
+Authority: `.dsh/skills/devrites-lib/reference/standards/acceptance-preserving-reslice.md`.
+
+<!-- BEGIN RESLICE ROUTE-TO-ACTION -->
+- `FOLD` → reconcile `architecture.md`, `plan.md`, `tasks.md`, and `traceability.md` atomically; invalidate Vet/readiness; Vet.
+- `GUARD_AND_REPAIR` → no planning writes; Spec Drift Guard → Clarify → Plan repair → Vet.
+- `BLOCKED_INPUT` → no planning writes; exact diagnostic; recover input; reclassify.
+<!-- END RESLICE ROUTE-TO-ACTION -->
+
+## decompose
+
+First (or fresh) breakdown into vertical slices. Use `task-breakdown.md` +
+`slicing.md`. Output: a populated `tasks.md` and an ordered `plan.md` graph.
+
+## reslice
+
+A slice proved too large (couldn't build+prove in one cycle, or its goal has multiple
+"and"s). Split into thinner end-to-end slices, preserving acceptance coverage: split
+**by the sizing rule, not to a target count**. Update `tasks.md` under the canonical
+[ID contract](../../devrites-lib/reference/workspace-artifact-schema.md#id-contract):
+preserve unaffected IDs; never renumber or fill retired gaps. New meanings get the
+next unused IDs; record relationships in `decisions.md` or `drift.md` before updating
+downstream dependency edges and traceability.
+
+## repair (after Spec Drift Guard)
+
+A drift event stopped the build. Steps:
+
+1. Read the `drift.md` entries and their classifications. Fold EVERY open entry
+   and accepted finding for the affected artifacts in ONE pass, never serially.
+2. If the user answered a drift question, encode that decision in `decisions.md`.
+   Fold each `decisions.md` carry-forward constraint into `Prior-slice learnings`
+   of the remaining slices it affects.
+3. Update `spec.md` (only the affected sections) and `plan.md`/`tasks.md` to match
+   reality. Fix acceptance wording only when its meaning stays the same. An
+   acceptance meaning change needs a user directive or a recorded user decision
+   ([provenance](../../devrites-lib/reference/standards/acceptance-preserving-reslice.md));
+   without one, ask with a recommended option. **Failing case:** root rewords an
+   AC so a bound may be exceeded, records its own decision, and sends it to Vet.
+   **Write the pointer, not the history.** Name the findings a fold closes by ID, one line
+   of meaning each; never restate prior folds, prior DEC lists, or closed-round narrative in
+   `architecture.md`/`plan.md`/`tasks.md`/`traceability.md`. That text belongs in
+   `decisions.md`, or in `history/` via [Budget relocation](#revise) once closed, so each
+   fold appends a bounded line. A banner that grows with the round count is the defect.
+4. Mark each `drift.md` entry **resolved** with the resolution + date.
+5. **Self-check and self-attack the repaired candidate on the delta before
+   handoff** — re-verify every invariant the correction touched (acyclic
+   dependency graph, bidirectional traceability, Shared contract proof vs
+   boundary set, sizing, no correction-created regression), then probe the
+   delta against the reviewers' attack classes (race/observation windows,
+   alias escapes, ordering gaps, capability gaps, unbounded blocking,
+   happy-path-only coverage); fold a fix or a named bounded residual into
+   the same pass. Record both in the Plan
+   checkpoint; Vet's recheck verifies it rather than rediscovering the defect a
+   loop later.
+6. Resume at the corrected slice.
+Never quietly delete a requirement; use the marked action before contract edits.
+
+## reorder
+
+Dependency order is wrong or suboptimal. Recompute the graph (`dependency-graph.md`),
+re-sort risk-first within tiers, update `plan.md`'s implementation order.
+
+## split (backend/frontend contract)
+
+A slice couples two sides too tightly. Define the contract first (shape, status codes,
+errors: `devrites-api-interface`), then split into a backend slice (can land with a
+stub consumer) and a frontend slice (can land against a mock/real contract).
+
+## unblock
+
+An exhausted fingerprint blocks diagnosis, not symptom. Route around/reslice; escalate
+only for scope change. If proof removed that cause but symptom remains, keep the dead
+end and plan a new diagnosis/proof fingerprint. Never clear/reuse old one.
+
+## course-correct
+
+Mid-build user pivot. Apply the marked action, choose rollback or forward-fix, and
+update permitted artifacts atomically (`MVP cut` is the named retreat). Invalidate
+Vet/readiness when contract or topology changes.
+
+**Feature-ceiling cut.** When unbuilt slices exceed the
+[feature ceiling](slicing.md#feature-ceiling-split-an-epic-never-override-the-budget),
+`MVP cut` keeps the built slices plus the thinnest shippable unbuilt subset here; the
+remaining slices, their REQ/AC IDs and proof rows move verbatim into a named
+continuation list (spec `Non-goals` → future `/rite-spec <slug>-2`, `-3`, …) through
+the Spec Drift Guard. IDs never renumber; each ID is owned by exactly one workspace.
+Record the sequence once in `decisions.md`.
+
+## revise
+
+Artifact-only reconciliation of `spec.md`, `architecture.md`, `plan.md`, `tasks.md`,
+or `traceability.md` — never source. Propose/confirm the file set first. A neutral workspace
+edit is authorized by explicit `/rite-upgrade` with a `repairable` assessment, or, for budget
+relocation only, by the phase owner when `orient` reports `over: true`.
+
+Unchanged acceptance/behavior with non-equivalent `proposed_coverage` is a
+contradictory input: the canonical classifier blocks it — there is no fourth
+route (see [`acceptance-preserving-reslice.md`](../../devrites-lib/reference/standards/acceptance-preserving-reslice.md)).
+
+**Budget relocation** (authorized as above): move checkpoint narrative, historical fold text and
+closed-round accounts verbatim from `state.md`/`tasks.md`/`plan.md`/`architecture.md`/
+`eng-review.md` into `history/<file>-<YYYYMMDD>.md`, packets/accounts from the root
+into `packets/`, leaving a one-line pointer. Cursor, live slices, open findings, IDs,
+answers, decisions and bindings stay unchanged; nothing is deleted or reworded.
+Re-emit the readiness binding when a readiness input moved.
+
+## Always
+
+Update `state.md` (phase, next step) and append a dated line to `decisions.md`
+explaining *why* the plan changed. Preserve mapped-action decisions.

package/pack/generated/dsh/skills/rite-plan/reference/slicing.md

@@ -0,0 +1,187 @@
+# Slicing
+
+DevRites builds in **thin vertical slices**: each slice cuts through every layer it
+needs (data → logic → API → UI) and leaves the system in a working, testable state.
+
+## Vertical, not horizontal
+Horizontal layering delays integration feedback. Vertical slicing delivers a usable path:
+```
+SLICE-001: Create a task   (DB + API + minimal UI)   -> user can create + test passes
+SLICE-002: List tasks      (query + API + UI)         -> user can see them
+SLICE-003: Edit a task     (update + API + UI)        -> user can modify
+SLICE-004: Delete a task   (delete + API + UI + confirm) -> full CRUD
+```
+
+## Sizing a slice
+A slice is the right size when it:
+- delivers one observable capability end-to-end;
+- can finish its writer, independent review, and slice proof within `/rite-build`;
+- has acceptance criteria you can verify with evidence;
+- can be rolled back on its own;
+- is worth its own review gate: a reviewer could meaningfully reject *this* slice while
+  approving its neighbor. If two slices can only pass or fail together, they're one slice.
+
+Size by independent invariants, failure modes, and proof seams, not file count or
+the word "and". Split independently acceptable/provable responsibilities; several
+files may serve one inseparable capability. Full feature `/rite-prove` follows all
+slices; slice proof never replaces final integration or acceptance proof.
+
+For `Complexity` and irreducible boundaries, use the canonical
+[`tasks.md` slice grammar](../../devrites-lib/reference/workspace-artifact-schema.md#canonical-slice-grammar).
+Keep the smallest cut that stands alone end-to-end; do not add slices or gates for
+fragments that can only pass together. No slice size guarantees first-pass correctness.
+
+## How many slices?: derive, don't dictate
+The slice **count is an output, not an input.** It falls out of the work: one slice per
+independently-shippable vertical increment that satisfies one (or a tight group of)
+acceptance criteria and passes the sizing test above. A 2-criterion feature is 1-2 slices;
+a 12-criterion feature is however many thin end-to-end cuts those 12 need.
+
+- **Never slice to a target number.** Don't pad a small feature into "5 slices" or
+  compress a large one into "3" because a figure was named.
+- **A user-supplied count is a hint at most.** If the user says "do it in 4", slice the
+  work logically first; if your honest decomposition differs, present the logical count
+  and *why*, then let them redirect: don't silently force their number.
+- **Re-size by the rule, not the tally** (`/rite-plan reslice`): split a slice because it
+  failed the sizing test, not to hit a count.
+
+`.devrites/AFK` `max_slices` limits unattended execution, never plan decomposition.
+
+## Feature ceiling: split an epic, never override the budget
+
+The derived count is also a size signal. A decomposition that cannot fit the
+`tasks.md` / `plan.md` / `traceability.md` budgets in
+[`workspace-artifact-schema.md`](../../devrites-lib/reference/workspace-artifact-schema.md)
+(about ten canonical slices) is an epic: every Vet/Doubt/Build review re-reads the
+whole surface, each round finds new material, and the loop never converges.
+`Budget override` never covers slice or acceptance-criteria count.
+
+- Keep the thinnest independently shippable subset here; the rest becomes spec
+  `Non-goals` (via the Spec Drift Guard), each continuation a named future `/rite-spec`
+  workspace. Record the sequence once in `decisions.md`.
+- Acceptance-preserving: every REQ/AC keeps its ID, owned by exactly one workspace.
+- Earliest owner wins: Temper's one-sentence test → Define/Plan decomposition → Vet §0
+  scope finding → `/rite-plan course-correct` (`MVP cut`). Mid-build, unbuilt slices
+  beyond the ceiling move; built slices stay.
+- The ceiling bounds one **workspace**, never the product: the sequence delivers every
+  slice, in order, each with its own Vet/Build/Review loop. A human may still accept a
+  single larger workspace by recording the decision in `decisions.md` and a bounded
+  `Budget override: <=N lines; <reason>` (N at most 2x the budget; past that only
+  relocation to history/ or a split) in the affected artifacts; the extra review rounds on the whole
+  surface are then the accepted, named cost. The deterministic gate
+  (`check readiness`/`check seal`) blocks only a material overshoot without such an
+  override, so the choice stays explicit rather than accidental.
+
+### Continuation workspaces
+
+Granularity is a real cost choice, not a formality: a workspace costs ~8–12 fixed
+dispatches (drafter, plan reviewer, proof runner, spec/code reviewers, seal roster;
+Temper is skippable when the parent's `strategy.md` already covers the scope) plus
+~3–5 per slice. The split does not remove per-slice cost; it bounds each round's
+context, stops the non-convergent whole-surface loop, isolates a plan defect's blast
+radius to its own workspace, and lets independent continuations run in parallel.
+
+Make each continuation cheap and drift-free:
+
+- `brief.md` names the parent slug and the sequence position; `decisions.md` holds the
+  sequence once (in the parent).
+- The child's `state.md` seeds the durable cursor at creation — `sequence_parent` =
+  parent slug, `sequence_position` = parent position + 1,
+  `sequence_workspaces_remaining` = parent remaining − 1, and `sequence_role:
+  release` only when the recorded entry is the sequence's release milestone.
+  Values derive from the parent's `state.md` and its `decisions.md` record,
+  exactly once; resume re-derives the same values rather than charging again.
+  A workspace that is not a recorded continuation leaves all four rows absent.
+  This is what `state merge-manifest` walks and what the release-union gate reads,
+  so a manually opened continuation needs the same seeding as an armed run.
+- Read the parent's `architecture.md`, `plan.md`, `decisions.md` (or its archived copy)
+  as **design input** — never re-derive settled architecture, dependency choices, or
+  interfaces. Proof is always fresh for the new candidate; parent evidence is cited as
+  input, never as proof for this workspace.
+- Shared interfaces, data shapes, and contracts are pinned **once**, in the workspace
+  that introduces them, and referenced afterwards. A continuation that must change a
+  pinned contract does so through its own `plan.md` shared-contract proof and an ADR
+  that names the superseded owner — never by silently re-deciding it.
+- A request that names a recorded continuation is a new workspace, not
+  `/rite-plan revise` on the parent.
+- Phases chain automatically only **inside** one workspace (`/rite-autocomplete`
+  drives spec → clarify → temper → define → vet → build × slices → prove → polish →
+  review → seal; plain HITL chains plan↔vet inline and stops at each other boundary).
+  HITL: next continuation is a new invocation. Autocomplete chains it
+  (Deferred-ship) unless `continue_sequence: false`.
+
+### Release milestone (full-picture gate)
+
+Milestone gates are feature-scoped: `prove` proves *that* workspace's acceptance,
+`review`/`seal` judge *that* candidate. A product release therefore needs one more
+workspace — the **release milestone** — planned last, whose subject is the assembled
+product:
+
+- Its ACs are product-level: cross-milestone integration, end-to-end journeys,
+  performance/release budgets, docs/rollout. Milestone ACs stay owned by their
+  milestones and are **referenced** here, never re-owned.
+- Its candidate manifest lists the union of shipped surfaces, so one `prove` → `review`
+  → `seal` binds the whole product, and one `ship` commits/pushes/tags the release.
+  Its `state.md` cursor carries `sequence_role: release` (seeded when the recorded
+  continuation is the sequence's release entry); `check candidate`/`check seal`
+  then require the manifest to cover the whole recorded chain. Build that union
+  deterministically: `devrites-engine state merge-manifest <release-slug>` walks
+  the recorded `sequence_parent` chain (live `work/` first, then `archive/`) and
+  folds every predecessor's manifest into the release `## Candidate manifest`;
+  on a path collision the later sequence position's row wins. An explicit
+  ordered `<pred>...` argument exists for chains recorded before the sequence
+  cursor fields.
+- Earlier milestones keep their own slice-level proof and their own prove/review/seal;
+  that is what stops a late defect from invalidating 170 slices of work. Skipping a
+  milestone's proof is allowed only by recording the decision — the release milestone
+  then carries the full acceptance burden, and that cost is the named trade-off.
+- The capability ledger (`.devrites/specs/<capability>/spec.md`) accumulates the
+  product picture across milestones; Polish folds each milestone's deltas.
+- **Deferred-ship sequence** (autocomplete default; `.devrites/AFK` `max_workspaces: N`):
+  milestones are sealed but not shipped, and the armed run opens the next recorded
+  continuation automatically; local `WIP(<slug>):` checkpoints still land with
+  human summaries (never a slice id),
+  so the tree stays clean. One release ship at the end collapses the sequence's
+  checkpoints into the single release commit, pushes/tags it, and may archive the
+  sealed predecessors. Because no milestone boundary was shipped, later work can touch
+  an earlier milestone's surfaces without an affected-re-proof trigger — so the release
+  milestone re-proves the union acceptance map, and that full re-proof is this mode's
+  named cost. Trade-off against per-milestone ship: no shared-history rollback point
+  per increment, one Git approval at the end.
+- What is full-surface here is the **review**: reviewers see the whole product diff.
+  Re-proof stays targeted — this milestone's product ACs, everything a later milestone
+  touched, and any uncertain closure. Milestone evidence is cited only under
+  [evidence validity](../../devrites-lib/reference/candidate-integrity.md#evidence-validity)
+  with explicit unchanged-input/dependency justification and a link to the original
+  account; a blind re-proof of every milestone AC is a recorded decision, not a default.
+
+## First slice
+Make slice 1 the **thinnest useful end-to-end path**. It flushes out integration and
+convention surprises early, while changes are cheap.
+
+**Risk-first exception.** When the biggest risk is a technical *unknown*: "will this library
+even do X?", "can we hit the latency target?": let slice 1 (or a throwaway spike ahead of it)
+prove that unknown, even if it isn't the thinnest user-facing path. Fail the risky bet first,
+while pivoting is still cheap.
+
+## Slice independence
+Order by dependency, but minimize coupling. A slice that needs three other slices first
+is a smell: look for a thinner cut that stands alone. An edge exists only when this slice
+reads something the other produces: write it as `SLICE-001 (via <interface>)`. If you
+cannot name what crosses, drop the edge; a shallow, wide graph runs in parallel.
+
+Slices sharing a file never build side by side: put a hub file's shared edit
+(registry, command table, test harness) in one seam slice the others depend on.
+`check task-graph` prints the `schedule:`, `ADVISORY hub:` and `ADVISORY chain:` lines.
+A `chain` line means only one slice was ever ready, so the DAG rather than the cap
+serializes: cut a slice that stands alone, or record `Serial rationale: <why>`.
+`check task-graph <slug> --strict` refuses a plan whose shared path carries `ADVISORY hub:`
+writers, so a contended plan must split disjointly instead of widening the cap.
+Never merge slices or drop acceptance to widen it.
+
+## Deferred slice
+A slice with `Satisfies: none` is an optional follow-up: plan-invented hardening or
+owner-moved scope kept with its preserved source and contracts. It carries no acceptance
+(every AC still maps to a required slice), is never dispatched (`check slice` refuses
+it), and never counts toward "all slices built", Prove, or Seal. The owner elects it
+later through a plan change that gives it an AC.

package/pack/generated/dsh/skills/rite-plan/reference/task-breakdown.md

@@ -0,0 +1,50 @@
+# Task breakdown
+
+How to turn a spec into ordered, vertical slices in `tasks.md`.
+
+## Each slice is one task
+
+Use the complete canonical grammar in
+[`workspace-artifact-schema.md`](../../devrites-lib/reference/workspace-artifact-schema.md#canonical-slice-grammar).
+This reference owns decomposition; the shared schema owns field names and meanings.
+
+## Process
+1. List the capabilities the spec promises.
+2. Map each to a vertical slice (thinnest end-to-end cut).
+3. Order by dependency; risk-first within a tier (do the scary slice early while it's
+   cheap to change).
+4. Mark which slices touch UI (→ frontend craft + browser proof), map each to the design
+   brief states, and give each a binary visual acceptance target. Mark which slices cross
+   a module/service boundary (→ `devrites-api-interface`, `devrites-doubt`). For a changed
+   provider/consumer boundary, map the plan's `Shared contract proof` artifact before its
+   provider- and consumer-side asserting tests; both tests consume that same artifact and
+   their slice dependencies preserve the order. Do not duplicate the contract in each slice.
+   For each applicable topology/data/integration row, assign its owner, failure/recovery
+   case, and proof to a slice; preserve deployment/resource ordering from the plan.
+5. Write or update `traceability.md` so every `AC-###` maps to ≥1 `SLICE-###`, a
+   planned proof, evidence status, and likely touched files.
+6. Sanity check: every acceptance criterion in `spec.md` maps to ≥1 slice; no slice has
+   an unowned criterion.
+7. Resolve every foreseeable human-owned checkpoint now. Keep a build-time checkpoint only
+   when it needs evidence unavailable before code or mandatory action-time approval, and say why.
+8. Make every `Tests/proof` entry executable: exact command, working directory, prerequisites,
+   expected signal, and mutable inputs whose provenance evidence must bind. Source the command
+   from `devrites-engine detect commands` output where a slot resolves; an `unresolved` slot
+   means the plan names the concrete command explicitly, never an invented one.
+
+## Keep it honest
+- **Interfaces prevent cross-slice drift.** A slice-wright sees only its own contract; the
+  `Interfaces` line is how it learns the names and types neighboring slices use. A function
+  called `clearLayers()` in slice 3 and `clearFullLayers()` in slice 7 is a planning bug:
+  name shared symbols once, here.
+- Don't pre-write code in the task: describe the outcome, not the implementation.
+- **Read the fields, not the title.** A slice fails Vet (`kind: contract`, Important, field
+  quoted) when its `Goal` or `Done condition` names an activity instead of an observable end
+  state ("implement backend", "add tests", "handle errors", "wire up UI"); when a no-op or
+  wrong diff could meet the `Done condition` ("tests pass", "works correctly"); or when
+  `Tests/proof` names no specific test or assertion ("run the suite"). **Failing case:**
+  `Goal: Implement export backend · Done condition: tests pass · Tests/proof: go test ./...`.
+- Don't bundle "while we're here" work into a slice. That's scope creep; log it as a
+  follow-up instead.
+- Don't slice to a target number: the count comes from the capabilities + the sizing
+  rule (`slicing.md`), not a figure anyone named.

package/pack/generated/dsh/skills/rite-polish/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: rite-polish
+description: Polish the active feature's code and any touched UI before review. Use for finish or normalization requests; not for repository-wide refactors.
+argument-hint: "[target | bolder | quieter | distill | harden | normalize-only]"
+user-invocable: true
+---
+
+<!-- loads: {"always":["devrites-lib/reference/standards/core.md","devrites-lib/reference/candidate-integrity.md","rite-polish/reference/code.md","rite-polish/reference/anti-patterns.md","rite-polish/reference/anti-ai-slop.md","rite-polish/reference/harden-checklist.md","rite-polish/reference/ledger.md","rite-build/reference/checkpoint.md"],"triggers":{"adr":["rite-polish/reference/adr-promotion.md"],"agents":["devrites-lib/reference/standards/agents.md"],"backend":["rite-polish/reference/backend-polish.md"],"coding":["devrites-lib/reference/standards/coding-style.md","devrites-lib/reference/standards/duplicate-code.md"],"errors":["devrites-lib/reference/standards/error-handling.md"],"ui":["rite-polish/reference/ui.md","rite-polish/reference/design-memory.md","rite-polish/reference/design-system-discovery.md","rite-polish/reference/browser-polish-evidence.md","devrites-lib/reference/standards/browser-proof-checklist.md"]},"workspace":["brief.md","spec.md","state.md","decisions.md","assumptions.md","questions.md","decision-coverage.md","architecture.md","plan.md","tasks.md","traceability.md","eng-review.md","test-plan.md","gates.md","evidence.md","touched-files.md","design-brief.md","browser-evidence.md","polish-report.md"],"workspaceByRole":{"slice-wright":["spec.md","architecture.md","plan.md","tasks.md","test-plan.md","state.md","decisions.md","design-brief.md"]},"rootOnly":["rite-build/reference/checkpoint.md"]} -->
+> Read-set manifest: `devrites-engine context --skills-root .dsh/skills <slug> --phase polish` bundles every file named below into one deduplicated read. Trigger names map to the conditional rules in the sections that follow.
+
+
+# /rite-polish: finish before review
+
+Polish code for every feature. When the feature touches UI, normalize and polish the
+UI as well. Complete this self-review before `/rite-review`. The code and UI phases
+live in [`reference/code.md`](reference/code.md)
+([`anti-ai-slop.md`](reference/anti-ai-slop.md),
+[`backend-polish.md`](reference/backend-polish.md))
+and [`reference/ui.md`](reference/ui.md)
+([`browser-polish-evidence.md`](reference/browser-polish-evidence.md),
+[`design-system-discovery.md`](reference/design-system-discovery.md),
+[`harden-checklist.md`](reference/harden-checklist.md));
+read only the phase in scope.
+
+## Operating rules
+
+- **Functionality complete first.** Polish runs after `/rite-prove` (full
+  feature proven).
+- Follow the shared
+  [`candidate-integrity.md`](../devrites-lib/reference/candidate-integrity.md).
+  Polish owns every candidate-affecting correction and durable rollup before Review.
+- Feature scope only.
+- For UI, **normalize before polishing**. Do not add decoration on top of drift.
+- **Bounded polish passes.** Verification runs in bounded passes, not a loop: after the
+  Phase 4 assessment, at most one more correction round for **new** findings, then stop —
+  residual subjective preference is recorded in `polish-report.md`, not re-polished.
+  **Failing case:** the same surface reopened a third time with no new failing evidence.
+- **Root selects; wright edits.** The controlling chat assesses and reconciles, but every
+  accepted source/test correction is dispatched to the sole writer,
+  `devrites-slice-wright`, through
+  [`agents.md`](../devrites-lib/reference/standards/agents.md). Never edit source inline or
+  run two correction writers concurrently.
+
+## Polish axes (C3 — completeness vs craft)
+
+Score **separately**; conflating them hides gaps:
+
+| Axis | Question | Failing case |
+| --- | --- | --- |
+| **ux_coverage** | Did we compare every stated alternative/state? | Omitted empty/error state treated as agreement |
+| **completeness** | Are required states, copy, and flows present? | Hero-only layout with no loading/error |
+| **craft / anti-slop** | Does the UI avoid generic template patterns? | Inter + purple gradient hero with no product-specific hierarchy |
+| **distinction** | Is there one intentional signature detail? | Polished but indistinguishable from a template |
+
+Incomplete comparison is **not** agreement. Record axis deltas in `polish-report.md`.
+
+## Orchestration
+
+0. **Read** `.dsh/skills/devrites-lib/reference/standards/core.md` first (the always-on operating rules). The
+   per-phase rule files ([`coding-style.md`](../devrites-lib/reference/standards/coding-style.md), [`error-handling.md`](../devrites-lib/reference/standards/error-handling.md), …) load on demand
+   from `reference/code.md` / `reference/ui.md` when their phase runs; for UI scope also read
+   `.dsh/skills/devrites-lib/reference/standards/browser-proof-checklist.md`.
+   Then read the explicit or active workspace's `state.md` directly.
+1. **Read** `state.md`, `touched-files.md`, the current candidate digest, and the
+   `git diff` for the active workspace (or `$ARGUMENTS` if a target was given).
+2. **Detect UI scope:** UI is touched when the diff changes rendered output:
+   markup, template, style, design token, client component, or a visible string
+   (including an API error message shown in the UI). These paths are leads to
+   inspect, not the predicate: `.tsx`, `.jsx`, `.vue`, `.svelte`, `.html`, `.css`,
+   `.scss`, `.sass`, `.less`, `.styl`, component dirs (`components/`,
+   `pages/`, `routes/`, `app/`, `views/`, `screens/`), Storybook stories,
+   or design-token files; when in doubt whether output changes, treat it as UI
+   scope. A diff with no rendered-output change records
+   `UI scope: none (no rendered output)` and skips Phases 3–4; non-visual client
+   code still gets frontend engineering review (`devrites-code-reviewer` frontend lane).
+   **Failing case:** an `app/services/billing.rb` diff opens Phase 4 and demands
+   captures.
+3. **Always** read [`reference/code.md`](reference/code.md) and assess **Phase 1
+   (code polish)**; if backend was touched, assess **Phase 2 (backend polish)** from
+   the same file. Assess step 4's UI phases on the same frozen digest while the
+   code assessment runs, reconcile both, then send every accepted code and UI
+   correction as one bounded wright contract (normalize corrections before polish
+   ones): build its read-set with
+   `devrites-engine context --skills-root .dsh/skills <slug> --phase polish --role slice-wright`, run the
+   single-agent wave through `devrites-engine dispatch <slug> open|start|seal|return`
+   (auto-records dispatch/return metrics; `open` passes `--claim-session <id>` and one
+   `--claim <path>` per contract path, so the root-edit tripwire attributes its edits), and gate returned paths
+   with `devrites-engine check diff-scope <slug> --allow <contract-paths>` before
+   proof.
+4. **If UI scope detected** read [`reference/ui.md`](reference/ui.md), and read
+   `design-brief.md` if present so the polish follows the direction and states established
+   by `devrites-ux-shape` and refined by `devrites-frontend-craft`. **Read the
+   `## Visual Verdict` table in `browser-evidence.md` if present:
+   its `FAIL` and `PARTIAL` rows are the normalize/quality-bar worklist**: identify the root
+   cause of each (a missing state, an off-token CTA, or an anti-slop hit) rather than
+   hiding it with decoration. Assess **Phase 3 (normalize)** → **Phase 4 (UI polish)**,
+   and fold accepted UI
+   corrections into step 3's single wright contract (the wright invokes the relevant craft skill). Honor argument modes:
+   - `bolder | quieter | distill | harden`: passed to Phase 4 as the
+     emphasis dial.
+   - `normalize-only`: assess Phase 3 and stop (no Phase 4).
+5. **Finish durable rollups before Review.** Apply the capability
+   [`ledger`](reference/ledger.md) when requirements changed, the optional UI
+   [`design memory`](reference/design-memory.md), and durable
+   [`ADR promotion`](reference/adr-promotion.md). Add every changed project path
+   to the candidate manifest and record each root-written ADR or `DESIGN.md` path the
+   tripwire flags (`check candidate` names it) with `devrites-engine dispatch <slug> attribute --reason "polish rollup" --path <path>`;
+   none of these writes waits for Ship.
+6. **Re-prove and close.** After all accepted code/UI corrections and rollups,
+   run `devrites-engine check candidate <slug>` and `devrites-engine check
+   windows <slug>` — an unwaived deferral marker surfaces here, not at Seal.
+   Any digest change requires
+   affected real re-proof using the approved commands, fresh proof-runner
+   validation, refreshed evidence/browser bindings, and an updated candidate
+   manifest. Record a **`Re-verification:`** line in `polish-report.md`. Close
+   the candidate for Review only after these checks are green. Then checkpoint
+   remaining candidate diffs per
+   [`checkpoint.md`](../rite-build/reference/checkpoint.md).
+7. **Aggregate output:** each phase appends to the single `polish-report.md`.
+
+## Refinement modes
+
+Pass the requested UI direction to Phase 4. Modes do not bypass normalization or the
+quality bar; they apply after the system is aligned. See `reference/ui.md`.
+
+> **Mid-flight discipline.** When tempted to polish UI without normalize, cite
+> clean lint as proof of quality, skip Phase 2 on a backend diff, or delete a
+> Chesterton's Fence: see [anti-patterns](reference/anti-patterns.md).

package/pack/generated/dsh/skills/rite-polish/reference/adr-promotion.md

@@ -0,0 +1,11 @@
+# ADR promotion
+
+During Polish, promote a `decisions.md` architecture/interface choice only when it is
+hard to reverse, surprising without context, and a real trade-off. Otherwise leave it in
+the archived workspace. If the project has no `docs/adr/`, ask before creating that
+convention.
+
+Write the next append-only `docs/adr/ADR-NNN.md` with Context, Decision, Status
+`accepted`, and Consequences. Never rewrite an accepted ADR; supersede it with a linked
+new ADR. Add it to the candidate manifest, run affected real re-proof, and refresh evidence
+and browser bindings before Review. Ship performs no ADR promotion.