@sushanglewis/lincoln 1.6.3 → 1.8.0

package/framework/.claude/skills/draft-product-design/prompts/main.md

@@ -45,14 +45,35 @@ Create `{process_slug}/pages/docs/` HTML design documents with enough product, d
    ```
    This creates only the pages that do not yet exist. If a matching `.md` file exists, it is used automatically; otherwise the page is created empty for you to fill afterwards.
 
-   Page-specific guidance:
-   - `design-review.md`: H2 chapters such as `## 决策摘要`, `## 范围`, `## 链接`, `## 开放问题`, `## 审批清单`.
+   Page-specific guidance (every doc page starts with `## 页面意图` — target reader and the question this page answers — and `## 边界` — what it deliberately does not cover plus links to the single source of truth; do not duplicate content across pages, link instead):
+   - `design-review.md`: H2 chapters such as `## 页面意图`, `## 范围`, `## 链接`, `## 开放问题`, `## 审批清单`. Do **not** include a decision log here — decisions live only in `decisions.html`.
+   - `decisions.md`: the archive of important communication records and decisions from both the clarify and design stages. H2 chapters such as `## 页面意图`, `## 决策清单`; each entry is a Markdown table row with 日期 / 场景 / 选项 / 决定 / 理由 / 影响 / 状态. Render it with an explicit archive nav group:
+
+     ```bash
+     python scripts/lincoln_render.py \
+       --stage product-design-docs \
+       --target issue-<N>/pages/docs/decisions.html \
+       --title "决策归档" \
+       --nav-label "决策归档" \
+       --nav-group "归档" \
+       --markdown issue-<N>/pages/docs/decisions.md
+     ```
    - `scenarios.md`: `## 主要场景`, `## 边界场景`, `## 非目标`, plus persona descriptions and Mermaid flowcharts.
    - `feature-catalog.md`: either a Markdown table or a YAML `features` array.
    - `data-model.md`: either Markdown entity sections or a YAML `entities` array.
    - `flows.md`: Markdown with ` ```mermaid ` flowcharts and numbered step lists.
    - `page-map.md`: either a Markdown table or a YAML `pages` array.
-   - `feasibility.md`: H2 chapters such as `## 风险`, `## 方案对比`, `## 建议`.
+   - `feasibility.md`: H2 chapters such as `## 风险`, `## 方案对比`, `## 建议`. This page holds all technical research; render it with `--nav-group "归档"` so it stays out of the main reading path:
+
+     ```bash
+     python scripts/lincoln_render.py \
+       --stage product-design-docs \
+       --target issue-<N>/pages/docs/feasibility.html \
+       --title "可行性研究" \
+       --nav-label "可行性" \
+       --nav-group "归档" \
+       --markdown issue-<N>/pages/docs/feasibility.md
+     ```
    - `version-log.md`: H2 chapters plus a Markdown table of version entries.
    - `api-list.md`: either a Markdown table or a YAML `apis` array.
 4. Create the PM→UX handoff contract at `{process_slug}/handoffs/pm-to-ux/pm-to-ux.handoff.yaml` referencing the approved design docs and PRD versions.
@@ -67,6 +88,8 @@ Create `{process_slug}/pages/docs/` HTML design documents with enough product, d
 
 - Use Chinese for PM-facing content unless the requirements are in English.
 - Keep documents short and reviewable; prefer tables and Mermaid diagrams over long prose.
+- Every document page must open with `## 页面意图` and `## 边界`; content must follow standard Markdown (a single H1, H2 chapters, tables/Mermaid over long prose). Never copy content across pages — link to the single source of truth instead.
+- Technical research and solution comparisons (frameworks, open-source options, trade-off analysis) belong **only** in `feasibility.html` (archived) or the PM→UX handoff contract. They must not appear in `prd.html`, `requirements.html`, `design-review.html`, `scenarios.html`, `feature-catalog.html`, or any other main-path page. PM-stage pages focus on business clarity: background, user roles, journeys, business states, flows, page routes/elements/interactions.
 - For technical frameworks and open-source projects, check current official docs or primary repositories before recommending.
 - Do not create UI specs, field specs, or prototypes in this step. Those are produced in the next stage `product-prototype`.
 - Do not create a Pencil prototype in this step.

