refactor(conflict-engine): extract shared doc-conflict-engine reference

Move the BLOCKER/WARNING/INFO conflict report format, severity semantics,
and safety-gate behavior from workflows/import.md into a new shared
reference file. /gsd-import consumes the reference; behavior is unchanged
(all 13 import-command tests + full 4091-test suite pass).

Prepares for /gsd-ingest-docs (#2387) which will consume the same contract
with its own domain-specific check list. Prevents drift between the two
implementations.

Refs #2387

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jeremy McSpadden
2026-04-17 16:45:29 -05:00
parent 794f7e1b0b
commit 0b90150ebf
3 changed files with 98 additions and 36 deletions

View File

@@ -107,7 +107,7 @@ Extract from the imported content:
<step name="plan_conflict_detection">
Run conflict checks against the loaded project context. Output as a plain-text conflict report using [BLOCKER], [WARNING], and [INFO] labels. Do NOT use markdown tables (no `|---|` format).
Run conflict checks against the loaded project context. The report format, severity semantics, and safety-gate behavior are defined by `references/doc-conflict-engine.md` — read it and apply it here. Operation noun: `import`.
### BLOCKER checks (any one prevents import):
@@ -128,45 +128,15 @@ Run conflict checks against the loaded project context. Output as a plain-text c
- Plan uses a library not currently in the project tech stack → [INFO]
- Plan adds a new phase to the ROADMAP.md structure → [INFO]
Display the full Conflict Detection Report:
Render the full Conflict Detection Report using the format in `references/doc-conflict-engine.md`.
```
## Conflict Detection Report
### BLOCKERS ({N})
[BLOCKER] {Short title}
Found: {what the imported plan says}
Expected: {what project context requires}
→ {Specific action to resolve}
### WARNINGS ({N})
[WARNING] {Short title}
Found: {what was detected}
Impact: {what could go wrong}
→ {Suggested action}
### INFO ({N})
[INFO] {Short title}
Note: {relevant information}
```
**If any [BLOCKER] exists:**
Display:
```
GSD > BLOCKED: {N} blockers must be resolved before import can proceed.
```
Exit WITHOUT writing any files. This is the safety gate — no PLAN.md is written when blockers exist.
**If any [BLOCKER] exists:** apply the safety gate from the reference — exit WITHOUT writing any files. No PLAN.md is written when blockers exist.
**If only WARNINGS and/or INFO (no blockers):**
**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
Ask via AskUserQuestion using the approve-revise-abort pattern:
Ask via AskUserQuestion using the approve-revise-abort pattern (see `references/gate-prompts.md`):
- question: "Review the warnings above. Proceed with import?"
- header: "Approve?"
- options: Approve | Abort
@@ -267,7 +237,7 @@ Show: plan filename written, phase directory, validation result, next steps.
## Anti-Patterns
Do NOT:
- Use markdown tables (`|---|`) in the conflict detection report — use plain-text [BLOCKER]/[WARNING]/[INFO] labels
- Violate the shared conflict-engine contract in `references/doc-conflict-engine.md` (no markdown tables, no new severity labels, no bypass of the BLOCKER gate)
- Write PLAN.md files as `PLAN-01.md` or `plan-01.md` — always use `{NN}-{MM}-PLAN.md`
- Use `pbr:plan-checker` or `pbr:planner` — use `gsd-plan-checker` and `gsd-planner`
- Write `.planning/.active-skill` — this is a PBR pattern with no GSD equivalent