@mindrian_os/install 1.13.0-beta.17 → 1.13.0-beta.21

package/skills/ui-system/rules/glyph-disambiguation.md

@@ -0,0 +1,171 @@
+---
+name: glyph-disambiguation
+description: >
+  ODD 4 resolution (Phase 121.5, 2026-05-16). Documents the 🎯 glyph overload
+  (three surfaces, three meanings) and the "JTBD" word collision (Phase 37
+  bash nudges vs Phase 100 typed engine) as explicit position-anchored
+  exceptions in SKILL.md §3 -- mirroring the existing no-emoji + statusline
+  carve-out pattern. The lower-risk path: document the seam, not move it.
+  Renumbering / renaming deferred to v1.14.0 cleanup.
+---
+
+# Glyph + Word Disambiguation Rule (ODD 4 Resolution)
+
+Phase 121.5 (Terminal Coherence Capstone) found two vocabulary collisions in
+v1.13.0 that needed resolution before the final release gate. The lower-risk
+path chosen 2026-05-16: DOCUMENT both as explicit position-anchored exceptions
+in `skills/ui-system/SKILL.md` §3, mirroring the existing no-emoji +
+statusline carve-out pattern. The pattern is: a global rule with a precisely-
+named exception, position-anchored.
+
+Renumbering the glyphs and renaming "JTBD" the word were considered and
+deferred to v1.14.0. Rationale:
+
+1. Phase 121.5 is consolidation, not expansion (Canon Part 7). Renaming "JTBD"
+   the word ripples through 24+ files, Brain context packets, telemetry
+   event types. Cost-benefit too high for the closing milestone.
+2. The collisions are real but CONTEXT-DISAMBIGUATING: each occurrence is
+   resolved by surface position. 🎯 in statusline Row 2 next to "JTBD" means
+   "what job"; 🎯 in /mos:jtbd output means "broadcast"; 🎯 in
+   EXPLORATION_LABELS means problem-definition. Each surface owns its
+   position-anchored meaning.
+3. Documenting the overload + carve-out is the SAME shape of exception the
+   existing emoji carve-out (no-emoji rule with statusline exception) already
+   does. We follow the same pattern.
+
+Future v1.14.0 may renumber the glyphs OR rename "JTBD". For v1.13.0 final we
+mark the seam, not move it.
+
+---
+
+## 1. The 🎯 glyph overload (three surfaces, three meanings)
+
+The 🎯 emoji is used on three distinct surfaces with three distinct meanings.
+Each surface owns its position-anchored meaning; the three meanings never
+collide on the same surface at the same time.
+
+| Surface                                          | 🎯 meaning                                                                        | Source path                                  |
+|--------------------------------------------------|-----------------------------------------------------------------------------------|----------------------------------------------|
+| Statusline Row 2 (the JTBD label prefix)          | "What job are you in right now."                                                  | `scripts/context-monitor`                    |
+| `/mos:jtbd` command output + JTBD broadcast       | "This is the job we're proposing." (recommendation prefix)                       | `commands/jtbd.md` + JTBD nudge rendering    |
+| `EXPLORATION_LABELS` problem-definition emoji     | "Where the wicked navigator starts." (stage emoji for problem-definition phase) | `lib/core/visual-ops.cjs` EXPLORATION_LABELS |
+
+**Reader disambiguation rule.** Ask: WHERE is the 🎯?
+
+  - Statusline row 2? -> active JTBD context (what job).
+  - Command output / broadcast banner? -> JTBD recommendation (which job).
+  - EXPLORATION_LABELS render path (visual ops, stage-labeled output)? ->
+    problem-definition stage emoji.
+
+The three surfaces are physically separate render paths; they never appear
+together in the same line, the same paragraph, or the same selector block.
+
+---
+
+## 2. The "JTBD" word collision (two systems)
+
+The acronym "JTBD" (Jobs-To-Be-Done) names two unrelated systems in the
+plugin:
+
+| System                          | Status                                       | Source path                                                       |
+|---------------------------------|----------------------------------------------|-------------------------------------------------------------------|
+| Phase 37 nudge templates        | Internal prompt-engineering layer (legacy)   | `lib/hmi/build-jtbd-nudges` (bash, prompt-engineering style)      |
+| Phase 100 typed engine          | AUTHORITATIVE 13-JTBD taxonomy + verb engine | `lib/hmi/jtbd-taxonomy.json` (cues / methodology hooks / verbs)   |
+
+**Resolution rule.** When SKILL.md, the Mindrian canon, or any user-facing
+surface says "JTBD" without qualification, it means the **Phase 100 typed
+engine** (`lib/hmi/jtbd-taxonomy.json` -- the 13-JTBD taxonomy with
+methodology hooks, next_move_verbs, and completion patterns).
+
+The Phase 37 nudges are an internal prompt-engineering layer beneath the
+engine. User-facing surfaces never name them directly. If a code path needs to
+distinguish, the convention is:
+
+  - "JTBD" (unqualified) -> Phase 100 engine.
+  - "JTBD nudge template" / "build-jtbd-nudges" -> Phase 37 layer (internal
+    reference only).
+
+---
+
+## 3. The carve-out pattern
+
+This rule mirrors the structure of the existing emoji carve-out in
+`skills/ui-system/SKILL.md` §3:
+
+> Global rule: NO EMOJI. EVER.
+> Carve-out: `scripts/context-monitor` statusline is excepted (position-
+> anchored: the host terminal renders it as a passive signal surface, not a
+> MindrianOS command output body).
+
+ODD 4 follows the same shape:
+
+> Global rule: One glyph -> one meaning. One word -> one system.
+> Carve-out: 🎯 has three position-anchored meanings (statusline row 2 / `/mos:jtbd`
+> output / EXPLORATION_LABELS). "JTBD" has two position-anchored systems
+> (Phase 100 engine = authoritative; Phase 37 nudges = internal-only).
+
+The pattern is: precision in the exception, anchored by surface position.
+Future cleanup may move the seam; until then, the surfaces own the meaning.
+
+---
+
+## 4. The v1.14.0 cleanup proposal
+
+A future v1.14.0 cleanup phase MAY:
+
+  - Renumber the 🎯 glyph by SURFACE: e.g. statusline uses 🎯, broadcast uses
+    `🔆` or a new 12-glyph CLI vocabulary entry, EXPLORATION_LABELS uses a
+    distinct stage emoji.
+  - Rename one of the two "JTBD" systems: e.g. Phase 37 nudges become
+    "JTBD-nudges-v0" or "preinference-nudges"; Phase 100 engine retains "JTBD"
+    unqualified.
+
+Both are renaming exercises with ripple costs: ~24 files for "JTBD" rename,
+3+ render paths for 🎯. Neither is in scope for v1.13.0. Track in
+`docs/CANON-PHASE-MAP.md` v1.14.0 backlog under Canon Part 7 (Reuse Before
+Build) -- the bar for renumbering is "this REPLACES / reconciles N existing
+things," not "this is the N+1th."
+
+---
+
+## 5. Verification
+
+This rule passes when:
+
+1. SKILL.md §3 contains the "ODD 4 resolution" paragraph documenting both
+   collisions (grep `ODD 4 resolution` returns >= 1 hit).
+2. SKILL.md §3 still preserves the existing no-emoji + statusline carve-out
+   (the ODD 4 paragraph is APPENDED, not replacing).
+3. SKILL.md §3 cross-references this rule file
+   (`skills/ui-system/rules/glyph-disambiguation.md`).
+4. No new glyphs were added to the 12-glyph CLI vocabulary table in SKILL.md
+   §3 (Canon Part 7 invariant: ZERO new glyphs in 121.5).
+5. No code paths were renamed (Canon Part 7 invariant: ZERO concept renames
+   in 121.5).
+
+---
+
+## 6. Canon Refs
+
+- **Part 3 (UI Ruling System enforcement)** -- the carve-out is the
+  documented exception in the ruling system's vocabulary contract.
+- **Part 7 (Reuse Before Build)** -- consolidation only. ZERO new commands,
+  glyphs, renames.
+- **Part 8 (Graph Boundary)** -- no Brain query depends on the disambiguation;
+  glyph + word use is LOCAL render-path concern.
+- **Part 10 (Conversation as Product)** -- the terminal must coherently
+  express its vocabulary. ODD 4 resolution closes a coherence gap before the
+  v1.13.0 final gate.
+
+---
+
+## 7. See Also
+
+- `skills/ui-system/SKILL.md` §3 -- the carve-out lives there in canonical
+  form; this rule file is the expansion.
+- `.planning/phases/121.5-terminal-coherence-capstone/121.5-CONTEXT.md` --
+  ODD 4 (item 8 + "Open Design Decisions" section).
+- `lib/hmi/jtbd-taxonomy.json` -- the authoritative Phase 100 JTBD system.
+- `lib/hmi/build-jtbd-nudges` -- the Phase 37 layer (internal only).
+- `scripts/context-monitor` -- statusline 🎯 (active JTBD prefix).
+- `lib/core/visual-ops.cjs` -- EXPLORATION_LABELS 🎯 (problem-definition).