package/framework/.claude/skills/lc-workflow/validators/validate.py

@@ -452,6 +452,7 @@ def check_no_conflict_with_existing_knowledge(feature_slug: str):
 def validate_design_docs_complete(design_id: str):
     docs = [
         "design-review.html",
+        "decisions.html",
         "scenarios.html",
         "feature-catalog.html",
         "data-model.html",

package/framework/.claude/stages/clarify.yaml

@@ -19,6 +19,7 @@ variables:
 - process_slug
 artifact_templates:
   '{process_slug}/pages/docs/requirements.html': .claude/templates/issue-package/page-doc.html.tpl
+  '{process_slug}/pages/docs/stakeholders.html': .claude/templates/issue-package/page-doc.html.tpl
   '{process_slug}/pages/docs/user-stories.html': .claude/templates/issue-package/page-doc.html.tpl
   '{process_slug}/pages/docs/prd.html': .claude/templates/issue-package/page-doc.html.tpl
   '{process_slug}/pages/docs/snapshots/prd-v*.html': .claude/templates/issue-package/page-doc.html.tpl
@@ -38,6 +39,7 @@ skills:
 artifacts:
   required:
   - '{process_slug}/pages/docs/requirements.html'
+  - '{process_slug}/pages/docs/stakeholders.html'
   - '{process_slug}/pages/docs/user-stories.html'
   - '{process_slug}/pages/docs/prd.html'
   optional:
@@ -47,7 +49,7 @@ references:
   agent_guide: .claude/agents/pm.md
 context:
   goal: 基于访谈产物（逐字稿、摘要、初始洞察）与人类 PM 进行多轮澄清，形成统一、可追溯、已确认的需求文档，并将 PRD 置于 HTML 门户（{process_slug}/pages/docs/prd.html）作为串联后续所有阶段的主线文档与单一事实来源。人类读者通过 {process_slug}/index.html 浏览所有产物。
-  execution: "调用 clarify-requirements skill 与人类 PM 进行多轮澄清对话，基于访谈产物识别歧义并达成共识；产出 requirements/user-stories/prd 三个 HTML 文档，PRD 携带 <!-- version: vX.Y --> 版本标记，确认后通过 scripts/lincoln_prd.py freeze 生成不可变的快照。"
+  execution: "调用 clarify-requirements skill 与人类 PM 进行多轮澄清对话，基于访谈产物识别歧义并达成共识；产出 requirements、stakeholders、user-stories、prd 四个 HTML 文档，PRD 携带 <!-- version: vX.Y --> 版本标记，确认后通过 scripts/lincoln_prd.py freeze 生成不可变的快照。"
   constraints: "- PRD 必须位于 {process_slug}/pages/docs/prd.html，并携带 <!-- version: vX.Y --> 版本标记；确认后通过 scripts/lincoln_prd.py freeze 生成不可变的 pages/docs/snapshots/prd-vX.Y.html 快照。\n\n    - PRD 是产研流程的主线文档，需在后续阶段持续维护「相关产物链接」章节，指向设计、原型、OpenSpec、实现等产物。"
 gates:
   entry:

package/framework/.claude/stages/phase-1-p0-design.yaml

@@ -0,0 +1,44 @@
+schema_version: 3.0.0
+id: phase-1-p0-design
+name: Phase 1 P0 Design
+description: 'Design Phase 1 / P0 recommendations from the LEW-70 research baseline:
+
+  SecurityAnalyzer + ConfirmationPolicy, harness distribution for
+
+  Claude Code/Codex/OpenCode, and declarative hook/MCP configuration.
+
+  '
+prerequisite_stage: explore-opensource
+next_stage: phase-1-p0-implement
+human_gate: true
+agent:
+  primary: lc-architect
+  reviewers:
+  - lc-engineer
+  handoff_to: lc-pm
+skills:
+  required: []
+  optional: []
+artifacts:
+  required:
+  - '{process_slug}/designs/phase-1-p0-harness-security-design.md'
+context:
+  goal: 'Produce an approved design document for the highest-priority borrowable
+
+    patterns before any implementation PR is opened.
+
+    '
+  constraints: '- 仅通过 scripts/stage_loader.py 更新 {process_slug}/workflow-stage.yaml。
+
+    - human_gate 必须获得人类 PM 显式确认。
+
+    '
+gates:
+  entry:
+  - check: previous_stage_completed
+    args:
+    - explore-opensource
+  exit:
+  - check: artifacts_present
+workflows:
+- framework-self-improvement

package/framework/.claude/stages/phase-1-p0-implement.yaml

@@ -0,0 +1,47 @@
+schema_version: 3.0.0
+id: phase-1-p0-implement
+name: Phase 1 P0 Implement
+description: 'Implement Phase 1 / P0 recommendations from the approved design document.
+
+  '
+prerequisite_stage: phase-1-p0-design
+next_stage: phase-2-p1-design
+human_gate: false
+agent:
+  primary: lc-engineer
+  reviewers:
+  - lc-qa
+  handoff_to: lc-pm
+skills:
+  required: []
+  optional: []
+artifacts:
+  required:
+  - .claude/policies/security.yaml
+  - .claude/hooks/pre-tool-use.sh
+  - .claude/hooks/hooks.yaml
+  - .claude/mcp/mcp.yaml
+  - .claude/harnesses/codex.yaml
+  - .claude/harnesses/opencode.yaml
+  - scripts/security_analyzer.py
+  - scripts/lincoln_harness_adapter.py
+  - scripts/lincoln-setup.py
+  - scripts/check-harness-drift.sh
+context:
+  goal: 'Implement the approved P0 design and verify with tests and static checks.
+
+    '
+  constraints: '- 仅通过 scripts/stage_loader.py 更新 {process_slug}/workflow-stage.yaml。
+
+    - 所有变更必须通过测试与 static-check.sh。
+
+    '
+gates:
+  entry:
+  - check: previous_stage_completed
+    args:
+    - phase-1-p0-design
+  exit:
+  - check: artifacts_present
+workflows:
+- framework-self-improvement

package/framework/.claude/stages/phase-2-p1-design.yaml

@@ -0,0 +1,53 @@
+schema_version: 3.0.0
+id: phase-2-p1-design
+name: Phase 2 P1 Design
+description: 'Design Phase 2 / P1 recommendations from the LEW-70 research baseline:
+
+  friction-based learning + recall precheck, EventLog + Condenser,
+
+  skill marketplace + git caching, sub-agent delegation, and MR knowledge mining.
+
+  '
+prerequisite_stage: phase-1-p0-implement
+next_stage: phase-2-p1-implement
+human_gate: true
+agent:
+  primary: lc-architect
+  reviewers:
+  - lc-engineer
+  - lc-researcher
+  handoff_to: lc-pm
+  parallel_specialists:
+  - lc-architect
+  - lc-security-reviewer
+  merge_strategy: priority
+  output_schema: .claude/schemas/design-review-feedback.json
+skills:
+  required: []
+  optional: []
+artifacts:
+  required:
+  - '{process_slug}/designs/phase-2-p1-learning-eventlog-subagents-design.md'
+context:
+  goal: 'Produce an approved design document for P1 borrowable patterns before
+
+    any implementation PR is opened.
+
+    '
+  constraints: '- 仅通过 scripts/stage_loader.py 更新 {process_slug}/workflow-stage.yaml。
+
+    - human_gate 必须获得人类 PM 显式确认。
+
+    - Lincoln 不自研底层执行器；所有设计必须适配 Claude Code / Codex / OpenCode。
+
+    '
+gates:
+  entry:
+  - check: previous_stage_completed
+    args:
+    - phase-1-p0-implement
+  exit:
+  - check: artifacts_present
+  - check: human_approved
+workflows:
+- framework-self-improvement

package/framework/.claude/stages/phase-2-p1-implement.yaml

@@ -0,0 +1,45 @@
+schema_version: 3.0.0
+id: phase-2-p1-implement
+name: Phase 2 P1 Implement
+description: 'Implement Phase 2 / P1 recommendations from the approved design document.
+
+  '
+prerequisite_stage: phase-2-p1-design
+next_stage: product-design-docs
+human_gate: false
+agent:
+  primary: lc-engineer
+  reviewers:
+  - lc-qa
+  handoff_to: lc-pm
+skills:
+  required: []
+  optional: []
+artifacts:
+  required:
+  - .claude/policies/friction.yaml
+  - .claude/schemas/design-review-feedback.json
+  - scripts/lincoln_friction.py
+  - scripts/lincoln_recall.py
+  - scripts/lincoln_condenser.py
+  - scripts/lincoln_mr_mine.py
+  - scripts/lincoln_trace.py
+  - scripts/stage_loader.py
+context:
+  goal: 'Implement the approved P1 design and verify with tests and static checks.
+
+    '
+  constraints: '- 仅通过 scripts/stage_loader.py 更新 {process_slug}/workflow-stage.yaml。
+
+    - 所有变更必须通过测试与 static-check.sh。
+
+    '
+gates:
+  entry:
+  - check: previous_stage_completed
+    args:
+    - phase-2-p1-design
+  exit:
+  - check: artifacts_present
+workflows:
+- framework-self-improvement

package/framework/.claude/stages/product-design-docs.yaml

@@ -17,6 +17,7 @@ variables:
 - process_slug
 artifact_templates:
   '{process_slug}/pages/docs/design-review.html': .claude/templates/issue-package/page-doc.html.tpl
+  '{process_slug}/pages/docs/decisions.html': .claude/templates/issue-package/page-doc.html.tpl
   '{process_slug}/pages/docs/scenarios.html': .claude/templates/issue-package/page-doc.html.tpl
   '{process_slug}/pages/docs/feature-catalog.html': .claude/templates/issue-package/page-doc-structured.html.tpl
   '{process_slug}/pages/docs/data-model.html': .claude/templates/issue-package/page-doc-structured.html.tpl
@@ -44,6 +45,7 @@ skills:
 artifacts:
   required:
   - '{process_slug}/pages/docs/design-review.html'
+  - '{process_slug}/pages/docs/decisions.html'
   - '{process_slug}/pages/docs/scenarios.html'
   - '{process_slug}/pages/docs/feature-catalog.html'
   - '{process_slug}/pages/docs/data-model.html'

package/framework/.claude/workflows/bug-fix.yaml

@@ -29,6 +29,7 @@ workflow:
       action: draft-product-design
       artifacts:
         - "{process_slug}/pages/docs/design-review.html"
+        - "{process_slug}/pages/docs/decisions.html"
       exit_checks:
         - check: design_docs_complete
         - check: design_docs_human_approved

package/framework/.claude/workflows/design-spike.yaml

@@ -29,6 +29,7 @@ workflow:
       action: draft-product-design
       artifacts:
         - "{process_slug}/pages/docs/design-review.html"
+        - "{process_slug}/pages/docs/decisions.html"
       exit_checks:
         - check: design_docs_complete
         - check: design_docs_human_approved

package/framework/.claude/workflows/existing-project-iteration.yaml

@@ -44,6 +44,7 @@ workflow:
       action: draft-product-design
       artifacts:
         - "{process_slug}/pages/docs/design-review.html"
+        - "{process_slug}/pages/docs/decisions.html"
       exit_checks:
         - check: design_docs_complete
         - check: design_docs_human_approved

package/framework/.claude/workflows/framework-self-improvement.yaml

@@ -0,0 +1,100 @@
+workflow:
+  name: framework-self-improvement
+  version: 1.0.0
+  description: 持续改进 Lincoln 框架本身的工作流（安全门控、harness 分发、摩擦学习、事件追踪、子代理委托）
+  execution_mode: team
+  engine: everything-claude-code
+
+  steps:
+    - id: workflow-router
+      name: 工作流路由
+      description: 会话开场引导后，选择最适合当前场景的工作流模板
+      action: lc-workflow-router
+
+    - id: clarify
+      name: 需求澄清
+      description: 与人类 PM 多轮澄清，形成统一需求文档
+      human_gate: true
+      action: clarify-requirements
+      artifacts:
+        - "{process_slug}/pages/docs/requirements.html"
+      exit_checks:
+        - check: requirements_has_background_problem_solution_acceptance
+        - check: human_approved
+
+    - id: explore-opensource
+      name: 开源方案探索
+      description: 调研可复用的开源方案并记录决策
+      action: lc-explore-opensource
+      artifacts:
+        - "{process_slug}/docs/research/{change_name}-oss-options.md"
+      exit_checks:
+        - check: oss_research_complete
+
+    - id: phase-1-p0-design
+      name: Phase 1 P0 设计
+      description: 设计 P0 安全门控与 harness 分发方案
+      human_gate: true
+      action: draft-product-design
+      artifacts:
+        - "{process_slug}/designs/phase-1-p0-harness-security-design.md"
+      exit_checks:
+        - check: design_docs_complete
+        - check: design_docs_human_approved
+
+    - id: phase-1-p0-implement
+      name: Phase 1 P0 实现
+      description: 实现 P0 安全门控与 harness 分发
+      action: implement
+      artifacts:
+        - ".claude/policies/security.yaml"
+        - ".claude/hooks/pre-tool-use.sh"
+        - ".claude/hooks/hooks.yaml"
+        - ".claude/mcp/mcp.yaml"
+        - ".claude/harnesses/codex.yaml"
+        - ".claude/harnesses/opencode.yaml"
+        - "scripts/security_analyzer.py"
+        - "scripts/lincoln_harness_adapter.py"
+        - "scripts/lincoln-setup.py"
+        - "scripts/check-harness-drift.sh"
+      exit_checks:
+        - check: artifacts_present
+
+    - id: phase-2-p1-design
+      name: Phase 2 P1 设计
+      description: 设计 P1 摩擦学习、事件追踪扩展、子代理委托与 MR 知识挖掘方案
+      human_gate: true
+      action: draft-product-design
+      artifacts:
+        - "{process_slug}/designs/phase-2-p1-learning-eventlog-subagents-design.md"
+      exit_checks:
+        - check: design_docs_complete
+        - check: design_docs_human_approved
+
+    - id: phase-2-p1-implement
+      name: Phase 2 P1 实现
+      description: 实现 P1 摩擦学习、事件追踪扩展、子代理委托与 MR 知识挖掘
+      action: implement
+      artifacts:
+        - ".claude/policies/friction.yaml"
+        - ".claude/schemas/design-review-feedback.json"
+        - "scripts/lincoln_friction.py"
+        - "scripts/lincoln_recall.py"
+        - "scripts/lincoln_condenser.py"
+        - "scripts/lincoln_mr_mine.py"
+        - "scripts/lincoln_trace.py"
+        - "scripts/stage_loader.py"
+      exit_checks:
+        - check: artifacts_present
+
+    - id: sync-knowledge
+      name: 同步到知识库
+      description: 将业务与技术知识沉淀到 Obsidian vault
+      trigger: on_pr_merge
+      action: sync-to-knowledge
+      artifacts:
+        - "knowledge/03-features/{feature_slug}.md"
+      exit_checks:
+        - check: feature_doc_has_business_and_technical_sections
+        - check: feature_doc_has_links
+        - check: no_conflict_with_existing_knowledge

package/framework/.claude/workflows/interview-to-knowledge.yaml

@@ -46,6 +46,7 @@ workflow:
       human_gate: true
       artifacts:
         - "{process_slug}/pages/docs/requirements.html"
+        - "{process_slug}/pages/docs/stakeholders.html"
         - "{process_slug}/pages/docs/user-stories.html"
         - "{process_slug}/pages/docs/prd.html"
       optional_artifacts:
@@ -68,6 +69,7 @@ workflow:
       human_gate: true
       artifacts:
         - "{process_slug}/pages/docs/design-review.html"
+        - "{process_slug}/pages/docs/decisions.html"
         - "{process_slug}/pages/docs/scenarios.html"
         - "{process_slug}/pages/docs/feature-catalog.html"
         - "{process_slug}/pages/docs/data-model.html"

package/framework/.claude/workflows/oss-first-design.yaml

@@ -38,6 +38,7 @@ workflow:
       action: draft-product-design
       artifacts:
         - "{process_slug}/pages/docs/design-review.html"
+        - "{process_slug}/pages/docs/decisions.html"
       exit_checks:
         - check: design_docs_complete
         - check: design_docs_human_approved

package/framework/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "lincoln",
       "description": "AI-Native product R&D collaboration system for Conductor + Claude Code. Orchestrates stages, gates, artifacts, skills, and roles across product, design, and engineering into a repeatable workflow from recordings to GitHub Issues to Obsidian knowledge base.",
-      "version": "1.6.3",
+      "version": "1.8.0",
       "author": {
         "name": "Lincoln contributors"
       },
@@ -28,5 +28,5 @@
       ]
     }
   ],
