merge-readiness

name	merge-readiness
aliases	understanding-gate
description	Post-task merge readiness gate with a state-backed explanation report and human explainability quiz
argument-hint	[--quick|--standard|--deep] [--from-diff|--from-artifacts] <change summary or artifact path>

Merge Readiness is a post-task explainability gate. After implementation, tests, QA, and review evidence exist, it generates a human-readable explanation of the change, then asks the human targeted questions to verify they can explain why the change exists, what changed, what tradeoffs were made, what risks were considered, and how the team should understand it.

<Use_When>

• A task, PR, or change set is functionally complete and needs a final human-understanding check before merge readiness
• Tests, QA, code review, security review, or other verification has already run, or missing evidence must be explicitly recorded
• The user wants AI to explain the change and then quiz the human on whether they can explain it
• You need a durable session audit record showing why the team can trust and understand the change before asking for merge approval </Use_When>

<Do_Not_Use_When>

• Requirements are still unclear before implementation; use /deep-interview
• The implementation is not done; use /ralph, /team, or /autopilot
• Tests or QA have not run and the user expects this command to replace them
• The user wants code review findings; use /review or the relevant review workflow </Do_Not_Use_When>

<Why_This_Exists> Real delivery is not only code that works. Teams need to understand why a change exists, what changed, what was deliberately not done, which risks were considered, and what future maintainers should believe about the change. This workflow makes that understanding explicit before merge approval is requested. Passing this gate never means the change is approved or merged; it only means a human can explain it. </Why_This_Exists>

<Depth_Profiles>

• Quick (--quick): small/local changes; correctness threshold >= 0.70; max 3 MCQs; required dimensions: why / change / risk
• Standard (--standard, default): normal feature/bugfix; correctness threshold >= 0.80; max 5 MCQs; required dimensions: why / change / tradeoff / risk / team
• Deep (--deep): high-risk, architectural, security, or cross-module changes; correctness threshold >= 0.90; max 8 MCQs (redundancy across all five dimensions)

If no flag is provided, use Standard. Thresholds and round counts are canonical in src/hooks/merge-readiness/mcq.ts and must stay in sync with this file. </Depth_Profiles>

<Execution_Policy>

• This is a post-task command. Do not implement code inside this mode.
• Gather repository and artifact evidence before asking the human for facts that can be discovered locally.
• Generate the explanation doc + MCQs in one AI step, then present MCQs one-per-round.
• The runtime (TS hook code) is the backbone: it owns validation, authoritative session state, objective MCQ scoring, and report rendering. The AI owns content generation + MCQ presentation via AskUserQuestion.
• Present each MCQ one-per-round via AskUserQuestion (deep-interview style). Record each selection via the runtime so it is scored objectively.
• Ask about explainability, not implementation trivia.
• Never ask the human to memorize line numbers, variable names, private helper names, or incidental implementation details.
• Score is the objective correctness rate (correct answers / answered), not a keyword heuristic.
• If the correctness rate is below threshold after all required MCQs are answered, mark result paused and do not claim merge readiness.
• If key evidence is missing (no diff/change signal), mark result blocked.
• Passing this gate does not approve merge, replace tests, replace review, replace security review, accept risk, or bypass maintainer approval.
• Persist state for resume safety under .omc/state/merge-readiness-state.json (session-scoped under .omc/state/sessions/<sessionId>/). Do not write this file directly.
• v1 is advisory: the gate logic (checkMergeReadiness) is not wired to the Stop hook, so an active gate does not block the session. It does not perform or approve a Git merge. </Execution_Policy>

Phase 0: Evidence Intake

1. Parse {{ARGUMENTS}}, depth profile, source mode (--from-diff|--from-artifacts), and derive a task slug. --from-pr is unsupported; this workflow uses local evidence only.
2. Collect available evidence (the runtime detects artifacts by FILENAME heuristics; file CONTENTS are never parsed):
   • Local Git diff and commit range
   • Changed files
   • Test/QA/verification artifacts (filenames matching test|spec|qa|verify|validation)
   • Review/risk/security/readiness/verdict artifacts (filenames matching review|risk|security|readiness|verdict)
   • .omc/plans/, .omc/specs/, .omc/interviews/, .omc/artifacts/, .omc/logs/, and relevant mode state artifacts (canonical {mode}-state.json files under .omc/state/ that record a real run)
3. Record missing evidence explicitly. Missing evidence is not hidden by a good explanation.

Phase 1: Initialize

Call the merge_readiness_start tool with the change summary to seed state (the runtime parses the --quick/--deep profile (--standard is the default when neither flag is present; it is not a parsed token)). State shape:

{
  "active": true,
  "current_phase": "merge-readiness",
  "phase": "content",
  "profile": "standard",
  "threshold": 0.80,
  "max_rounds": 5,
  "required_dimensions": ["why", "change", "tradeoff", "risk", "team"],
  "questions": [],
  "answers": [],
  "awaiting_content": true,
  "readiness_score": 0,
  "result": "pending"
}

awaiting_content is true until the AI submits the generated doc + MCQs via merge_readiness_set_content.

Phase 2: Generate Explanation Doc + MCQs (AI content step)