package/skills/ui-system/rules/shape-f-zero-and-six.md

@@ -0,0 +1,169 @@
+---
+name: shape-f-zero-and-six
+description: >
+  Shape F.0 (Mini Decision Gate) and Shape F.6 (Plan Review Round) sub-shape
+  documentation. Both shipped in Phase 88.2. Surface them at queryable
+  granularity so the skill auto-loader can pull this rule independently of
+  the full SKILL.md when only F.0 or F.6 is in scope. Part of the current
+  Shape F catalog as of Phase 121.5 (additive expansion reserved for future
+  lens-aware variants).
+---
+
+# Shape F.0 + Shape F.6 -- Sub-shape Documentation
+
+This rule documents the two Shape F sub-shapes that landed in Phase 88.2 and are
+shipped but were missing from `skills/ui-system/SKILL.md` until the Phase 121.5
+reconciliation pass. The five original sub-shapes (F.1 through F.5) are
+documented in SKILL.md §2 and remain unchanged. F.0 is the lightweight
+binary-or-trinary gate that fires BEFORE the larger Shape F slate; F.6 is the
+Plan Mode wrap that closes a planning round (and, per Phase 101-01, is also the
+JTBD-aware variant of Shape F selected by the dispatcher when a JTBD signal is
+set).
+
+The Shape F catalog as of Phase 121.5 carries seven sub-shapes (F.0 / F.1 / F.2
+/ F.3 / F.4 / F.5 / F.6). This is the current catalog; future v1.14.0+ work may
+add lens-aware variants (the dual-graph proposal under review 2026-05-16 may
+introduce ASSOCIATION_LENS / TRANSITION_LENS lens-class variants).
+
+---
+
+## Shape F.0 -- Mini Decision Gate
+
+**Shipped:** Phase 88.2 (Plan 88.2-05 / UISEL-88.2-07).
+
+**Implementation:** `lib/hmi/shape-f0-renderer.cjs` (pure CJS, node built-ins
+only, zero new runtime deps).
+
+**Purpose.** Tiny binary or trinary decision gate. Lighter than F.1 (which
+carries 3-5 options). F.0 is the minimum-viable gate when the navigator only
+needs a yes / no / defer call before the larger selector slate fires.
+
+**When to use.** A surface needs a confirmation BEFORE producing the larger F.1
+selector. Most common pairing: F.0 (accept this recommendation?) -> F.1 (now
+choose next move). Used for binary commits that need an explicit edge produced
+even when the navigator wants to keep moving.
+
+**Verb set.** EXACTLY 3 verbs (closed vocabulary, shipped value):
+
+  - Approve  -- cascade now (collapses to Run Methodology or whatever the
+                recommendation called for)
+  - Reject   -- capture reason -> REJECTED_BECAUSE typed edge (graph data, no
+                silent dismiss path -- Canon Part 4)
+  - Defer    -- queue for milestone audit (Defer verb)
+
+**No Free-Text slot.** F.0 omits Free-Text by design. The Reject path captures
+the reason as a REJECTED_BECAUSE edge property, which preserves free-form intent
+without expanding the verb vocabulary. F.0 ALWAYS produces a typed edge; there
+is no silent dismiss path.
+
+**Header format.**
+
+```
+[filled-square] [CONTEXT] - MINI GATE             - decision gate
+[right-triangle-filled] {short binary or trinary question}
+```
+
+Single-line ASCII border (the visual sub-decision cue). Persona-agnostic
+visually (D-AMEND-04 from Phase 88.2 CONTEXT.md).
+
+**Keyboard.** Standard F-family keyboard. up-arrow / down-arrow (or J / K) to
+navigate, Enter to select, `?` to inspect, Esc to cancel.
+
+**No RECOMMENDED marker.** F.0 is itself the recommendation surface. Marking
+one of the three options would double-cue. RECOMMENDED markers are an F.1
+through F.5 concept.
+
+**State-update hook.** Append to STATE.md Decisions section with the chosen
+verb + a tiny one-line context snapshot (F.0 gates are lightweight; do NOT
+bloat Decisions with full context). Typed edge `(navigator) -[CHOSE_MINI
+{verb}]-> (recommendation-node)` lands in the local graph. Reject additionally
+writes REJECTED_BECAUSE with `{reason, rejected_at, parent_decision_id,
+actor_id?, confidence_self_report?}` via Phase 109 `logEvent` (eventType
+`selector_rejection_captured`).
+
+**Canon refs.** Part 3 (the gate), Part 4 (rejection is data), Part 8 (reason
+text is graph-local; never egresses to Brain).
+
+---
+
+## Shape F.6 -- Plan Review Round
+
+**Shipped:** Phase 88.2 (Plan 88.2-06 plan-review variant) + Phase 101-01
+(JTBD-aware Next Move variant).
+
+**Implementation:** Two co-existing renderers at collision-safe paths:
+  - `lib/hmi/shape-f6-plan-review-renderer.cjs` -- Plan Review Round variant
+    (Phase 88.2-06; double-line border for structural distinction from F.0).
+  - `lib/hmi/shape-f6-renderer.cjs` -- JTBD-aware Next Move variant (Phase
+    101-01; falls through to F.1 if JTBD taxonomy entry missing).
+
+The umbrella `F` branch in `lib/hmi/selector-dispatcher.cjs` (`F_SUBSHAPES =
+['F.0', 'F.1', 'F.2', 'F.3', 'F.4', 'F.5', 'F.6']`) routes to the Phase 101-01
+JTBD-aware module when `jtbd` is non-null; explicit `requestedShape: 'F.6'`
+(string) routes to the plan-review renderer.
+
+**Purpose.** Plan Mode wrap. When the navigator has been in a planning surface
+(e.g. after a methodology session that produced a plan), F.6 closes the round
+with an explicit Review verb selection BEFORE returning to Plan vs Build mode.
+The JTBD-aware variant produces a JTBD-anchored Next Move slate sourced from
+`lib/hmi/jtbd-taxonomy.json` `next_move_verbs`.
+
+**When to use.**
+  - End of a plan-producing methodology session (Plan Review variant).
+  - Any Shape F surface where a non-null JTBD is in play and the renderer
+    should produce a JTBD-aware Next Move slate (JTBD-aware variant).
+
+**Verb set.** 3-5 verbs. Plan-review typical slate:
+
+  - Approve plan        -> Synthesize (plan becomes confirmed artifact;
+                            review_status proposed -> confirmed, Canon Part 9)
+  - Revise plan         -> Reformulate (re-runs the planning verb with edits)
+  - Replan from scratch -> Reformulate from a fresh seed
+  - Defer review        -> Defer (milestone-audit TodoWrite row)
+  - Free-Text           -> Free-Text routes to interpretation
+
+JTBD-aware variant draws verbs from the taxonomy entry's `next_move_verbs`.
+
+**Header format.**
+
+```
+[filled-square] [CONTEXT] - PLAN REVIEW           - decision gate
+[down-triangle] LOCAL   / BRAIN   / SIGNAL
+[right-triangle-filled] Review this plan:
+```
+
+Double-line border on the Plan Review variant (parent shape -- structural
+distinction from F.0's single-line border).
+
+**Keyboard.** Standard F-family keyboard (inherits from F.1 per Phase 101-01
+D-01).
+
+**State-update hook.**
+  - On Approve, plan is promoted `review_status: proposed -> confirmed` (Canon
+    Part 9 truth-state machine).
+  - On Revise/Replan, original plan stays `proposed` and a new revision edge is
+    created.
+  - On Defer, a milestone-audit TodoWrite row queues the review.
+  - Plan-review variant additionally writes REVIEWED typed edges per question
+    position with `{round_id, position, latency_ms, was_decoy, response,
+    confidence_self_report}` via Phase 109 `logEvent` (eventType
+    `selector_response`). Round close emits a `f6_round_completed` event.
+
+**Decoy ethics.** The Plan Review variant runs decoys (interleaved per
+position) with a debrief Shape A action report at round-end that discloses
+which questions were decoys (round-state `room/decisions/decision-decoy-
+ethics.md`).
+
+**Canon refs.** Part 3 (the gate), Part 9 (truth states), Part 4 (every
+response is a typed edge), Part 8 (response text is graph-local).
+
+---
+
+## Sub-shape catalog notes
+
+The Shape F catalog as shipped through Phase 88.2 carries seven sub-shapes
+(F.0 / F.1 / F.2 / F.3 / F.4 / F.5 / F.6). This is the current catalog as of
+Phase 121.5. The catalog is expandable, not foreclosed: lens-aware variants
+(e.g. the dual-graph ASSOCIATION_LENS / TRANSITION_LENS work under review
+2026-05-16) may add future Shape F sub-shapes in v1.14.0+. SKILL.md treats
+today's seven sub-shapes as the shipped vocabulary, not a terminal set.