@delete101020/aidlc 4.0.0

package/dist/templates/sdlc/profiles/agile-lite.yaml

@@ -0,0 +1,29 @@
+# SDLC compliance profile — `agile-lite` (GH-69)
+#
+# Lightweight rigor: user stories + testable acceptance criteria + every AC
+# covered by at least one test case. No full section coverage, no RTM.
+#
+# NOTE: mirrors the embedded manifest in
+# packages/core/src/profiles/StandardProfile.ts — keep the two in sync.
+id: agile-lite
+name: Agile-lite
+description: >-
+  Lightweight: user stories + testable acceptance criteria + every AC covered
+  by ≥1 test case. No full section coverage.
+anchors:
+  plan: User stories / ACs
+traceability:
+  enforce: true
+  rules:
+    - ac-testable   # ACs must be testable, not vague prose
+    - ac-has-test   # every AC covered by ≥1 test case (once test cases exist)
+phases:
+  plan:
+    persona: po
+    skills: [prd]
+  implement:
+    persona: developer
+    skills: [implement, unit-test]
+  execute-test:
+    persona: qa
+    skills: [execute-test, test-report]

package/dist/templates/sdlc/profiles/hybrid.yaml

@@ -0,0 +1,43 @@
+# SDLC compliance profile — `hybrid` (GH-69, recommended default for new projects)
+#
+# Anchors artifacts to standard names and enforces the full traceability chain
+# (AC → test case → result, RTM references resolve), but keeps presentation
+# lean — no mandatory ISO section coverage.
+#
+# NOTE: mirrors the embedded manifest in
+# packages/core/src/profiles/StandardProfile.ts — keep the two in sync.
+id: hybrid
+name: Hybrid (recommended)
+description: >-
+  Anchors artifacts to standard names and enforces the full traceability chain,
+  but keeps presentation lean.
+anchors:
+  plan: ISO/IEC/IEEE 29148
+  design: ISO/IEC/IEEE 1016 / 42010
+  test-plan: ISO/IEC/IEEE 29119
+traceability:
+  enforce: true
+  rules:
+    - ac-testable
+    - ac-has-test
+    - tc-has-result   # every test case has a recorded result (once report exists)
+    - rtm-no-dangling # RTM references resolve (once traceability.md exists)
+phases:
+  plan:
+    persona: po
+    skills: [prd]
+  design:
+    persona: tech-lead
+    skills: [tech-design]
+  test-plan:
+    persona: qa
+    skills: [test-plan]
+  implement:
+    persona: developer
+    skills: [implement, unit-test]
+  generate-test-cases:
+    persona: qa
+    skills: [generate-test-cases]
+  execute-test:
+    persona: qa
+    skills: [execute-test, test-report]

package/dist/templates/sdlc/profiles/iso-ieee.yaml

@@ -0,0 +1,67 @@
+# SDLC compliance profile — `iso-ieee` (GH-69)
+#
+# Full section coverage per ISO/IEC/IEEE 29148 (requirements) / 1016+42010
+# (design) / 29119 (testing), plus a mandatory RTM. For audit / compliance
+# teams that must certify artifacts against a named standard.
+#
+# NOTE: mirrors the embedded manifest in
+# packages/core/src/profiles/StandardProfile.ts — keep the two in sync.
+id: iso-ieee
+name: ISO/IEC/IEEE
+description: >-
+  Full section coverage per 29148 / 1016 / 29119 plus a mandatory RTM. For
+  audit / compliance teams.
+anchors:
+  plan: ISO/IEC/IEEE 29148
+  design: ISO/IEC/IEEE 1016 / 42010
+  test-plan: ISO/IEC/IEEE 29119
+traceability:
+  enforce: true
+  rules:
+    - ac-testable
+    - ac-has-test
+    - tc-has-result
+    - rtm-no-dangling
+    - mandatory-sections # each present artifact carries the profile's required sections
+artifacts:
+  PRD:
+    mandatory_sections:
+      - Problem & Goal
+      - User Flow
+      - Acceptance Criteria
+      - Non-Functional Requirements
+      - Dependencies
+    id_scheme:
+      req: REQ
+      ac: AC
+  TECH-DESIGN:
+    mandatory_sections:
+      - Architecture
+      - API
+      - Data Model
+    id_scheme:
+      des: DES
+  TEST-CASES:
+    mandatory_sections:
+      - Test Cases
+    id_scheme:
+      tc: TC
+phases:
+  plan:
+    persona: po
+    skills: [prd]
+  design:
+    persona: tech-lead
+    skills: [tech-design]
+  test-plan:
+    persona: qa
+    skills: [test-plan]
+  implement:
+    persona: developer
+    skills: [implement, unit-test]
+  generate-test-cases:
+    persona: qa
+    skills: [generate-test-cases]
+  execute-test:
+    persona: qa
+    skills: [execute-test, test-report]

