@sushanglewis/lincoln 1.5.0 → 1.5.1

package/framework/.claude/schemas/stage-definition.schema.json

@@ -0,0 +1,233 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lincoln-framework.dev/schemas/stage-definition.schema.json",
+  "title": "Lincoln Stage Definition Schema",
+  "description": "Validates a single Lincoln stage YAML file under .claude/stages/.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "id",
+    "name",
+    "description",
+    "templates",
+    "prerequisite_stage",
+    "next_stage",
+    "human_gate",
+    "agent",
+    "skills",
+    "artifacts",
+    "context",
+    "gates"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of the stage schema"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Kebab-case stage identifier"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable stage name"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "What this stage does and when it is triggered"
+    },
+    "templates": {
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": ["all"],
+          "description": "This stage applies to all workflow templates"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "minItems": 1,
+          "description": "List of workflow template IDs that include this stage"
+        }
+      ]
+    },
+    "prerequisite_stage": {
+      "oneOf": [
+        { "type": "string", "pattern": "^[a-z][a-z0-9-/]*$" },
+        { "type": "null" }
+      ],
+      "description": "Stage that must complete before this one, or null for entry stages"
+    },
+    "next_stage": {
+      "oneOf": [
+        { "type": "string", "pattern": "^[a-z][a-z0-9-/]*$" },
+        { "type": "null" }
+      ],
+      "description": "Stage that follows this one, or null for terminal stages"
+    },
+    "human_gate": {
+      "type": "boolean",
+      "description": "Whether human approval is required to exit this stage"
+    },
+    "agent": {
+      "type": "object",
+      "required": ["primary"],
+      "properties": {
+        "primary": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Primary agent role for this stage"
+        },
+        "reviewers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "default": [],
+          "description": "Optional reviewer agent roles"
+        },
+        "handoff_to": {
+          "oneOf": [
+            { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            { "type": "null" }
+          ],
+          "description": "Agent role to hand off to at stage end"
+        }
+      },
+      "additionalProperties": false
+    },
+    "skills": {
+      "type": "object",
+      "required": ["required"],
+      "properties": {
+        "required": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)*$"
+          },
+          "default": [],
+          "description": "Skills that must be available for this stage"
+        },
+        "optional": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)*$"
+          },
+          "default": [],
+          "description": "Skills that may be used but are not mandatory"
+        }
+      },
+      "additionalProperties": false
+    },
+    "artifacts": {
+      "type": "object",
+      "required": ["required"],
+      "properties": {
+        "required": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "default": [],
+          "description": "Path templates for artifacts that must be produced"
+        },
+        "optional": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "default": [],
+          "description": "Path templates for optional artifacts"
+        }
+      },
+      "additionalProperties": false
+    },
+    "context": {
+      "type": "object",
+      "required": ["goal"],
+      "properties": {
+        "goal": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What the agent should achieve in this stage"
+        },
+        "entry": {
+          "type": "string",
+          "description": "Checks and preparation before stage execution"
+        },
+        "execution": {
+          "type": "string",
+          "description": "How to perform the stage work"
+        },
+        "exit": {
+          "type": "string",
+          "description": "AI-evaluable criteria for completing the stage"
+        },
+        "constraints": {
+          "type": "string",
+          "description": "Additional constraints and guardrails"
+        }
+      },
+      "additionalProperties": false
+    },
+    "gates": {
+      "type": "object",
+      "properties": {
+        "entry": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/gateCheck" },
+          "default": []
+        },
+        "exit": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/gateCheck" },
+          "default": []
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "gateCheck": {
+      "type": "object",
+      "required": ["check"],
+      "properties": {
+        "check": {
+          "type": "string",
+          "enum": [
+            "file_exists",
+            "artifact_exists",
+            "artifacts_present",
+            "audio_format_supported",
+            "previous_stage_completed",
+            "human_approved",
+            "gate_review_passed",
+            "handoff_contract_valid",
+            "handoff_versions_match",
+            "prd_has_required_sections",
+            "prd_snapshot_present"
+          ]
+        },
+        "args": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": []
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/framework/.claude/schemas/workflow-stage.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lincoln-framework.dev/schemas/workflow-stage.schema.json",
+  "title": "Lincoln Workflow Stage State Schema",
+  "description": "Validates branch-scoped workflow-stage.yaml files that track stage progression in append-only node history.",
+  "type": "object",
+  "required": ["schema_version", "workflow", "current_run", "nodes"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "workflow": {
+      "type": "object",
+      "required": ["name", "version", "template"],
+      "properties": {
+        "name": { "type": "string" },
+        "version": { "type": "string" },
+        "template": { "type": "string" }
+      }
+    },
+    "current_run": {
+      "type": "object",
+      "required": ["run_id", "branch", "current_stage", "status", "variables"],
+      "properties": {
+        "run_id": { "type": "string" },
+        "branch": { "type": "string" },
+        "current_stage": { "type": "string" },
+        "status": {
+          "type": "string",
+          "enum": ["not_started", "in_progress", "paused", "waiting_for_human", "validation_failed", "completed"]
+        },
+        "started_at": { "type": "string" },
+        "last_updated_at": { "type": "string" },
+        "issue_number": { "type": "string" },
+        "execution_mode": { "type": "string", "enum": ["solo", "team"] },
+        "variables": {
+          "type": "object",
+          "properties": {
+            "session_id": { "type": "string" },
+            "design_id": { "type": "string" },
+            "change_name": { "type": "string" },
+            "issue_number": { "type": "string" },
+            "pr_number": { "type": "string" },
+            "feature_slug": { "type": "string" }
+          }
+        }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/nodeEntry" }
+    },
+    "recovery": {
+      "type": "object",
+      "properties": {
+        "last_validated_checkpoint": { "type": "string" },
+        "can_resume_from": { "type": "string" },
+        "abort_reason": { "type": ["string", "null"] },
+        "abort_at": { "type": ["string", "null"] }
+      }
+    }
+  },
+  "definitions": {
+    "nodeEntry": {
+      "type": "object",
+      "required": ["node_id", "status"],
+      "properties": {
+        "node_id": { "type": "string" },
+        "status": {
+          "type": "string",
+          "enum": ["not_started", "in_progress", "paused", "waiting_for_human", "validation_failed", "completed", "pr_submitted", "merged"]
+        },
+        "started_at": { "type": "string" },
+        "completed_at": { "type": "string" },
+        "handoff_file": { "type": "string" },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "gate_passed": { "type": "boolean" },
+        "approved_by": { "type": "string" }
+      }
+    }
+  }
+}

package/framework/.claude/schemas/workflow-template.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lincoln-framework.dev/schemas/workflow-template.schema.json",
+  "title": "Lincoln Workflow Template Schema",
+  "description": "Validates workflow template YAML files under .claude/workflows/.",
+  "type": "object",
+  "required": ["workflow"],
+  "properties": {
+    "workflow": {
+      "type": "object",
+      "required": ["name", "version", "description", "execution_mode", "steps"],
+      "properties": {
+        "name": { "type": "string" },
+        "version": { "type": "string" },
+        "description": { "type": "string" },
+        "execution_mode": { "type": "string", "enum": ["solo", "team"] },
+        "engine": { "type": "string" },
+        "loop": {
+          "type": "object",
+          "properties": {
+            "engine": { "type": "string" },
+            "state_file": { "type": "string" },
+            "on_failure": { "type": "string" },
+            "max_retries": { "type": "integer" }
+          }
+        },
+        "conventions": {
+          "type": "object",
+          "properties": {
+            "language": { "type": "string" },
+            "artifact_encoding": { "type": "string" },
+            "timestamp_format": { "type": "string" },
+            "session_id_pattern": { "type": "string" }
+          }
+        },
+        "steps": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/step" }
+        },
+        "gates": {
+          "type": "object",
+          "properties": {
+            "human_confirmation_prompt": { "type": "string" },
+            "on_validation_failure": { "type": "string" },
+            "on_human_rejection": { "type": "string" }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "step": {
+      "type": "object",
+      "required": ["id", "name", "description"],
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "entry_checks": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/check" }
+        },
+        "exit_checks": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/check" }
+        },
+        "action": { "type": "string" },
+        "human_gate": { "type": "boolean" },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "trigger": { "type": "string" }
+      }
+    },
+    "check": {
+      "type": "object",
+      "required": ["check"],
+      "properties": {
+        "check": { "type": "string" },
+        "args": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/framework/.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": ".claude/hooks/on-session-start.sh",
+    "Stop": ".claude/hooks/on-stop.sh",
+    "PreToolUse": ".claude/hooks/pre-tool-use.sh",
+    "PostToolUse": ".claude/hooks/post-tool-use.sh"
+  },
+  "lincoln": {
+    "state_file": "<process_slug>/workflow-stage.yaml",
+    "legacy_state_file": ".claude/workflow-state.yaml",
+    "auto_install_dependencies": false,
+    "dependency_check_on_startup": true
+  }
+}

package/framework/.claude/skills/build-product-prototype/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: build-product-prototype
+description: 基于已确认设计文档生成字段、界面规格和 Pencil 原型
+triggers:
+  - "生成产品原型"
+  - "build-product-prototype"
+inputs:
+  - name: session_id
+    description: 访谈会话 ID
+    required: true
+  - name: design_id
+    description: 产品设计 ID
+    required: true
+outputs:
+  - "{process_slug}/pages/docs/fields.html"
+  - "{process_slug}/pages/docs/ui-spec.html"
+  - "{process_slug}/designs/{design_id}/prototype.pen"
+  - "{process_slug}/pages/prototype/**/*.html"
+required_tools:
+  - Read
+  - Bash
+  - Write
+  - mcp__pencil__batch_design
+---
+
+# build-product-prototype
+
+## Purpose
+
+Using [build-product-prototype] to 基于已确认设计文档生成字段、界面规格和 Pencil 原型.
+
+
+基于已确认设计文档生成字段规格、UI 规格和 Pencil 原型。
+
+运行入口： prompts/main.md

package/framework/.claude/skills/build-product-prototype/prompts/main.md

@@ -0,0 +1,78 @@
+# build-product-prototype
+
+You are executing the Lincoln workflow step `product-prototype`: turn approved product design documents into UI/field specifications and an interactive HTML prototype.
+
+## Goal
+
+Create field and UI specifications as HTML doc pages, and produce a high-fidelity interactive HTML prototype that the PM can inspect directly in the issue-package portal (`{process_slug}/index.html`). A Pencil prototype is optional; the HTML prototype is the primary review artifact.
+
+## Reference templates
+
+Use the following read-only templates as the style/layout reference. Copy/adapt them into the issue package; do not modify the templates themselves.
+
+- `.claude/templates/issue-package/page-prototype.html.tpl` — minimal starter page with theme sync support.
+- `.claude/templates/issue-package/prototypes/app/main/page.html.tpl` — main app window with sidebar + WebView placeholder.
+- `.claude/templates/issue-package/prototypes/app/onboarding/page.html.tpl` — login/onboarding card.
+- `.claude/templates/issue-package/prototypes/app/settings/page.html.tpl` — two-column settings page.
+- `.claude/templates/issue-package/prototypes/app/overlays/page.html.tpl` — avatar menu / about / toast overlays.
+- `.claude/templates/issue-package/prototypes/app/tray/page.html.tpl` — system-tray scenario controller. When the product has a macOS menubar presence, create thin scenario pages under `pages/prototype/app/tray/` showing at minimum: default state, unread-badge state, and menu-open state. These pages must **not** redraw the tray inside the app prototype; instead they send `postMessage({type:'lincoln-tray-state', unread:<int>, open:<bool>}, '*')` to the portal so the portal-level macOS tray updates. See the tray template for the exact snippet.
+- `.claude/templates/issue-package/prototypes/app/org/page.html.tpl` — organization list.
+- `.claude/templates/issue-package/prototypes/web/dashboard/page.html.tpl` — web dashboard shell.
+- `.claude/templates/issue-package/prototypes/web/list/page.html.tpl` — web list view shell.
+- `.claude/templates/issue-package/prototypes/web/form/page.html.tpl` — web form shell.
+- `.claude/templates/issue-package/prototypes/web/detail/page.html.tpl` — web detail shell.
+- `.claude/templates/issue-package/prototypes/mobile/home/page.html.tpl` — mobile home feed shell.
+- `.claude/templates/issue-package/prototypes/mobile/chat/page.html.tpl` — mobile chat shell.
+- `.claude/templates/issue-package/prototypes/mobile/settings/page.html.tpl` — mobile settings list shell.
+- `.claude/templates/issue-package/prototypes/mobile/profile/page.html.tpl` — mobile profile shell.
+- `.claude/templates/issue-package/assets/prototype.css` — shared styles (tokens, dark mode, window shell, sidebar, forms, overlays, web/mobile shells).
+- `.claude/templates/issue-package/assets/prototype.js` — shared UI builders and mock data (`window.LincolnPrototype`), including `frameApp`, `frameWeb`, `frameMobile`.
+
+## Input
+
+- `session_id`: the interview session identifier
+- `design_id`: the product design identifier
+
+## Steps
+
+1. Verify `{process_slug}/pages/docs/design-review.html` contains `<!-- status: approved -->` or `[x] PM 已确认设计文档`.
+2. Read the approved design package under `{process_slug}/pages/docs/`, including `flows.html` and `page-map.html`.
+3. Write `{process_slug}/pages/docs/fields.html` using `.claude/templates/issue-package/page-doc.html.tpl` with screen/form fields, data type, required/optional status, validation, default value, copy, error state, and source data object.
+4. Write `{process_slug}/pages/docs/ui-spec.html` covering the interaction-document delivery standards:
+   - 用户场景与流程: who, when, goal, trigger, completion criteria.
+   - 界面流转图: screen-to-screen flow mapped to the business flow in `flows.html`.
+   - 页面交互说明: per-screen layout elements, interaction rules (events, responses, navigation), and field validation/error handling.
+   - 交互 Demo/原型: links to the HTML prototype pages under `pages/prototype/` and a summary of key interactions.
+5. **Plan prototype generation granularity.** Before writing prototype pages, list every screen from `flows.html` and `page-map.html`. Group them into cohesive clusters (e.g. onboarding, main shell, settings, overlays, tray). Generate one cluster at a time. After each cluster, verify that every page in the cluster has complete annotation meta tags before starting the next cluster. This prevents agent context exhaustion and keeps each page's documentation and interactions complete.
+6. Create interactive HTML prototypes under `{process_slug}/pages/prototype/{app,web,mobile}/` by adapting the reference templates above. Pick the right shell (`frameApp`, `frameWeb`, or `frameMobile`) from `LincolnPrototype.ui` for the product form-factor. Every page must:
+   - Link to `../../../assets/prototype.css` and `../../../assets/prototype.js` (depth 3) or `../../../../assets/...` (depth 4) depending on its path.
+   - Include the theme sync IIFE shown in the starter template.
+   - Include `<meta name="prototype-base" content="../../../">` (or `../../../../` for depth 4).
+   - Include `<meta name="page-uid" content="...">`, `<meta name="nav-group" content="...">`, and `<meta name="nav-label" content="...">` with a short Chinese label for the left nav.
+   - Include the annotation meta tags `doc-purpose`, `doc-layout`, `doc-fields`, `doc-boundaries`, `doc-exceptions`. Also include `doc-stories`, `doc-rules`, `doc-refs` when they add clarity, so the portal right panel explains functionality, layout, fields, boundary cases, and exception flows.
+   - Use `LincolnPrototype.ui` builders and `prototype.css` tokens for every visual element so both light and dark themes render correctly; verify both themes by toggling the portal theme switch.
+   - Assign a stable `data-uid` attribute to every interactive element, screen region, and WebView placeholder.
+   - Override `LincolnPrototype.data` in the page script for issue-specific mock data (user, org, webviews, settings, unread items).
+7. Optionally create or update `{process_slug}/designs/<design_id>/prototype.pen` with Pencil tools if the PM explicitly asks for a Pencil prototype. If you use Pencil tools, call `get_editor_state(include_schema: true)` first and use `snapshot_layout` to check for clipping/overlap.
+8. Update the root `{process_slug}/pages/docs/prd.html` section 9 "相关产物链接" with the `ui-spec.html`, `fields.html`, and HTML prototype links. If the PRD already has an approved snapshot, warn the PM that changes require a version bump and re-freeze via `python scripts/lincoln_prd.py freeze`.
+9. Ask the PM to open `{process_slug}/index.html` in a browser, toggle the theme switch in the macOS menubar, and review both light and dark renderings of each prototype page inside the portal.
+10. When the PM confirms the prototype, add `<!-- prototype-status: approved -->` to `ui-spec.html`.
+11. Run `python scripts/stage_loader.py --stage product-prototype --action record-artifacts`.
+
+## Output Artifacts
+
+- `{process_slug}/pages/docs/fields.html`
+- `{process_slug}/pages/docs/ui-spec.html`
+- `{process_slug}/pages/prototype/**/*.html` (required interactive HTML prototypes)
+- `{process_slug}/designs/<design_id>/prototype.pen` (optional Pencil prototype)
+
+## Rules
+
+- The HTML prototype is the primary review artifact; Pencil is optional.
+- Always reuse the shared `prototype.css` and `prototype.js` assets. Do not inline all styles or rebuild the component library from scratch.
+- Keep controls and states complete enough for implementation: default, hover/focus where relevant, disabled, empty, loading, error, and success.
+- Every interactive element must carry a stable `data-uid`. Do not generate random UIDs that change on every render.
+- Prototype links use relative paths so they work both inside the portal iframe and when opened standalone.
+- Do not add collapse toggles or custom panel chrome to the portal; the right annotation panel is always visible.
+- The system tray is portal-level chrome. Never redraw the tray inside an app prototype page with `.menubar`, `.tray-icon`, `.tray-panel`, `bindTray`, or `trayMenu`. Tray scenario pages must be thin controllers that post `lincoln-tray-state` messages to the portal.
+- After approval, tell the user to run: `claude plan-tdd-development <session_id> <design_id>`.

package/framework/.claude/skills/clarify-requirements/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: clarify-requirements
+description: 基于访谈内容与人类 PM 多轮澄清需求
+triggers:
+  - "澄清需求"
+  - "clarify-requirements"
+inputs:
+  - name: session_id
+    description: 访谈会话 ID，如 2026-06-27-stakeholder
+    required: true
+outputs:
+  - "{process_slug}/pages/docs/requirements.html"
+  - "{process_slug}/pages/docs/user-stories.html"
+  - "{process_slug}/pages/docs/prd.html"
+  - "{process_slug}/pages/docs/snapshots/prd-v*.html"
+required_tools:
+  - Read
+  - Bash
+  - Write
+  - Edit
+---
+
+# clarify-requirements
+
+## Purpose
+
+Using [clarify-requirements] to 基于访谈内容与人类 PM 多轮澄清需求.
+
+
+基于访谈 transcript 和 summary 与人类 PM 多轮澄清，输出统一需求文档。
+
+运行入口： prompts/main.md

package/framework/.claude/skills/clarify-requirements/prompts/main.md

@@ -0,0 +1,81 @@
+# clarify-requirements
+
+You are executing the Lincoln workflow step `clarify`: turn interview artifacts into a structured requirements document through multi-round clarification with the human PM.
+
+## Goal
+
+Produce a clear, agreed-upon `{process_slug}/pages/docs/requirements.html` and the root-level `{process_slug}/pages/docs/prd.html` that serves as the single source of truth and main thread for this issue.
+
+## Input
+
+- `session_id`: the interview session identifier
+
+## 子技能准备
+
+在执行本 prompt 前：
+- 若存在外部需求/计划文件，先调用 `gsd-import` 进行冲突检测。
+- 调用 `superpowers:brainstorming` 与 PM 一起探索 2-3 种可能的需求视角，列出 trade-offs。  
+  **在 PM 明确选择方向前，禁止继续生成需求文档。**
+
+## Steps
+
+1. Read `{process_slug}/interviews/<session-id>/transcript.md`, `summary.md`, and `raw-insights.md`.
+2. Draft an initial `{process_slug}/pages/docs/requirements.html` using `.claude/templates/issue-package/page-doc.html.tpl`. Embed the Markdown source in the `<script type="text/markdown" id="docSource">` block and include a `<!-- version: v1.0 -->` marker. Required sections:
+   - `背景`
+   - `问题`
+   - `用户`
+   - `方案`
+   - `验收标准`
+   - `非目标`
+   - `开放问题`
+3. Identify 1-3 ambiguities or missing details, and tag each with its Johari quadrant (认知象限): 知道自己知道 → 复述确认题; 知道自己不知道 → 直接回答 + coach; 不知道自己知道 → 展示已有资产; 不知道自己不知道 → 探查题.
+4. Ask the human PM these questions one batch at a time in the terminal, using the quadrant-appropriate style.
+5. Update `requirements.html` based on the answers (always rewrite the full file; do not mutate in-place).
+6. Repeat until the PM confirms the requirements are clear.
+7. Also generate `{process_slug}/pages/docs/user-stories.html` from the finalized requirements using the same doc-page template.
+8. Generate the root-level PRD at `{process_slug}/pages/docs/prd.html` using `.claude/templates/issue-package/page-doc.html.tpl`. It must include:
+   - `<!-- version: v1.0 -->` marker inside the `docSource` block.
+   - Meta tags: `doc-title`, `nav-group="Docs"`, `doc-version="v1.0"`, and a stable `doc-uid`.
+   - All required sections: 1.需求背景, 2.用户故事, 3.功能拆解, 4.业务流程图, 5.验收标准, 6.业务规则, 7.非功能需求, 8.关联系统/接口, 9.相关产物链接, 10.风险与开放问题.
+   - A links table in section 9 pointing to interviews, requirements.html, user-stories.html, and downstream design/prototype/OpenSpec artifacts.
+9. When the PM confirms, add an approval marker inside `requirements.html`: `<!-- status: approved -->`.
+10. After human approval, run `python scripts/lincoln_prd.py freeze` to create the immutable snapshot `{process_slug}/pages/docs/snapshots/prd-v1.0.html`.
+11. Run `python scripts/stage_loader.py --stage clarify --action record-artifacts` to persist the artifact paths and refresh `{process_slug}/assets/js/package-data.js`.
+
+## Human Interaction Rules
+
+- Ask at most 3 questions per turn.
+- After each answer, update the document and show the changed sections.
+- If the PM edits `requirements.html` or `prd.html` directly and runs `workflow-continue`, re-read the file and continue from there.
+- Do not proceed to the next step until the PM explicitly confirms (e.g., says "confirm" or "确认").
+
+## 认知象限确认（Johari）
+
+澄清问题按 Johari 四象限设计与标注：
+
+| 象限 | 问题风格 |
+|------|----------|
+| 知道自己知道 | 复述确认题：用你的话复述需求，防止会错意 |
+| 知道自己不知道 | 直接回答 + coach：先给背景与选项，不反问 |
+| 不知道自己知道 | 展示已有资产：引用 knowledge/、issues、既有文档中已有的答案 |
+| 不知道自己不知道 | 探查题：用具体场景暴露用户未意识到的风险与缺失 |
+
+出口条件（两条都满足才允许进入下一阶段）：
+
+1. 每个开放问题都有明确的验收标准答案（用户认可的"怎样算完成"）。
+2. 执行路径已确定（下一步产物、负责角色、进入哪个阶段）。
+
+## Output Artifacts
+
+- `{process_slug}/pages/docs/requirements.html`
+- `{process_slug}/pages/docs/user-stories.html`
+- `{process_slug}/pages/docs/prd.html` (root-level PRD, versioned)
+- `{process_slug}/pages/docs/snapshots/prd-v1.0.html` (immutable snapshot after approval)
+
+## Traceability
+
+Every requirement must reference the transcript timestamp where it originated, e.g., `(来源: 00:03:22)`.
+
+## Next Step
+
+After confirmation and snapshot freeze, tell the user the clarify stage is complete and the next stage is `product-design-docs`.