-  "version": "1.6.3"
+  "version": "1.8.0"
 }

package/framework/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lincoln",
-  "version": "1.6.3",
+  "version": "1.8.0",
   "description": "AI-Native product R&D collaboration system for Conductor + Claude Code + OpenSpec + GitHub + Obsidian",
   "author": {
     "name": "Lincoln contributors"

package/framework/.version-bump.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.6.3",
+  "version": "1.8.0",
   "manifests": [
     {
       "path": ".claude-plugin/plugin.json",

package/framework/README.en.md

@@ -2,6 +2,8 @@
 
 > [中文](README.md) | English
 
+**TL;DR** — Lincoln is an AI-Native R&D workflow system that brings stage-driven discipline, human gates, and repeatable SOPs to Claude Code, Codex, and OpenCode — from requirements to shipped knowledge.
+
 Lincoln is an AI-Native R&D workflow system spanning **IDEs, agent harnesses, code hosting, knowledge management, skills, plugins, and automation**. It runs on **stages** for rhythm, **gates** for quality, and **repeatable SOPs** as its backbone, chaining requirements clarification, product design, prototyping, TDD planning, OpenSpec proposals, task splitting, implementation, and knowledge-base distillation into one human-AI collaborative pipeline.
 
 - **Whole lifecycle, not a point tool**: every stage has explicit role, skill, and artifact contracts — agents step in at the right moments instead of replacing human judgment.
@@ -10,9 +12,9 @@ Lincoln is an AI-Native R&D workflow system spanning **IDEs, agent harnesses, co
 
 ## Latest Release
 
-[![Release](https://img.shields.io/badge/release-v1.6.3-blue)](RELEASE.md)
+[![Release](https://img.shields.io/badge/release-v1.8.0-blue)](RELEASE.md)
 
-**v1.6.3** is released: Lincoln switches to a global npm plugin model. Install with `npm install -g @sushanglewis/lincoln`; projects opt in via `.lincoln.yaml`.
+**v1.8.0** is released: SecurityAnalyzer pre-tool-use gating, Trace 2.0 event log, session friction scoring and knowledge recall, plus multi-dimensional stakeholder analysis in the clarify stage.
 
 See the full release notes in [RELEASE.md](RELEASE.md).
 
@@ -92,10 +94,28 @@ This creates a `.lincoln.yaml` marker file. After that, opening Claude Code in t
 
 ### Update Lincoln
 
+Already installed? One command upgrades Lincoln and re-syncs the framework into your harnesses — `lincoln update` pulls the latest release from npm and re-runs the sync:
+
 ```bash
-lincoln update
+lincoln update            # upgrade to the latest release and re-sync
+lincoln update --check    # check for a newer version without installing
+```
+
+On an older install (e.g. from the `lincoln-install` era), or if npm reports `EEXIST: file already exists`, a leftover bin from an old package is blocking the install — clean up first, then reinstall:
+
+```bash
+npm uninstall -g lincoln lincoln-install   # remove legacy package names (skips if absent)
+npm install -g @sushanglewis/lincoln@latest
+lincoln install --yes
 ```
 
+> **Dangling-bin symptom**: the install fails with `EEXIST: file already exists` while running `lincoln` reports `command not found` — a dead symlink from an old package occupies the bin path. Verify with `ls -la "$(npm prefix -g)/bin/lincoln"` that it points to a removed package, delete it, and retry:
+>
+> ```bash
+> rm "$(npm prefix -g)/bin/lincoln"
+> npm install -g @sushanglewis/lincoln@latest && lincoln install --yes
+> ```
+
 ### Migrate from the old vendored model
 
 If your project previously committed the Lincoln framework source directly into the repo:
@@ -113,7 +133,11 @@ First time? Read [USAGE.md](USAGE.md) for the full installation and usage guide.
 
 ### Stage-Driven Workflow Engine
 
-Each stage is defined in `.claude/stages/<stage-id>.yaml` with its role, skills, gates, and artifacts. The `workflow-stage.yaml` runtime state drives agent context injection, while Lincoln's stage loader handles stage validation, artifact recording, and gate advancement.
+Each stage is defined in `.claude/stages/<stage-id>.yaml` with its role, skills, gates, and artifacts. The `workflow-stage.yaml` runtime state drives agent context injection, while Lincoln's stage loader handles stage validation, artifact recording, and gate advancement. `--render-stage` batch rendering generates all missing artifact pages declared by a stage in a single command.
+
+### Artifact Traceability
+
+Lincoln assigns stable IDs such as `feature/*`, `page/*`, `field/*`, and `doc/*` to requirements, pages, fields, documents, and other artifacts. Downstream stages trace upstream work by ID instead of guessing paths. To trace an artifact, just tell the Agent "Look up doc/requirement-001".
 
 ### Preset SOP Workflow Templates
 
@@ -128,14 +152,14 @@ Each stage is defined in `.claude/stages/<stage-id>.yaml` with its role, skills,
 
 See [`.claude/workflows/README.md`](.claude/workflows/README.md) for the full template catalog.
 
-### Issue Work Packages (HTML Portal)
+### Markdown-First Issue Work Packages
 
 Every requirement maps to one GitHub issue and one Lincoln feature branch. The `issue-<N>/` work package contains:
 
 - `index.html` — human-facing portal aggregating stage status, navigation, and artifacts
 - `workflow-stage.yaml` — machine-readable state and handoff protocol
 - `documents.yaml` — artifact index and human-approval status
-- `pages/docs/` — HTML pages for requirements, PRDs, designs, TDD plans
+- `pages/docs/` — pages for requirements, PRDs, designs, TDD plans; narrative docs are Markdown-first and can be authored as Markdown chapters with `mermaid` diagrams, rendered by the local `mermaid.min.js` runtime
 - `pages/prototype/` — interactive HTML prototypes
 - `handoffs/` — stage handoff documents
 
@@ -154,6 +178,7 @@ Lincoln is AI-Native — **you don't need to type terminal commands**. Describe
 | List all active Lincoln branches | Lists stage status and blockers for every issue branch |
 | Run benchmark | Generates a Lincoln session benchmark report |
 | Start the PM research workflow | Enters the `pm-research` research chain |
+| Look up doc/requirement-001 | Traces the artifact by stable ID |
 
 More commands and usage details are in [USAGE.md](USAGE.md).
 
@@ -201,6 +226,18 @@ Before submitting a PR, please read:
 - [OpenSpec docs](https://github.com/Fission-AI/openspec)
 - [Obsidian WikiLinks](https://help.obsidian.md/Linking+notes+and+files/Internal+links)
 
+## Release History
+
+| Version | Date | Key capabilities |
+|---|---|---|
+| v1.7.0 | 2026-09-05 | SecurityAnalyzer gating; Trace 2.0 event log; friction scoring/knowledge recall/trace condensation/MR mining; parallel specialist delegation; stakeholder analysis model |
+| v1.6.3 | 2026-08-15 | Markdown-first issue-package documents; `--render-stage` batch rendering; local `mermaid.min.js` runtime |
+| v1.6.2 | 2026-08-12 | `lc-init-branch` reads global Lincoln templates |
+| v1.6.1 | 2026-08-11 | `lc-one-id` artifact traceability; portal annotation alignment |
+| v1.6.0 | 2026-08-06 | Global npm plugin model; `@sushanglewis/lincoln` CLI; release-on-merge automation |
+
+See [RELEASE.md](RELEASE.md) for full release notes.
+
 ## License
 
 Lincoln is released under the [MIT License](LICENSE), Copyright (c) 2026 苏尚lewis (sushanglewis).