Generate, from the actual diff + evidence (not templates):

1. A 5-section narrative: Why, What Changed, Tradeoffs, Risks Considered, Team Understanding.
2. A set of MCQs (one correct option each, with correctOptionId + optional rationale):
   • Up to the profile max rounds (quick 3 / standard 5 / deep 8)
   • Distributed across the required dimensions
   • Testing understanding of THIS change, not implementation trivia

Submit them with merge_readiness_set_content (requires an active gate from merge_readiness_start; it errors if no gate is active). Do not write the state JSON or invoke internal runtime functions. Invalid content is rejected with recoverable validation errors. The validated content is persisted in the authoritative session state.

Use merge_readiness_report to render the five sections, evidence, quiz progress, readiness, and merge boundary directly from state. It is read-only and does not create a file. Correct answers and rationales remain hidden until the attempt is complete; cancellation or override reveals only answered questions.

The Merge Boundary must say: "Passing means the human can explain the change. It does not approve merge, replace tests, replace review, or accept risk."

Maintainer Override Authority

/merge-readiness --override <reason> is accepted only when the MCP server launcher injects an authenticated principal in OMC_MERGE_READINESS_AUTHENTICATED_PRINCIPAL and includes that exact principal in the comma-separated OMC_MERGE_READINESS_MAINTAINERS allowlist. The caller-provided session_id selects the state record only; it is never override authority and is not recorded as override_owner.

Phase 3: Human Quiz Loop (MCQ, one-per-round, deep-interview style)

Present each MCQ one-per-round via AskUserQuestion with the option ids/text as choices, then record the human’s selection with the merge_readiness_record_answer tool (questionId + optionId). The runtime scores it objectively and either advances to the next question or finalizes the gate (pass / paused / blocked).

Cover these dimensions before passing (quick = why/change/risk only):

1. why - why this change was worth doing
2. change - what behavior, workflow, interface, or maintenance model changed
3. tradeoff - what was chosen, deferred, or rejected and why
4. risk - which risks were considered and what remains risky
5. team - how the team should understand and maintain this change

Forbidden question types:

• Function-name trivia
• Line-number trivia
• Variable-name recall
• Private helper memorization
• Any question whose answer does not help a reviewer explain the change

Phase 4: Score Readiness (runtime-owned, objective)

The runtime computes:

• readiness_score = correctness rate = (correct answers) / (answered answers), in [0, 1]
• Per-dimension coverage = whether every required dimension has at least one answered MCQ

Gate results:

• pass: all required MCQs answered AND correctness rate >= threshold AND required dimensions covered
• paused: all required MCQs answered but correctness rate below threshold (or required dimension uncovered)
• blocked: missing minimal evidence (no diff/change signal)

Thresholds: quick 0.70 / standard 0.80 / deep 0.90.

Phase 5: Crystallize Result

Persist these fields in the terminal session state and inspect them with merge_readiness_report:

• Final readiness score
• Dimension breakdown
• Human answers
• AI assessment
• Result
• Blocking or paused gap
• Next step

Phase 6: Handoff

If pass:

• State that the change may proceed to human merge approval.
• Do not merge.

If paused:

• State which explanation dimension is missing.
• Recommend rereading or revising the report and rerunning /merge-readiness.

If blocked:

• State which evidence must be produced before rerunning.

<Tool_Usage>

• Use repository search and local artifacts for evidence intake before asking the human for context.
• Use structured user questioning when available.
• Use merge_readiness_start to initialize the gate, merge_readiness_set_content to submit the report + MCQs, merge_readiness_record_answer to record each selection, and merge_readiness_report to render the current audit record. Use state read/status/clear only for .omc/state/merge-readiness-state.json; never use generic state write to submit quiz content. state_clear routes merge-readiness through cancellation and preserves terminal state; pass the current session_id to avoid cancelling concurrent quizzes. </Tool_Usage>

<Escalation_And_Stop_Conditions>

• User says stop/cancel/abort -> persist terminal cancelled state and stop.
• Missing diff or change evidence -> blocked.
• Human cannot explain a required dimension -> paused.
• Readiness threshold reached and mandatory gates satisfied -> pass. </Escalation_And_Stop_Conditions>

<Final_Checklist>

• Evidence intake completed
• Missing evidence recorded
• Explanation doc (5 sections) + MCQs submitted via merge_readiness_set_content
• MCQs presented one-per-round via AskUserQuestion
• Each answer correlated from marked AskUserQuestion output (objective scoring)
• Questions avoided implementation trivia
• Correctness rate calculated by the runtime
• Result is pass, paused, blocked, overridden, or cancelled
• Merge Boundary is explicit
• No direct implementation or merge performed </Final_Checklist>

## Recommended Delivery Pipeline

/deep-interview
  -> /omc-plan or /ralplan
  -> /ralph, /team, or /autopilot
  -> /ultraqa and review
  -> /merge-readiness
  -> human merge approval

Autopilot Bridge

Autopilot may call this workflow after QA/validation when configured:

{
  "autopilot": {
    "mergeReadiness": true
  }
}

autopilot.understandingGate is a deprecated compatibility alias for autopilot.mergeReadiness.

Task: {{ARGUMENTS}}