package/dist/templates/sdlc/profiles/none.yaml

@@ -0,0 +1,21 @@
+# SDLC compliance profile — `none` (GH-69)
+#
+# Backward-compatible default. Nothing is enforced and no AIDLC persona/skill
+# opinion is composed. The structural/context layer (epic id + input paths +
+# artifact output path + gate contract) is STILL injected regardless of
+# profile, so artifacts land in docs/epics/<epic>/artifacts/ and the gate works.
+#
+# A workspace with no `standard:` key behaves exactly like this profile.
+#
+# NOTE: the built-in profiles are also embedded in
+# packages/core/src/profiles/StandardProfile.ts — keep the two in sync.
+id: none
+name: None (backward-compatible)
+description: >-
+  No opinion enforced and no AIDLC persona/skill composed. The
+  structural/context layer is still injected so artifacts land correctly.
+  Nothing is validated.
+traceability:
+  enforce: false
+  rules: []
+phases: {}

package/dist/templates/sdlc/skills/advance-epic.md

@@ -0,0 +1,77 @@
+---
+name: advance-epic
+description: Full-auto orchestrated run of the SDLC pipeline for an epic. The Orchestrator agent dispatches workers and stops at the human gates for approval. Runs plan → design ∥ test-plan → implement ∥ generate-test-cases → execute-test.
+argument-hint: <{{EPIC_PREFIX}}-XXXX> [--skip-gates]
+---
+
+# Advance Epic $0
+
+You are about to run the **full-auto orchestrator** for epic `$0`.
+
+## What this does
+
+The Orchestrator agent (loaded from `.claude/agents/orchestrator.md`) runs this loop until it hits a stopping condition:
+
+```
+next_step → dispatch worker → done? ─┬─ gate phase → pause for human approve/reject
+                                     └─ else → advance to next step
+```
+
+Stopping conditions:
+- ✅ `completed` — all phases through execute-test passed
+- 🔔 `paused_at_gate` — waiting for human approve/reject at a human gate
+- ⛔ `halted` — a worker couldn't finish after a retry, human must intervene
+
+## Prerequisites
+
+- `docs/epics/$0/epic.json` must exist with required fields (`epic_id`, `project`, `brief`, `affected_modules`).
+  - If missing: run `/epic $0` first to scaffold, or call the `init_epic` MCP tool, or edit `epic.json` by hand following `.claude/schemas/epic.schema.md`.
+- The MCP server `sdlc` (or whatever name you bound it to) must be configured in `.claude/settings.json`.
+
+## Steps
+
+1. **Verify epic.json exists.**
+   ```
+   Read docs/epics/$0/epic.json
+   ```
+   If not found → tell the user to run `/epic $0` first and STOP.
+
+2. **Check if affected_modules is populated.**
+   If the array is empty:
+   - Call MCP tool `list_project_modules` (with the workspace path) to see what modules the workspace defines under `docs/core-business/`.
+   - Show them to the user with a short blurb for each. If the list is empty, tell the user the orchestrator can still run but workers will only see the epic brief and upstream artifacts — they may want to populate `docs/core-business/` first.
+   - Ask the user to edit `epic.json` and list the modules this epic affects (or leave empty intentionally).
+   - STOP. Re-running `/advance-epic` after editing will continue.
+
+3. **Dispatch the Orchestrator agent** via the `Task` tool:
+   ```
+   subagent_type: orchestrator
+   prompt:
+     Run the full-auto SDLC loop for epic $0.
+     Workspace: <absolute path to the user's project root>
+     Skip gates: <true if "--skip-gates" present in arguments, else false>
+
+     Follow the core loop in your persona (.claude/agents/orchestrator.md).
+     Use the MCP tools: epic_status, phase_context, start_phase,
+     set_phase_status, reject_gate, amend_affected_modules.
+     Dispatch workers via the Task tool.
+
+     Stop when you hit completed, paused_at_gate, or halted. Return a
+     one-line summary of the stop reason.
+   ```
+
+4. **Relay the orchestrator's summary** back to the user. Do not add commentary.
+
+## If the user is running `/advance-epic` after approving a gate
+
+Just re-invoke step 3 — the orchestrator picks up from wherever `next_step` points.
+
+## If the user passes `--skip-gates`
+
+Set `skip_gates: true` in the dispatch prompt. The orchestrator will not pause at human gates; it advances every phase straight through to execute-test. Use this for hotfixes, not normal epics.
+
+## Anti-patterns (do not do in this skill)
+
+- ❌ Running workers directly here. The whole point of `/advance-epic` is to delegate to the Orchestrator.
+- ❌ Skipping the affected_modules check. Without it, context packaging is empty.
+- ❌ Bypassing the MCP tool set and writing `status.json` files by hand.

