@hanzlaa/rcode 2.1.0

package/rihal/workflows/import.md

@@ -0,0 +1,306 @@
+# Import Workflow
+
+External plan ingestion with conflict detection and agent delegation.
+
+- **--from**: Import external plan → conflict detection → write SPRINT.md → validate via rihal-sprint-checker
+
+Future: `--prd` mode (PRD extraction into PROJECT.md + REQUIREMENTS.md + ROADMAP.md) is planned for a follow-up PR.
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+- Print the usage block below
+- STOP — do not proceed
+
+**Usage:**
+```
+/rihal:import --from <path>
+```
+
+**Examples:**
+```
+/rihal:import --from ./external-plan.md
+/rihal:import --from ../other-project/SPRINT.md
+```
+
+---
+
+<step name="banner">
+
+Display the stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► IMPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+</step>
+
+<step name="parse_arguments">
+
+Parse `$ARGUMENTS` to determine the execution mode:
+
+- If `--from` is present: extract FILEPATH (the next token after `--from`), set MODE=plan
+- If `--prd` is present: display message that `--prd` is not yet implemented and exit:
+  ```
+  RIHAL > --prd mode is planned for a future release. Use --from to import plan files.
+  ```
+- If neither flag is found: display usage and exit:
+
+```
+Usage: /rihal:import --from <path>
+
+  --from <path>   Import an external plan file into Rihal format
+```
+
+**Validate the file path:**
+
+Verify the path does not contain traversal sequences and the file exists:
+
+```bash
+case "{FILEPATH}" in
+  *..* ) echo "SECURITY_ERROR: path contains traversal sequence"; exit 1 ;;
+esac
+test -f "{FILEPATH}" || echo "FILE_NOT_FOUND"
+```
+
+If FILE_NOT_FOUND: display error and exit:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+File not found: {FILEPATH}
+
+**To fix:** Verify the file path and try again.
+```
+
+</step>
+
+---
+
+## Path A: MODE=plan (--from)
+
+<step name="plan_load_context">
+
+Load project context for conflict detection:
+
+1. Read `.planning/ROADMAP.md` — extract phase structure, phase numbers, dependencies
+2. Read `.planning/PROJECT.md` — extract project constraints, tech stack, scope boundaries.
+   **If PROJECT.md does not exist:** skip constraint checks that rely on it and display:
+   ```
+   RIHAL > Note: No PROJECT.md found. Conflict checks against project constraints will be skipped.
+   ```
+3. Read `.planning/REQUIREMENTS.md` — extract existing requirements for overlap and contradiction checks.
+   **If REQUIREMENTS.md does not exist:** skip requirement conflict checks and continue.
+4. Glob for all CONTEXT.md files across phase directories:
+   ```bash
+   find .planning/phases/ -name "*-CONTEXT.md" -o -name "CONTEXT.md" 2>/dev/null
+   ```
+   Read each CONTEXT.md found — extract locked decisions (any decision in a `<decisions>` block)
+
+Store loaded context for conflict detection in the next step.
+
+</step>
+
+<step name="plan_read_input">
+
+Read the imported file at FILEPATH.
+
+Determine the format:
+- **RIHAL SPRINT.md format**: Has YAML frontmatter with `phase:`, `plan:`, `type:` fields
+- **Freeform document**: Any other format (markdown spec, design doc, task list, etc.)
+
+Extract from the imported content:
+- **Phase target**: Which phase this plan belongs to (from frontmatter or inferred from content)
+- **Plan objectives**: What the plan aims to accomplish
+- **Tasks listed**: Individual work items described in the plan
+- **Files modified**: Any files mentioned as targets
+- **Dependencies**: Any referenced prerequisites
+
+</step>
+
+<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).
+
+### BLOCKER checks (any one prevents import):
+
+- Plan targets a phase number that does not exist in ROADMAP.md → [BLOCKER]
+- Plan specifies a tech stack that contradicts PROJECT.md constraints → [BLOCKER]
+- Plan contradicts a locked decision in any CONTEXT.md `<decisions>` block → [BLOCKER]
+- Plan contradicts an existing requirement in REQUIREMENTS.md → [BLOCKER]
+
+### WARNING checks (user confirmation required):
+
+- Plan partially overlaps existing requirement coverage in REQUIREMENTS.md → [WARNING]
+- Plan has `depends_on` referencing plans that are not yet complete → [WARNING]
+- Plan modifies files that overlap with existing incomplete plans → [WARNING]
+- Plan phase number conflicts with existing phase numbering in ROADMAP.md → [WARNING]
+
+### INFO checks (informational, no action needed):
+
+- 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:
+
+```
+## 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:
+```
+RIHAL > BLOCKED: {N} blockers must be resolved before import can proceed.
+```
+
+Exit WITHOUT writing any files. This is the safety gate — no SPRINT.md is written when blockers exist.
+
+**If only WARNINGS and/or INFO (no blockers):**
+
+Ask via AskUserQuestion using the approve-revise-abort pattern:
+- question: "Review the warnings above. Proceed with import?"
+- header: "Approve?"
+- options: Approve | Abort
+
+If user selects "Abort": exit cleanly with message "Import cancelled."
+
+</step>
+
+<step name="plan_convert">
+
+Convert the imported content to RIHAL SPRINT.md format.
+
+Ensure the SPRINT.md has all required frontmatter fields:
+```yaml
+---
+phase: "{NN}-{slug}"
+plan: "{NN}-{MM}"
+type: "feature|refactor|config|test|docs"
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+must_haves:
+  truths: []
+  artifacts: []
+---
+```
+
+**Reject PBR naming conventions in source content:**
+If the imported plan references PBR plan naming (e.g., `PLAN-01.md`, `plan-01.md`), rename all references to RIHAL `{NN}-{MM}-SPRINT.md` convention during conversion.
+
+Apply RIHAL naming convention for the output filename:
+- Format: `{NN}-{MM}-SPRINT.md` (e.g., `04-01-SPRINT.md`)
+- NEVER use `PLAN-01.md`, `plan-01.md`, or any other format
+- NN = phase number (zero-padded), MM = plan number within the phase (zero-padded)
+
+Determine the target directory:
+```
+.planning/phases/{NN}-{slug}/
+```
+
+If the directory does not exist, create it:
+```bash
+mkdir -p ".planning/phases/{NN}-{slug}/"
+```
+
+Write the SPRINT.md file to the target directory.
+
+</step>
+
+<step name="plan_validate">
+
+Delegate validation to rihal-sprint-checker:
+
+```
+Task({
+  subagent_type: "rihal-sprint-checker",
+  prompt: "Validate: .planning/phases/{phase}/{plan}-SPRINT.md — check frontmatter completeness, task structure, and RIHAL conventions. Report any issues."
+})
+```
+
+If the checker returns errors:
+- Display the errors to the user
+- Ask the user to resolve issues before the plan is considered imported
+- Do not delete the written file — the user can fix and re-validate manually
+
+If the checker returns clean:
+- Display: "Plan validation passed"
+
+</step>
+
+<step name="plan_finalize">
+
+Update `.planning/ROADMAP.md` to reflect the new plan:
+- Add the plan to the Plans list under the correct phase section
+- Include the plan name and description
+
+Update `.planning/STATE.md` if appropriate (e.g., increment total plan count).
+
+Commit the imported plan and updated files:
+```bash
+node "$HOME/.rihal/bin/rihal-tools.cjs" commit "docs({phase}): import plan from {basename FILEPATH}" --files .planning/phases/{phase}/{plan}-SPRINT.md .planning/ROADMAP.md
+```
+
+Display completion:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► IMPORT COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Show: plan filename written, phase directory, validation result, next steps.
+
+</step>
+
+---
+
+## Anti-Patterns
+
+Do NOT:
+- Use markdown tables (`|---|`) in the conflict detection report — use plain-text [BLOCKER]/[WARNING]/[INFO] labels
+- Write SPRINT.md files as `PLAN-01.md` or `plan-01.md` — always use `{NN}-{MM}-SPRINT.md`
+- Use `pbr:sprint-checker` or `pbr:planner` — use `rihal-sprint-checker` and `rihal-planner`
+- Write `.planning/.active-skill` — this is a PBR pattern with no RIHAL equivalent
+- Reference `pbr-tools`, `pbr:`, or `PLAN-BUILD-RUN` anywhere
+- Write any SPRINT.md file when blockers exist — the safety gate must hold
+- Skip path validation on the --from file argument
+
+## Success Criteria
+
+- [ ] Task completed as requested
+- [ ] Output saved or reported
+- [ ] State updated if necessary
+- [ ] No errors encountered
+
+## On Error
+
+If arguments are invalid, missing files, or subagent fails:
+- Validate inputs match expected format
+- Check that required files exist
+- Retry with clearer arguments or report the specific error to the user
+