@nforma.ai/nforma 0.2.1

package/commands/qgsd/observe.md

@@ -0,0 +1,260 @@
+---
+name: qgsd:observe
+description: Fetch issues and drifts from configured sources, render dual-table output, and write to debt ledger. Replaces /qgsd:triage.
+argument-hint: "[--source github|sentry|sentry-feedback|bash|internal] [--since 24h|7d] [--limit N]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Aggregate issues and drifts from all configured sources, deduplicate, render a prioritized dual-table output (Issues + Drifts), write observations to the debt ledger, and route the selected issue to the right QGSD workflow.
+
+This command is the project's unified "what's broken right now?" entry point. It replaces `/qgsd:triage` with debt-aware persistence and dual-table rendering.
+</objective>
+
+<process>
+
+## Step 1: Parse arguments
+
+From `$ARGUMENTS`, extract:
+- `--source <type>` → `$SOURCE_FILTER` (filter to one source type; default: all)
+- `--since <duration>` → `$SINCE_OVERRIDE` (e.g. `24h`, `7d`; overrides per-source config)
+- `--limit <n>` → `$LIMIT_OVERRIDE` (max issues per source; default: 10)
+
+## Step 2: Load source configuration
+
+Use `loadObserveConfig()` from `bin/observe-config.cjs` to load sources.
+
+```javascript
+const { loadObserveConfig } = require('./bin/observe-config.cjs');
+const config = loadObserveConfig();
+// config = { sources, configFile, observeConfig, error? }
+```
+
+The loader automatically:
+1. Tries `.planning/observe-sources.md` first, falls back to `.planning/triage-sources.md` (backward compatible)
+2. Parses YAML frontmatter to extract sources array
+3. Infers `issue_type` for known source types (github/sentry/bash → "issue", prometheus/grafana/logstash → "drift")
+4. Applies default timeout and fail_open settings
+
+**If no config file exists or error is returned:**
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ QGSD > OBSERVE: No sources configured
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Create .planning/observe-sources.md to configure issue sources.
+```
+Stop.
+
+**If `$SOURCE_FILTER` is set**, keep only sources whose `type` matches.
+
+**Always-on internal source:** Regardless of config or filters, inject an internal work detection source:
+
+```javascript
+// Inject internal scanner unconditionally (always-on, no config needed)
+const internalSource = { type: 'internal', label: 'Internal Work', issue_type: 'issue' };
+// Add to sources array if not already present and not filtered out by --source
+if (!$SOURCE_FILTER || $SOURCE_FILTER === 'internal') {
+  config.sources.push(internalSource);
+}
+
+// Critical: check for empty sources AFTER internal injection
+if (config.sources.length === 0) {
+  // Display "no sources" message only if sources is empty AFTER internal source injection
+  display("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n QGSD > OBSERVE: No sources configured\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nCreate .planning/observe-sources.md to configure issue sources.");
+  stop();
+}
+```
+
+This ensures internal work detection runs even if observe-sources.md doesn't exist or if the user filters to `--source internal`.
+
+## Step 3: Register handlers
+
+Import handler functions and register them with the registry:
+
+```javascript
+const { registerHandler } = require('./bin/observe-registry.cjs');
+const { handleGitHub, handleSentry, handleSentryFeedback, handleBash, handleInternal } = require('./bin/observe-handlers.cjs');
+
+registerHandler('github', handleGitHub);
+registerHandler('sentry', handleSentry);
+registerHandler('sentry-feedback', handleSentryFeedback);
+registerHandler('bash', handleBash);
+registerHandler('internal', handleInternal);
+```
+
+Display dispatch header:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ QGSD > OBSERVE: Fetching from N source(s)...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Step 4: Dispatch parallel fetch
+
+Call `dispatchAll()` from `bin/observe-registry.cjs` — this dispatches ALL sources uniformly through the registry with per-source timeout. No special-casing per source type at this stage.
+
+```javascript
+const { dispatchAll } = require('./bin/observe-registry.cjs');
+const results = await dispatchAll(config.sources, { sinceOverride: $SINCE_OVERRIDE, limitOverride: $LIMIT_OVERRIDE });
+```
+
+This uses `Promise.allSettled` internally — one source failure does not block others (OBS-08).
+
+## Step 4b: MCP bridge for pending_mcp results
+
+After `dispatchAll` returns, iterate over results. For any result with `status: "pending_mcp"`:
+
+1. Read the `_mcp_instruction` object from the result:
+   ```javascript
+   const { tool, params, mapper } = result._mcp_instruction;
+   ```
+
+2. Execute the MCP tool call directly (the observe command runs in Claude context where MCP tools are available). Call the tool named in `_mcp_instruction.tool` with `_mcp_instruction.params`. Try `mcp__sentry__<tool>` first, then `mcp__plugin_sentry_sentry__<tool>` as fallback.
+
+3. Import the mapper function from `bin/observe-handlers.cjs`:
+   ```javascript
+   const handlers = require('./bin/observe-handlers.cjs');
+   const mapperFn = handlers[mapper]; // e.g., mapSentryIssuesToSchema or mapSentryFeedbackToSchema
+   ```
+
+4. Call the mapper with the MCP result and the original sourceConfig:
+   ```javascript
+   const mapped = mapperFn(mcpResult, sourceConfig);
+   // mapped = { source_label, source_type, status: "ok", issues: [...] }
+   ```
+
+5. Replace the `pending_mcp` result in the results array with the mapped standard schema result.
+
+6. If the MCP call fails, replace with:
+   ```javascript
+   { source_label, source_type, status: "error", error: "MCP call failed: {message}", issues: [] }
+   ```
+
+**Key principle:** This pattern keeps handlers as pure testable CJS functions while the observe command (running in Claude context) handles MCP execution. The registry's `dispatchAll` works uniformly — the MCP bridge is a post-processing step.
+
+## Step 5: Collect and render
+
+Call `renderObserveOutput()` from `bin/observe-render.cjs`:
+
+```javascript
+const { renderObserveOutput } = require('./bin/observe-render.cjs');
+const output = renderObserveOutput(results);
+```
+
+At this point ALL results are standard schema (pending_mcp results were resolved in Step 4b).
+
+The renderer:
+1. Separates successful results from errors
+2. Splits issues by `issue_type`: "issue" items and "drift" items
+3. Sorts each group by severity (error > bug > warning > info), then by age (newest first)
+4. Renders ISSUES table with columns: #, Title, Source, Sev, Age
+5. Renders DRIFTS table (if any) with columns: #, Parameter, Formal, Actual, Sev
+6. Renders error section at bottom listing failed sources
+
+Display the output.
+
+If total issues = 0 and no drifts:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ QGSD > OBSERVE: All clear — no open issues found
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Sources checked: <list>
+```
+Stop.
+
+## Step 6a: Write to debt ledger
+
+Call `writeObservationsToDebt()` from `bin/observe-debt-writer.cjs`:
+
+```javascript
+const { writeObservationsToDebt } = require('./bin/observe-debt-writer.cjs');
+
+// Collect all issues from all successful results
+const allObservations = results
+  .filter(r => r.status === 'ok')
+  .flatMap(r => r.issues || []);
+
+const { written, updated, errors } = writeObservationsToDebt(allObservations, '.planning/formal/debt.json');
+```
+
+Display:
+```
+Wrote {written} new, updated {updated} existing debt entries.
+```
+
+This upserts all observations by fingerprint (using v0.27-01's `fingerprintIssue` and `fingerprintDrift` functions). Same issues across runs update `occurrences` and `last_seen`, not duplicates.
+
+## Step 6b: Show debt summary
+
+Read the debt ledger and display status counts:
+
+```javascript
+const { readDebtLedger } = require('./bin/debt-ledger.cjs');
+const ledger = readDebtLedger('.planning/formal/debt.json');
+const entries = ledger.debt_entries || [];
+
+const counts = {
+  open: entries.filter(e => e.status === 'open').length,
+  acknowledged: entries.filter(e => e.status === 'acknowledged').length,
+  resolving: entries.filter(e => e.status === 'resolving').length,
+  resolved: entries.filter(e => e.status === 'resolved').length
+};
+```
+
+Display:
+```
+Debt ledger: {open} open, {acknowledged} acknowledged, {resolving} resolving, {resolved} resolved
+```
+
+## Step 7: Route to action
+
+Prompt the user:
+
+```
+Enter issue # to work on, "ack N" to acknowledge, "solve" for all internal issues, "all" for full details, or press Enter to skip:
+```
+
+**If user enters a number:**
+- Load the full issue details (title, URL, meta) for that index.
+- Determine routing:
+  - If the issue has `source_type: 'internal'` and `_route` metadata: use the `_route` value as the suggested action (example: unfinished quick task suggests `/qgsd:quick "original-slug"`, debug session suggests `/qgsd:debug --resume`)
+  - Otherwise, routing by severity:
+    - `severity: error` or `severity: bug` → suggest `/qgsd:debug`
+    - `severity: warning` or `severity: info` → suggest `/qgsd:quick`
+- Display:
+  ```
+  ◆ Issue: <title>
+    URL: <url>
+    Meta: <meta>
+
+  Suggested action: /qgsd:debug "<title> — <meta>"
+  Run it? [Y/n]
+  ```
+- If confirmed, invoke the suggested skill with the issue as context.
+
+**If user enters "solve":**
+- Collect all issues with `source_type: 'internal'`
+- Display: `Routing all internal issues to /qgsd:solve...`
+- Invoke `/qgsd:solve` to address all internal consistency issues at once
+
+**If user enters "ack N":**
+- Acknowledge the debt entry for issue #N (transition status from "open" to "acknowledged" via the debt state machine).
+- Display: `Acknowledged: <title>`
+
+**If user enters "all":**
+- Print the full metadata for each issue (title, URL, meta, created_at) as a numbered list.
+- Then re-prompt for a number.
+
+**If user presses Enter (blank):**
+```
+Observe complete. Run /qgsd:observe again when ready.
+```
+
+</process>

package/commands/qgsd/pause-work.md

@@ -0,0 +1,38 @@
+---
+name: qgsd:pause-work
+description: Create context handoff when pausing work mid-phase
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Create `.continue-here.md` handoff file to preserve complete work state across sessions.
+
+Routes to the pause-work workflow which handles:
+- Current phase detection from recent files
+- Complete state gathering (position, completed work, remaining work, decisions, blockers)
+- Handoff file creation with all context sections
+- Git commit as WIP
+- Resume instructions
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/pause-work.md
+</execution_context>
+
+<context>
+State and phase progress are gathered in-workflow with targeted reads.
+</context>
+
+<process>
+**Follow the pause-work workflow** from `@~/.claude/qgsd/workflows/pause-work.md`.
+
+The workflow handles all logic including:
+1. Phase directory detection
+2. State gathering with user clarifications
+3. Handoff file writing with timestamp
+4. Git commit
+5. Confirmation with resume instructions
+</process>

package/commands/qgsd/plan-milestone-gaps.md

@@ -0,0 +1,34 @@
+---
+name: qgsd:plan-milestone-gaps
+description: Create phases to close all gaps identified by milestone audit
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<objective>
+Create all phases necessary to close gaps identified by `/qgsd:audit-milestone`.
+
+Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase.
+
+One command creates all fix phases — no manual `/qgsd:add-phase` per gap.
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/plan-milestone-gaps.md
+</execution_context>
+
+<context>
+**Audit results:**
+Glob: .planning/milestones/v*-MILESTONE-AUDIT.md or .planning/v*-MILESTONE-AUDIT.md (use most recent)
+
+Original intent and current planning state are loaded on demand inside the workflow.
+</context>
+
+<process>
+Execute the plan-milestone-gaps workflow from @~/.claude/qgsd/workflows/plan-milestone-gaps.md end-to-end.
+Preserve all workflow gates (audit loading, prioritization, phase grouping, user confirmation, roadmap updates).
+</process>

package/commands/qgsd/plan-phase.md

@@ -0,0 +1,44 @@
+---
+name: qgsd:plan-phase
+description: Create detailed phase plan (PLAN.md) with verification loop
+argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify]"
+agent: qgsd-planner
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebFetch
+  - mcp__context7__*
+---
+<objective>
+Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification.
+
+**Default flow:** Research (if needed) → Plan → Verify → Done
+
+**Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn qgsd-planner, verify with qgsd-plan-checker, iterate until pass or max iterations, present results.
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/plan-phase.md
+@~/.claude/qgsd/references/ui-brand.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)
+
+**Flags:**
+- `--research` — Force re-research even if RESEARCH.md exists
+- `--skip-research` — Skip research, go straight to planning
+- `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
+- `--skip-verify` — Skip verification loop
+
+Normalize phase input in step 2 before any directory lookups.
+</context>
+
+<process>
+Execute the plan-phase workflow from @~/.claude/qgsd/workflows/plan-phase.md end-to-end.
+Preserve all workflow gates (validation, research, planning, verification loop, routing).
+</process>

package/commands/qgsd/polyrepo.md

@@ -0,0 +1,50 @@
+---
+name: qgsd:polyrepo
+description: Manage polyrepo groups — register repos that form one product for cross-repo QGSD awareness
+argument-hint: create | add <group> <path> [role] | remove <group> <path> | list [group] | info
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Manage named polyrepo groups — collections of repositories that together form one product. Supports creating groups, adding/removing repos, listing groups, and checking current repo membership.
+
+Global config: ~/.claude/polyrepos/<name>.json
+Per-repo marker: .planning/polyrepo.json
+</objective>
+
+<execution_context>
+Self-contained — no external workflow file needed.
+</execution_context>
+
+<process>
+Parse $ARGUMENTS for subcommand:
+
+**If no arguments or `create`:**
+Interactive flow using AskUserQuestion:
+1. Ask for group name (lowercase, alphanumeric + hyphens)
+2. Run `node bin/polyrepo.cjs create <name>` to create an empty group (calls `createGroup(name, [])`)
+3. Ask for repos to include (one at a time: path, role, planning yes/no)
+4. For each repo, run `node bin/polyrepo.cjs add <name> <path> <role> [--no-planning]` (calls `addRepo` per repo)
+5. Ask "Add another repo?" until user says no
+6. Display summary of created group
+
+**If `add <group> <path> [role]`:**
+Run `node bin/polyrepo.cjs add <group> <path> <role> [--no-planning]`
+If role not provided, ask via AskUserQuestion.
+
+**If `remove <group> <path>`:**
+Run `node bin/polyrepo.cjs remove <group> <path>`
+Confirm action.
+
+**If `list [group]`:**
+Run `node bin/polyrepo.cjs list [group]`
+Display formatted output.
+
+**If `info`:**
+Run `node bin/polyrepo.cjs info`
+Display current repo's group membership.
+</process>

package/commands/qgsd/progress.md

@@ -0,0 +1,24 @@
+---
+name: qgsd:progress
+description: Check project progress, show context, and route to next action (execute or plan)
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - SlashCommand
+---
+<objective>
+Check project progress, summarize recent work and what's ahead, then intelligently route to the next action - either executing an existing plan or creating the next one.
+
+Provides situational awareness before continuing work.
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/progress.md
+</execution_context>
+
+<process>
+Execute the progress workflow from @~/.claude/qgsd/workflows/progress.md end-to-end.
+Preserve all routing logic (Routes A through F) and edge case handling.
+</process>

package/commands/qgsd/queue.md

@@ -0,0 +1,54 @@
+---
+name: qgsd:queue
+description: Queue a skill or command to auto-invoke after the next /clear
+argument-hint: <command to queue, e.g. "/qgsd:quick --full">
+allowed-tools:
+  - Bash
+  - Write
+---
+
+<objective>
+Write a pending-task file so the specified command auto-invokes on the next user prompt
+after a `/clear`. Uses session-scoped file naming to prevent cross-session delivery.
+</objective>
+
+<process>
+1. Get the task from `$ARGUMENTS`. If empty, show usage and stop.
+
+2. Determine the session-scoped filename:
+   - Use `CLAUDE_SESSION_ID` env var if set, else use `CLAUDE_INSTANCE_ID`, else fall back to the generic name.
+   - Session-scoped: `.claude/pending-task-<sessionId>.txt`
+   - Generic fallback: `.claude/pending-task.txt`
+
+3. Write the task text to the file (create `.claude/` dir if needed).
+   Overwrite any existing pending task for this session.
+
+4. Confirm to the user:
+   ```
+   Queued: <task>
+   File:   .claude/pending-task-<sessionId>.txt (or pending-task.txt)
+
+   Now run /clear. Your next prompt will auto-invoke: <task>
+   ```
+
+5. Do NOT run the task now. Just write the file and confirm.
+</process>
+
+<implementation>
+Run this bash to determine the file path and write it:
+
+```bash
+SESSION_ID="${CLAUDE_SESSION_ID:-${CLAUDE_INSTANCE_ID:-}}"
+CLAUDE_DIR=".claude"
+mkdir -p "$CLAUDE_DIR"
+if [ -n "$SESSION_ID" ]; then
+  FILE="$CLAUDE_DIR/pending-task-$SESSION_ID.txt"
+else
+  FILE="$CLAUDE_DIR/pending-task.txt"
+fi
+printf '%s' '$ARGUMENTS' > "$FILE"
+echo "file=$FILE"
+```
+
+Then confirm to the user with the file path and next step.
+</implementation>

package/commands/qgsd/quick.md

@@ -0,0 +1,133 @@
+---
+name: qgsd:quick
+description: Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents
+argument-hint: "[--full]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking).
+
+Quick mode is the same system with a shorter path:
+- Spawns qgsd-planner (quick mode) + qgsd-executor(s)
+- Quick tasks live in `.planning/quick/` separate from planned phases
+- Updates STATE.md "Quick Tasks Completed" table (NOT ROADMAP.md)
+
+**Default:** Skips research, plan-checker, verifier. Use when you know exactly what to do.
+
+**`--full` flag:** Single-phase rigor tier. Enables:
+- Plan-checking (max 2 iterations) and post-execution verification
+- Formal scope scan: discovers relevant `.planning/formal/spec/*/invariants.md` and injects invariant context into the planner
+- Plan frontmatter must declare `formal_artifacts:` (none | update | create) with .planning/formal/ file targets
+- Executor commits .planning/formal/ files atomically when `formal_artifacts` is non-empty
+- Verifier checks invariant compliance and formal artifact syntax
+- Quorum reviews VERIFICATION.md after passing (can downgrade to "Needs Review")
+
+Use when you want quality guarantees with formal correctness properties, without full milestone ceremony.
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/quick.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+Context files are resolved inside the workflow (`init quick`) and delegated via `<files_to_read>` blocks.
+</context>
+
+<process>
+Execute the quick workflow from @~/.claude/qgsd/workflows/quick.md end-to-end.
+Preserve all workflow gates (validation, task description, planning, execution, state updates, commits).
+</process>
+
+## Verification Gap Auto-Proceed Override
+
+**Scope:** Applies only during Step 6.5 of the GSD quick workflow (post-execution verification, `$FULL_MODE` only). The `passed` and `human_needed` branches from the upstream workflow are unchanged.
+
+### Rule: gaps_found — auto-fix loop (replaces pause-and-ask)
+
+When Step 6.5 reaches `gaps_found` status, do NOT pause for user input and do NOT offer "accept as-is." Instead:
+
+**1. Display:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ QGSD ► GAPS FOUND — AUTO-FIX
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Verification found gaps. Spawning fix executor...
+```
+
+**2. Initialize iteration counter:** `$GAP_FIX_ITERATION = 1`. Max iterations = 2.
+
+**3. Spawn fix executor** with VERIFICATION.md and PLAN.md as context:
+
+```
+Task(
+  prompt="
+Fix gaps identified in verification.
+
+<files_to_read>
+- ${QUICK_DIR}/${next_num}-PLAN.md (Original plan)
+- ${QUICK_DIR}/${next_num}-VERIFICATION.md (Gaps to fix)
+- .planning/STATE.md (Project state)
+</files_to_read>
+
+<constraints>
+- Address only the gaps listed in VERIFICATION.md
+- Do not re-implement tasks already marked as passing
+- Commit fixes atomically using gsd-tools.cjs commit
+- Return the fix commit hash in your response (format: 'Fix Commit: {hash}')
+</constraints>
+",
+  subagent_type="qgsd-executor",
+  model="{executor_model}",
+  description="Fix gaps: ${DESCRIPTION}"
+)
+```
+
+**4. After fix executor returns, run quorum-test to verify gaps are closed:**
+
+Determine test scope from VERIFICATION.md artifacts. If test files exist (`*.test.js`, `*.test.ts`, etc.), call `/qgsd:quorum-test` with those files. If no test files are present (non-testable gaps), skip quorum-test and proceed directly to step 5 treating the result as PASS.
+
+Evaluate quorum-test consensus:
+
+| Verdict | Action |
+|---------|--------|
+| **PASS** | Gaps confirmed closed. Set `$VERIFICATION_STATUS = "Verified"`. Proceed to status update. |
+| **REVIEW-NEEDED** | Treat as passing (gap closure confirmed, concerns noted). Set `$VERIFICATION_STATUS = "Verified (Review Noted)"`. Proceed to status update. |
+| **BLOCK** | Gaps not resolved. If `$GAP_FIX_ITERATION < 2`, increment `$GAP_FIX_ITERATION` and repeat from step 3. |
+| **ALL models UNAVAILABLE** | Escalate to human. Display the unavailable-models banner (see below). Wait for human response. |
+
+**Unavailable-models banner:**
+
+```
+All quorum models unavailable — cannot verify gap closure automatically.
+Please manually verify and type "verified" to continue, or "skip" to record as Needs Review.
+```
+
+Set `$VERIFICATION_STATUS` based on human response ("verified" → "Verified", "skip" → "Needs Review").
+
+**5. If BLOCK after max iterations (2):** Set `$VERIFICATION_STATUS = "Gaps"`. Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ QGSD ► AUTO-FIX EXHAUSTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Max fix iterations reached. Quorum still reports gaps.
+
+Options:
+1. Provide guidance and retry: describe the issue
+2. Accept current state: type "accept"
+```
+
+Wait for human response.