package/dist/templates/sdlc/skills/analyze-requirements.md

@@ -0,0 +1,279 @@
+---
+name: analyze-requirements
+description: Analyze requirements from a document, file, or URL — break them into detailed tasks and create them on Jira (auto), GitHub Issues, Linear, Redmine, or export locally.
+argument-hint: "<REQ-ID>"
+---
+
+# Analyze Requirements — $0
+
+You are a **Senior Business Analyst / Product Analyst** skilled at decomposing product requirements into sprint-sized, well-scoped engineering tasks.
+
+## Step 1 — Load context
+
+Read `docs/task-breakdowns/$0/inputs.json`. It contains:
+- `requirements_source` — file path (relative), URL (`http://…`), or `inline:<text>`
+- `task_platform` — `jira` | `github` | `linear` | `redmine` | `local`
+- `parent_task` — Jira epic key, GitHub repo, Linear project, etc. May be empty.
+- `detail_level` — `brief` or `detailed` (default: `detailed`)
+- `project_key` (optional) — Jira project key (e.g. `PROJ`)
+- `custom_instructions` (optional) — extra project-specific guidance for task creation (e.g. sprint assignments, naming conventions, post-creation actions)
+- `extra_projects` (optional) — JSON array of `{type, ref, label}` objects for additional codebases (local paths or GitHub repos) to cross-reference
+- `business_context` (optional) — inline text, URL, or Confluence/Notion page describing the company's domain, product strategy, and business rules
+- `its_context` (optional) — URL or reference to existing ITS issues (Jira project board, GitHub issues, Linear team) to check for duplicates and alignment
+
+## Step 2 — Read requirements
+
+- **File path** (no URL prefix): read from disk relative to project root
+- **URL** (`http://` or `https://`): fetch the page content
+- **Inline** (`inline:` prefix): use the text directly after `inline:`
+
+**Extra projects** (if `extra_projects` is non-empty): For each entry, briefly survey the project's structure:
+- Type `local`: read `README.md` and top-level directory listing
+- Type `github`: fetch `https://raw.githubusercontent.com/{ref}/HEAD/README.md` (or the repo's default branch)
+
+**Business context** (if `business_context` is non-empty): Read or fetch it and extract: product domain, core business rules, naming conventions, architectural constraints. Apply throughout analysis.
+
+**ITS context** (if `its_context` is non-empty): Fetch or query the issue tracker and note existing epics, open tickets, and in-progress work. Avoid duplicating existing issues in the task list.
+
+## Step 3 — Analyze and break down tasks
+
+Carefully analyze the requirements. For each task determine:
+
+| Field | Guidance |
+|---|---|
+| **Task ID** | Sequential `T-01`, `T-02`, … for internal dependency tracking |
+| **Title** | Action-oriented, ≤ 80 chars, starts with a verb |
+| **Type** | `Story` \| `Task` \| `Bug` \| `Spike` \| `Testing` |
+| **Priority** | `High` \| `Medium` \| `Low` |
+| **Description** | What needs to be built and why, from a user/product perspective |
+| **Acceptance Criteria** | Given/When/Then format, 3–7 per task, each independently testable (skip if `brief`) |
+| **Story Points** | Fibonacci (1, 2, 3, 5, 8, 13). Break anything >13 into sub-tasks. (skip if `brief`) |
+| **Labels** | Technical area: `frontend` \| `backend` \| `api` \| `database` \| `infra` \| `devops` \| `testing` \| `ux` \| `docs` |
+| **Depends on** | Task IDs this one requires first (empty if none) |
+
+**Cross-codebase impact** (if `extra_projects` is set): For tasks that touch interfaces shared across projects, add an explicit `Depends on` note or a separate integration task.
+
+**Business alignment** (if `business_context` is set): Each task's Description must explain how it aligns with the business context — avoid purely technical descriptions with no product rationale.
+
+**ITS deduplication** (if `its_context` is set): If a proposed task is essentially the same as an existing ITS issue, replace it with a reference to that issue (e.g. "→ Already tracked as PROJ-42") instead of creating a duplicate.
+
+**Custom instructions:** If `custom_instructions` is non-empty, read it carefully before generating any tasks. Apply it throughout — it may specify sprint targets, naming conventions, T-shirt sizing instead of story points, Jira labels to add, or actions to perform after creating each task. Follow the instructions literally.
+
+**Type assignment rules:**
+- Use `Testing` for tasks whose primary output is test cases, test scripts, QA verification, regression suites, or acceptance testing
+- Use `Story` for user-facing feature work
+- Use `Task` for technical/infrastructure work with no direct user story
+- Use `Bug` for fixing known defects
+- Use `Spike` for research/prototyping with a time-box
+
+**Scope rules:**
+- Keep tasks sprint-sized: 3–13 story points each
+- Every happy path needs a corresponding error/edge-case task or explicit AC
+- Do not duplicate — if a task already exists in the parent epic, note it and skip
+
+## Step 4 — Write local files (always first)
+
+Write these before any platform API calls.
+
+### `docs/task-breakdowns/$0/requirements.md`
+
+Save the **full original requirements content** here — whatever was fetched or provided in Step 2. If the source was a URL, include the URL and the fetched text. If inline, include the text as-is. This file is the source of truth so the breakdown can be reviewed and re-run without the original URL being reachable.
+
+```markdown
+# Requirements — $0
+
+**Source**: {requirements_source}
+**Fetched at**: {ISO timestamp}
+
+---
+
+{full requirements content as fetched/provided}
+```
+
+### `docs/task-breakdowns/$0/tasks.md`
+
+```markdown
+# Task Breakdown — $0
+
+**Source**: {requirements_source}
+**Target**: {task_platform}{parent note}
+**Detail**: {detail_level}
+
+## Summary
+
+{2-3 sentences: what the requirements cover, total scope, any assumptions or ambiguities}
+
+**Total tasks**: N | **Total story points**: SP
+
+---
+
+## Group: {Feature Area or Component}
+
+### T-01: {Title}
+- **Type**: Story | **Priority**: High | **Points**: 5 | **Labels**: backend, api
+- **Depends on**: —
+
+**Description**: {description — this text goes verbatim into the platform task description}
+
+**Acceptance Criteria**:
+- [ ] Given … When … Then …
+- [ ] Given … When … Then …
+
+---
+{repeat for each task}
+```
+
+### `docs/task-breakdowns/$0/tasks.json`
+
+```json
+[
+  {
+    "id": "T-01",
+    "title": "…",
+    "type": "Story",
+    "priority": "High",
+    "points": 5,
+    "labels": ["backend", "api"],
+    "description": "…",
+    "acceptance_criteria": ["Given … When … Then …"],
+    "depends_on": []
+  }
+]
+```
+
+## Step 5 — Handle empty `parent_task`
+
+If `parent_task` is empty or blank:
+1. Confirm the local files are written (Step 4 complete).
+2. Print the full task list clearly in the conversation.
+3. Ask the user:
+
+```
+📋 Task breakdown complete — $0
+
+I generated N tasks (SP story points total). Where would you like to create them?
+
+Options:
+  1. Jira  — provide an epic key (e.g. PROJ-100)
+  2. GitHub Issues — provide owner/repo (e.g. acme/myapp)
+  3. Linear — provide a project name or URL
+  4. Redmine — I'll generate a CSV for import
+  5. Local only — keep the tasks.md / tasks.json files as-is
+
+Reply with the number and your reference (e.g. "1 PROJ-100"), or "5" to keep locally.
+```
+
+Once the user replies, proceed with the corresponding platform section below.
+
+---
+
+## Step 6 — Create tasks on platform
+
+### Jira (`task_platform = "jira"`)
+
+**Step A — Add analysis as an epic comment**
+
+Use `addCommentToJiraIssue` on `parent_task` with the following body:
+
+```
+## Requirement Analysis — $0
+
+{full content of tasks.md summary section}
+
+**Generated tasks** (N total, SP story points):
+{list each task: "- T-01 [Story, High, 5pts]: Title"}
+
+Analysis file: docs/task-breakdowns/$0/tasks.md
+```
+
+**Step B — Create child issues**
+
+For each task in order:
+1. Call `createJiraIssue` with:
+   - `projectKey`: from `project_key` or derived from `parent_task` (e.g. `PROJ` from `PROJ-100`)
+   - `issueType`: map `Story→Story`, `Task→Task`, `Bug→Bug`, `Spike→Task`, `Testing→Test` (or `"Testing"` if `Test` is not available)
+   - `summary`: task Title (≤ 255 chars)
+   - `description`: full task Description + Acceptance Criteria formatted as plain text or ADF
+   - `priority`: task Priority
+2. After creating each issue, call `createIssueLink` to link it as a child of `parent_task`:
+   - Link type: `"is child of"` or `"Epic Link"` (whichever is available)
+3. After all issues are created, output a summary:
+
+```
+✅ Created N Jira issues under {parent_task}:
+  - PROJ-101 [Story]: Title
+  - PROJ-102 [Test]:  Title
+  …
+```
+
+If Atlassian MCP tools are not available: write `docs/task-breakdowns/$0/tasks-jira-import.csv` with columns:
+`Summary,Issue Type,Priority,Description,Story Points,Epic Link`
+
+Inform the user about the CSV and skip the comment step.
+
+---
+
+### GitHub Issues (`task_platform = "github"`)
+
+Parse `parent_task`: `owner/repo` or `owner/repo#N` (milestone number).
+
+For each task:
+1. Create a GitHub issue: `title` = task Title, `body` = Description + ACs in Markdown, `labels` = task Labels
+2. If a milestone number was given, assign it
+3. Report all created issue URLs
+
+If unavailable: write `docs/task-breakdowns/$0/tasks-github.md` with copy-paste issue bodies.
+
+---
+
+### Linear (`task_platform = "linear"`)
+
+Use Linear MCP tools if connected. Create issues under the project/cycle in `parent_task`, setting priority and estimate (story points).
+
+If unavailable: write `docs/task-breakdowns/$0/tasks-linear.json` in Linear import format.
+
+---
+
+### Redmine (`task_platform = "redmine"`)
+
+Write `docs/task-breakdowns/$0/tasks-redmine.csv`:
+
+```
+Subject,Tracker,Priority,Description,Parent issue #,Estimated hours
+{title},{Story→Feature/Task,Testing→Test,Bug→Bug},{priority},{description},{parent_task},{points * 2}
+```
+
+Inform the user to import via Redmine → Project → Issues → Import.
+
+---
+
+### Local (`task_platform = "local"`)
+
+Only the `tasks.md` and `tasks.json` from Step 4. No API calls needed.
+
+---
+
+## Step 7 — Final summary
+
+```
+✅ Requirement Analysis Complete — $0
+
+Source:   {requirements_source}
+Platform: {task_platform} / {parent_task or "local"}
+Tasks:    N ({SP} story points)
+
+{list of created issue keys/URLs — or "Local files only"}
+
+Files:
+  docs/task-breakdowns/$0/tasks.md
+  docs/task-breakdowns/$0/tasks.json
+```
+
+## Rules
+
+- **Always write local files (Step 4) before any API calls.** The user always has a local copy.
+- **Never fabricate issue keys or URLs.** Only report IDs returned by actual tool calls.
+- **If the MCP tool is unavailable**, fall back to the CSV/markdown export and say so clearly.
+- **Task description → platform description.** The Description field in each task goes directly into the platform issue's description — write it with that in mind (clear, complete, no references to "the requirement doc").
+- **Ambiguity stops creation.** If requirements are ambiguous enough to affect task scope, list the ambiguities and ask for clarification before creating platform issues.
+- **`brief` mode:** skip Acceptance Criteria and Story Points; all other fields remain.

package/dist/templates/sdlc/skills/discovery-gate.md

@@ -0,0 +1,118 @@
+---
+name: discovery-gate
+description: Human-in-the-loop discovery gate — when a phase accumulates open questions before it can produce a good artifact, turn them into a point-and-click questionnaire (DISCOVERY.md), open it in annotron, let the human answer/annotate, then resume the phase from the confirmed choices. Invoke via /discovery-gate <epic>. This is a gate any phase runs up front, NOT a separate phase.
+argument-hint: "<{{EPIC_PREFIX}}-XXXX>"
+---
+
+# /discovery-gate — confirm open questions before the phase commits
+
+The mirror image of `/annotate-artifact`. That skill reviews a *finished* artifact; this one
+runs at the **start** of a phase, when the agent has **open questions** it would otherwise ask
+one-at-a-time in chat or silently guess. Instead of inline questions, compose a questionnaire,
+let the human answer it point-and-click in annotron, and resume the phase from confirmed
+choices.
+
+**Discovery is not a separate phase.** It is a gate the calling phase runs up front (most often
+**Plan**, also **Design**). There is no `discovery` slash command in the pipeline, no
+`discovery` node, and `DISCOVERY.md` is a **working doc, never a `produces:` / `depends_on`
+artifact**. The durable output is a `## Discovery decisions` (Plan) / confirmed choices section
+written into the calling phase's real artifact (`PRD.md`, `TECH-DESIGN.md`, …).
+
+## When to invoke (the gate rule)
+
+Run this gate **instead of asking inline** when either is true:
+- there are **≥ 3 open questions** before you can write a good artifact, **or**
+- there is **any single high-impact question** — scope, architecture, or acceptance criteria.
+
+A small / clear epic that has no such questions **skips the gate entirely** — write the artifact
+directly, no annotron round. The agent can't truly self-trigger mid-thought; this is a
+documented rule the phase skill follows, not automatic behavior.
+
+## Tools
+
+Both ship with the AIDLC extension under `~/.claude/tools/` — no `python`, no `pip`, just
+`node` (the same tools `/annotate-artifact` uses):
+- Renderer: `R = node "$HOME/.claude/tools/md-to-html.mjs"`
+- annotron:  `A = node "$HOME/.claude/tools/annotron/bin/annotron"`
+
+Paths (relative to the open project): `ARTIFACTS = docs/epics/<epic>/artifacts`,
+`MD = $ARTIFACTS/DISCOVERY.md`, `HTML = $ARTIFACTS/DISCOVERY.html`.
+
+**MD-canonical rule (same as `/annotate-artifact`):** Markdown is the source; the `.html` is a
+throwaway render. Annotation feedback arrives as selectors/text on the rendered HTML, but you
+**always apply edits to `$MD`**, then re-render. Never edit the `.html`. Do NOT use annotron's
+bundled `/annotron` command — its step 3 edits the HTML, the wrong layer here.
+
+## Loop
+
+1. **Compose the questionnaire.** Write `$MD` — a `# Discovery — <epic>` doc where each open
+   question is its own `## Q<n>: <question>` section containing:
+   - a checkbox list of concrete options (`- [ ] Option A`, `- [ ] Option B`, …);
+   - an `- [ ] Other / notes:` line with a blank for freeform input;
+   - a `- [x] Decide for me` **default** the agent pre-ticks — so a human who just clicks
+     Finalize still resolves every question (you pick a sensible default and say so).
+
+   Keep questions decision-shaped and mutually exclusive where possible. Group by topic
+   (scope, users, data, density, edge cases, approach, boundaries). One question per behavior.
+
+2. **Render.** `$R --all "$ARTIFACTS"` (`--all` so cross-links between sibling artifacts
+   resolve `.md`→`.html`).
+
+3. **Open.** `$A "$HTML"` — starts the background server (if needed), registers the file, opens
+   the editor in the browser. Print the editor URL. Tell the user: turn on **Annotate**
+   (press `A`), tick the options they want / add notes on the "Other" lines, then **Send
+   feedback** — or just type a message. They can also edit checkboxes and Finalize; the
+   pre-ticked "Decide for me" defaults stand for anything they leave untouched.
+
+4. **Wait for feedback.** `$A poll "$HTML"` — blocks until the user sends. Output JSON:
+   - `items[]` — each `{ kind: element|text, selector, text, note }` (which option / note they
+     ticked or wrote);
+   - `message` — freeform message;
+   - `finalized: true` — the user clicked **Finalize** → go to step 6.
+   If it returns empty / times out with nothing, run it again.
+
+   **End signal (robust):** if `finalized` is true, OR the `message` is essentially just
+   "done" / "xong" / "finalize" / "close" / "stop" (with no `items`), the user is finished →
+   go to step 6. Tell the user up front they can end either way — clicking Finalize, or typing
+   "done" and Send.
+
+5. **Apply answers to `$MD` (never the `.html`, and ONLY this `.md`).** The poll feedback includes:
+   - **Text annotations** — user selected text to comment on
+   - **Form-control changes** — checkboxes, radios, selects, text inputs auto-captured when user interacts
+   - **Freeform message** — any message the user typed
+   
+   For each form-control item, update the corresponding control in DISCOVERY.md:
+   - **Checkbox**: tick `[x]` if value is true, clear `[ ]` if false
+   - **Radio/Select**: record the selected value
+   - **Text input**: record the input text
+   
+   For text annotations, find the matching question and record the user's note. Then re-render and re-arm:
+   - `$R --all "$ARTIFACTS"` — re-render; annotron live-reloads the browser.
+   - `$A poll "$HTML" --reply "<short summary of what you captured>"` — posts your reply and
+     re-arms the poll. Loop back to step 4.
+   **Scope:** during the loop edit ONLY `$MD`. Do not create/edit other files yet — the
+   resolved choices land in the calling phase's artifact in step 6.
+
+6. **Finalize — write `## Decisions` and hand back (do NOT re-arm).** When the end signal fires:
+   - Append a `## Decisions` section to `$MD` summarizing each resolved question → chosen answer
+     (one line each, including any "Decide for me" defaults that stood). This is the compact
+     hand-off the calling phase reads.
+   - **Do not call `poll` again** — `poll --reply` re-arms and would hang.
+   - Optionally `$A stop` to shut the annotron server.
+   - Return control to the calling phase with the resolved choices. The phase then writes them
+     into its **real artifact** — Plan → a `## Discovery decisions` section at the top of
+     `PRD.md`; Design → the confirmed approach/boundaries into `TECH-DESIGN.md` — and proceeds.
+
+## Guardrails
+
+- **`DISCOVERY.md` is a working doc, not a pipeline artifact.** Never add it to any step's
+  `produces:` / `depends_on`. The durable record is the calling phase's artifact section.
+- **Never edit `$HTML`.** Edits go in `$MD`; the render is derived.
+- **Only touch `$MD` during the loop.** The resolved decisions are written into the phase
+  artifact by the calling phase after this gate returns.
+- **Never edit while a poll is in flight** — wait for the feedback JSON first.
+- **Skippable.** If the gate rule doesn't fire (< 3 questions, none high-impact), don't compose
+  a questionnaire — write the artifact directly.
+- One questionnaire per gate. Re-invoke to open a fresh round.
+
+<!-- AIDLC annotation tool — reinstalled by AIDLC; hand edits are overwritten -->