sdd-agent-platform 0.4.2 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/config/starter-documents.ts

@@ -1,432 +1,400 @@
-
-function usesChineseInitDocs(value: string): boolean {
-  return value === 'zh-CN';
-}
-
-export function renderInitSpecDocument(branch: string, docsLanguage: string): string {
-  const zh = usesChineseInitDocs(docsLanguage);
-  const title = zh ? '# Spec: Project Onboarding / 项目入门' : '# Spec: Project Onboarding';
-  const objectiveLines = zh ? `- User value: 仓库在第一个真实变更前已有可见的 SDD 入口。
-- Business value: 待补充；请替换为第一个真实功能或变更目标。
-- Engineering value: semantic documents、runtime config 与托管 AI entries 已安全初始化。
-- Observable success: \`sdd status --branch ${branch}\` 报告 spec、plan、tasks 均已存在。` : `- User value: the repository has a visible SDD entrypoint before the first real change.
-- Business value: pending; replace with the first real feature/change objective.
-- Engineering value: semantic documents, runtime config, and managed AI entries are initialized safely.
-- Observable success: \`sdd status --branch ${branch}\` reports spec, plan, and tasks as present.`;
-  const problemIntent = zh
-    ? '此项目已初始化 SDD。请在实现前用第一个真实功能或变更请求替换这份 onboarding spec。'
-    : 'This project has been initialized for SDD. Replace this onboarding spec with the first real feature or change request before implementation.';
-  const actorRow = zh
-    ? '| repository maintainer | 安全的 SDD 起点 | 还没有写入项目专属的 SDD 请求 |'
-    : '| repository maintainer | a safe SDD starting point | no project-specific SDD request has been written yet |';
-  const story = zh
-    ? 'As a repository maintainer, I want starter SDD documents, so that the first real change can be captured as requirements、design 与 executable tasks。'
-    : 'As a repository maintainer, I want starter SDD documents, so that the first real change can be captured as requirements, design, and executable tasks.';
-  return `---
-template: sdd-init-onboarding-spec-v1
-version: 1.4.0
-contract: sdd-spec-doc-v1
-sdd_managed_starter: true
----
-
-${title}
-
-## 0. Metadata
-
-- spec_id: \`onboarding\`
-- branch: \`${branch}\`
-- lifecycle_profile: \`direct\`
-- source_request: \`Created by sdd init\`
-- status: \`draft\`
-
-## 1. Objective / Customer Value
-
-${objectiveLines}
-
-## 2. Problem / Intent
-
-${problemIntent}
-
-## 3. Users / Actors
-
-| Actor | Need / Expectation | Current Pain |
-|---|---|---|
-${actorRow}
-
-## 4. User Stories / Scenarios
-
-### Story US-1
-
-${story}
-
-### Scenario S1: initialized repository
-
-- Given: \`sdd init\` has run for branch \`${branch}\`.
-- When: the maintainer runs \`sdd status --branch ${branch}\`.
-- Then: the CLI reports starter spec, plan, and tasks documents as present.
-
-## 5. Scope
-
-### In Scope
-
-- Confirm the project is initialized.
-- Replace onboarding placeholders with a real spec, plan, and tasks when ready.
-
-### Out of Scope
-
-- Running background agents.
-- Creating worktrees.
-- Claiming truth-alignment or release approval without accepted runtime evidence.
-
-## 6. Requirements
-
-### Functional Requirements
-
-| ID | Requirement | Priority | Source |
-|---|---|---|---|
-| FR-1 | \`sdd init\` creates the SDD runtime config and starter semantic documents. | Must | init |
-| FR-2 | \`sdd status --branch ${branch}\` can inspect the initialized branch without missing document gaps. | Must | status |
-
-### Non-functional Requirements
-
-| ID | Requirement | Priority | Source |
-|---|---|---|---|
-| NFR-1 | Initialization must not overwrite user-authored SDD documents unless force is explicitly requested. | Must | safety |
-
-## 7. Acceptance Criteria
-
-| ID | Acceptance | Verification Hint | Priority |
-|---|---|---|---|
-| AC-1 | \`sdd status --branch ${branch}\` reports all three semantic documents as present. | CLI status | Must |
-| AC-2 | Existing user-authored semantic documents are preserved by default. | init preserve behavior | Must |
-
-## 8. Assumptions / Dependencies
-
-| Item | Description | Impact if Wrong |
-|---|---|---|
-| first real request pending | onboarding docs are placeholders | implementation must not start from this scaffold |
-
-## 9. Risks / Hard Gates
-
-| Risk | Why it matters | Required Handling |
-|---|---|---|
-| scaffold mistaken for approved spec | could authorize vague implementation | replace with a real requirement contract before coding |
-
-## 10. Open Questions
-
-| ID | Question | Owner | Required Before |
-|---|---|---|---|
-| Q-1 | What is the first real feature or change request? | user | plan |
-
-## 11. Lifecycle Decision Reference
-
-- decision_artifact: \`pending\`
-- canonical_model: \`docs/architecture/lifecycle-decision-model.md\`
-- recommended_profile: \`direct\`
-- risk_signals: []
-- autonomy_ceiling: \`direct_execution_allowed\`
-`;
-}
-
-export function renderInitPlanDocument(branch: string, docsLanguage: string): string {
-  const zh = usesChineseInitDocs(docsLanguage);
-  const title = zh ? '# Plan: Project Onboarding / 项目入门' : '# Plan: Project Onboarding';
-  const background = zh
-    ? '在实现开始前，请用第一个真实功能或变更请求的业务背景与技术背景替换这份 starter plan。'
-    : 'Replace this starter plan with the business and technical context for the first real feature or change request before implementation begins.';
-  const goals = zh
-    ? '- Goals: 写明本次变更必须交付的结果。\n- Non-goals: 写明防止范围蔓延的边界。'
-    : '- Goals: replace with the outcomes this change must deliver.\n- Non-goals: replace with boundaries that prevent scope creep.';
-  const currentState = zh
-    ? '描述当前流程、代码区域、state/data/API 行为以及已知约束。'
-    : 'Describe the current flow, code areas, state/data/API behavior, and known constraints.';
-  const targetDesign = zh
-    ? '描述已选择的技术方案，以及它为什么是从 spec 到 implementation 最安全的 task-ready 路径。'
-    : 'Describe the selected technical solution and why it is the safest task-ready path from spec to implementation.';
-  return `---
-template: sdd-init-onboarding-plan-v1
-version: 1.4.0
-contract: sdd-plan-doc-v1
-sdd_managed_starter: true
----
-
-${title}
-
-## Metadata
-
-- spec_id: \`onboarding\`
-- plan_id: \`onboarding\`
-- branch: \`${branch}\`
-
-## 0.1 Requirement Trace
-
-| Spec Item | Plan Section | Design Response |
-|---|---|---|
-| AC-1 | §13 Validation Plan | onboarding status check maps to validation evidence |
-| AC-2 | §14 Task Breakdown Rationale | starter task boundary protects user-authored documents |
-
-## 1. Background / Context
-
-${background}
-
-## 2. Goals and Non-goals
-
-${goals}
-
-## 3. Current State Analysis
-
-${currentState}
-
-## 4. Target Design Overview
-
-${targetDesign}
-
-## 5. Architecture / Component Design
-
-Use PlantUML when component impact is non-trivial.
-
-\`\`\`plantuml
-@startuml
-title Component Impact
-component \"Existing Module\" as Existing
-component \"Changed Module\" as Changed
-database \"Data Store\" as DB
-Existing --> Changed : call / event
-Changed --> DB : read / write
-@enduml
-\`\`\`
-
-## 6. Interaction / Sequence Design
-
-Add a PlantUML sequence or activity diagram when cross-component flow, async work, or concurrency matters.
-
-## 7. State / Data Design
-
-Describe state machines, data model changes, persistence, idempotency, and migration/rollback impact.
-
-## 8. Interface / API / Schema Design
-
-Describe API, DTO, event, contract, or schema compatibility impact. Write \`None\` only after checking.
-
-## 9. Concurrency / Transaction / Consistency Design
-
-Describe transaction boundaries, locking/idempotency/retry behavior, and consistency guarantees when relevant.
-
-## 10. Key Design Decisions
-
-| Decision | Reason | Tradeoff | Rejected alternatives |
-|---|---|---|---|
-| Replace with decision | Replace with reason | Replace with tradeoff | Replace with alternatives |
-
-## 11. Risk Control
-
-| Risk | Impact | Control |
-|---|---|---|
-| Replace with risk | Replace with impact | Replace with mitigation |
-
-## 12. Compatibility / Rollout / Rollback
-
-Describe compatibility, rollout, feature flag/manual gate if needed, and rollback strategy.
-
-## 13. Validation Plan
-
-| Acceptance | Validation Method | Command / Evidence |
-|---|---|---|
-| AC-1 | Manual/automated check | \`<command or artifact>\` |
-
-## 14. Task Breakdown Rationale
-
-Explain why \`specs/${branch}/tasks.md\` should be split into the planned task boundaries.
-
-## 15. Gaps / Assumptions
-
-- Gap or assumption.
-
-## 16. Risk-driven Plan Requirements
-
-- state-machine risk: include state/data design and a PlantUML state diagram.
-- concurrency risk: include sequence/activity diagram plus transaction/consistency design.
-- database risk: include data, transaction, migration, and rollback design.
-- api_schema risk: include interface/schema compatibility design.
-- security/sql risk: include explicit risk controls.
-
-## Phase Gate Checkpoint
-
-- ready_for_tasks: \`true | false\`
-- blockers: []
-- required_user_decisions: []
-`;
-}
-
-export function renderInitTasksDocument(branch: string, docsLanguage: string): string {
-  const zh = usesChineseInitDocs(docsLanguage);
-  const title = zh ? '# Tasks: Project Onboarding / 项目入门' : '# Tasks: Project Onboarding';
-  const boundary = zh
-    ? 'Allowed scope 仅限于把 starter onboarding scaffold 替换为项目专属的 SDD requirements、plan 和 tasks。'
-    : 'Allowed scope is limited to replacing this starter onboarding scaffold with project-specific SDD requirements, plan, and tasks.';
-  const implementationNotes = zh
-    ? '由 \`sdd init\` 创建，用作安全的 onboarding placeholder。开始真实 implementation 前必须替换。'
-    : 'Created by \`sdd init\` as a safe onboarding placeholder. Replace before real implementation.';
-  return `---
-template: sdd-init-onboarding-tasks-v1
-version: 1.4.0
-contract: sdd-tasks-doc-v1
-sdd_managed_starter: true
----
-
-${title}
-
-## 0. Metadata
-
-- tasks_id: \`onboarding\`
-- spec_id: \`onboarding\`
-- plan_id: \`onboarding\`
-- branch: \`${branch}\`
-- lifecycle_profile: \`direct\`
-- status: \`draft\`
-
-## 1. Delivery Map
-
-| Task | Spec Acceptance | Plan Section | Boundary Reason |
-|---|---|---|---|
-| ONBOARDING-1 | AC-1, AC-2 | §13 Validation Plan, §14 Task Breakdown Rationale | replace placeholders before real implementation |
-
-## 2. Wave Plan
-
-| Wave | Tasks | Gate |
-|---|---|---|
-| 1 | ONBOARDING-1 | user provides the first real feature/change request |
-
-## 3. Task List
-
-### ONBOARDING-1: Replace starter SDD documents with the first real task
-
-\`\`\`sdd-task
-id: ONBOARDING-1
-status: pending
-wave: 1
-depends_on: []
-acceptance_refs:
-  - AC-1
-  - AC-2
-plan_refs:
-  - "§13 Validation Plan"
-  - "§14 Task Breakdown Rationale"
-affected_files:
-  - specs/${branch}/spec.md
-  - specs/${branch}/plan.md
-  - specs/${branch}/tasks.md
-validation:
-  - sdd status --branch ${branch}
-risk: []
-agent_fit:
-  - scout
-  - planner
-  - spec-reviewer
-allowed_agents:
-  - scout
-  - planner
-  - spec-reviewer
-required_artifacts: []
-verification_availability:
-  - inspect:sdd status --branch ${branch}
-autonomy: direct_execution_allowed
-\`\`\`
-
-#### Boundary
-
-${boundary}
-
-Forbidden scope:
-
-- Do not create worktrees.
-- Do not start background agents.
-- Do not commit changes.
-- Do not claim truth-alignment or release approval automatically.
-
-#### Acceptance
-
-- AC-1: \`specs/${branch}/spec.md\` becomes a real requirement contract with objective, actors/scenarios, scoped requirements, AC IDs, assumptions/dependencies, and risk gates.
-- AC-2: \`specs/${branch}/plan.md\` maps spec acceptance to a task-ready technical solution document with risk-driven design sections and validation evidence.
-- AC-3: \`specs/${branch}/tasks.md\` maps acceptance/design refs to executable task blocks with boundary, agent/artifact/verification/autonomy fields, Definition of Done, and evidence expectations.
-
-#### Definition of Done
-
-- Starter placeholders are replaced by a real request.
-- Every task maps to spec acceptance refs.
-- High-risk tasks define required artifacts and reviewer/validator expectations.
-- \`sdd status --branch ${branch}\` reports no blocking document or task parser gaps.
-
-#### Evidence Expectations
-
-| Artifact | Expected Content |
-|---|---|
-| spec document | requirement contract with AC IDs |
-| plan document | technical solution with requirement trace and validation matrix |
-| tasks document | execution/evidence contract with task boundary and refs |
-
-#### Implementation Notes
-
-${implementationNotes}
-
-## 4. Dependency Notes
-
-- Single starter task only.
-- The \`wave: 1\` field is present only because the current parser requires a positive wave value; it must not be interpreted as permission to run background agents or multi-wave orchestration.
-
-## 5. Phase Gate Checkpoint
-
-- ready_for_implementation: \`false\`
-- blockers:
-  - Replace onboarding placeholders with real project requirements before implementation.
-- required_user_decisions:
-  - Confirm the first real feature/change request.
-`;
-}
-
-export function renderInitVerifyDocument(branch: string, docsLanguage: string): string {
-  const zh = usesChineseInitDocs(docsLanguage);
-  const title = zh ? '# Verify: Project Onboarding / 项目入门' : '# Verify: Project Onboarding';
-  const purpose = zh
-    ? '这份 verify.md 是从 starter tasks 派生的 verification guidance，不是 runtime evidence，也不替代 `sdd test <validation_unit_id-or-validation_text>` 产生的验证证据。'
-    : 'This verify.md is task-derived verification guidance, not runtime evidence, and it does not replace validation evidence produced by `sdd test <validation_unit_id-or-validation_text>`.';
-  const availability = zh
-    ? '在替换真实 spec/plan/tasks 前，只能检查 onboarding scaffold 是否仍然可见且未被误当作已批准实现。'
-    : 'Before replacing the real spec/plan/tasks, verification can only inspect that the onboarding scaffold is visible and not mistaken for approved implementation.';
-  return `---
-template: sdd-init-onboarding-verify-v1
-version: 1.4.0
-contract: sdd-verify-doc-v1
-sdd_managed_starter: true
-branch: ${branch}
-author_role: verification-designer
-independent_from_roles:
-  - task-planner
-  - implementer
----
-
-${title}
-
-## 1. Purpose
-
-${purpose}
-
-## 2. Task Verification Matrix
-
-| Task | Acceptance refs | Validation commands | Required artifacts | Verification availability |
-|---|---|---|---|---|
-| ONBOARDING-1 | AC-1<br>AC-2 | sdd status --branch ${branch}<br>sdd test task-ONBOARDING-1 --branch ${branch} | none | ${availability} |
-
-## 3. Verification Rules
-
-- This starter verify contract does not authorize source changes, validation execution, runtime mutation, truth-alignment approval, commit, push, publish, or release.
-- Replace starter spec, plan, tasks, and verify documents with a real branch contract before implementation.
-- Runtime PASS is judged by \`sdd test <validation_unit_id-or-validation_text> --branch ${branch}\` consuming the current verify contract; \`sdd test task|batch|wave\` remains available for explicit low-level diagnostics.
-- Re-run \`sdd verifies write --branch ${branch} --force\` only after reviewing changed task expectations.
-
-## 4. Out of Scope
-
-- This document is not evidence in \`.sdd/runtime.sqlite\`.
-- This document is not a release, ship, or truth-alignment approval.
-`;
-}
+
+
+function usesChineseInitDocs(value: string): boolean {
+  return value === 'zh-CN';
+}
+
+export function renderInitSpecDocument(branch: string, timestamp: string, docsLanguage: string): string {
+  const zh = usesChineseInitDocs(docsLanguage);
+  const title = zh ? '# Spec: Project Onboarding / 项目入门' : '# Spec: Project Onboarding';
+  const reframing = zh
+    ? `Surface request: 初始化 SDD。\nReframed problem: 仓库需要一个安全可见的 SDD 入口，但这不是可执行产品需求。\nInferred intent: 在第一个真实变更前建立 spec/plan/tasks 的语义边界。\nObservable success: \`sdd status --branch ${branch}\` 能看到 starter documents，且后续实现不会把 onboarding scaffold 当作批准需求。`
+    : `Surface request: initialize SDD.\nReframed problem: the repository needs a safe visible SDD entrypoint, but this is not an executable product requirement.\nInferred intent: establish semantic boundaries for spec, plan, and tasks before the first real change.\nObservable success: \`sdd status --branch ${branch}\` can see starter documents, and later implementation does not treat this onboarding scaffold as approved requirements.`;
+  const unchanged = zh
+    ? '不会授权实现代码、迁移、测试执行、发布或长期 backlog；第一个真实请求必须替换本 starter spec。'
+    : 'This does not authorize implementation code, migrations, validation execution, release, or a long-lived backlog; the first real request must replace this starter spec.';
+  const openQuestion = zh
+    ? '第一个真实功能或变更请求是什么？'
+    : 'What is the first real feature or change request?';
+  return `---
+template: sdd-init-onboarding-spec-v3
+version: 3.0.0
+contract: sdd-spec-doc-v3
+sdd_managed_starter: true
+---
+
+${title}
+
+## 0. Metadata
+
+- spec_id: \`onboarding\`
+- branch: \`${branch}\`
+- source_request: \`Created by sdd init\`
+- status: \`draft\`
+- created_at: \`${timestamp}\`
+- updated_at: \`${timestamp}\`
+
+## 1. Problem Reframing / Intent Discovery
+
+${reframing}
+
+## 2. Change Delta
+
+| Area | Before | After | Unchanged |
+|---|---|---|---|
+| SDD entry | no starter semantic documents | starter spec/plan/tasks/verify exist for \`${branch}\` | ${unchanged} |
+
+## 3. Users / Actors
+
+| Actor | Need / Expectation | Current Pain |
+|---|---|---|
+| repository maintainer | ${zh ? '安全可见的 SDD 入口' : 'safe visible SDD entrypoint'} | ${zh ? '还没有项目专属 SDD 请求' : 'no project-specific SDD request has been written yet'} |
+
+## 4. Scope
+
+### In Scope
+
+- Confirm the project is initialized with visible starter semantic documents.
+- Replace onboarding placeholders with a real spec, plan, and tasks before implementation.
+
+### Out of Scope
+
+- Implementation code, migrations, validation execution, release, commits, worktrees, or background agents.
+- Long-term backlog management.
+
+## 5. Requirements
+
+| ID | Requirement | Priority | Source |
+|---|---|---|---|
+| FR-1 | \`sdd init\` creates runtime config and starter semantic documents. | Must | init |
+| FR-2 | \`sdd status --branch ${branch}\` can inspect the initialized branch without missing document gaps. | Must | status |
+
+## 6. Acceptance Criteria
+
+| ID | Acceptance | Evidence Target | Priority |
+|---|---|---|---|
+| AC-1 | \`sdd status --branch ${branch}\` reports starter spec, plan, and tasks documents as present. | CLI status output | Must |
+| AC-2 | Existing user-authored semantic documents are preserved unless force is explicitly requested. | init preserve behavior | Must |
+
+## 7. Non-goals / Invariants
+
+- Do not treat onboarding as approval for product implementation.
+- Do not infer a technical solution from this starter document.
+- Keep runtime truth in runtime close/state; this Markdown remains a starter semantic artifact until replaced and accepted.
+
+## 8. Open Questions / Ambiguity Ledger
+
+| ID | Type | Question / Assumption | Route |
+|---|---|---|---|
+| Q-1 | blocking user decision | ${openQuestion} | replace this spec before plan |
+| A-1 | assumption | starter docs are placeholders only | keep explicit in plan/tasks |
+| D-1 | deferred to plan/tasks | concrete implementation surfaces and validation coverage | plan/tasks after real spec |
+
+## 9. Close Quality Evidence
+
+- problem_reframed: \`yes\`
+- change_delta_defined: \`starter initialization only\`
+- unchanged_behavior_defined: \`yes\`
+- blocking_user_decisions_listed: \`yes\`
+- ready_for_plan: \`false until replaced by a real request\`
+`;
+}
+
+export function renderInitPlanDocument(branch: string, timestamp: string, docsLanguage: string): string {
+  const zh = usesChineseInitDocs(docsLanguage);
+  const title = zh ? '# Plan: Project Onboarding / 项目入门' : '# Plan: Project Onboarding';
+  const strategy = zh
+    ? '这是一份轻量 starter plan，占位用途是说明 plan 阶段必须在真实 spec 之后给出 grounded technical design，而不是直接授权实现或填满强合约表单。'
+    : 'This is a lightweight starter plan. Its placeholder purpose is to show that plan must provide grounded technical design after a real spec, not directly authorize implementation or fill a heavy contract form.';
+  const boundary = zh
+    ? 'starter docs 是一个文档替换 rollback unit；不要把 spec、plan、tasks 分成互相覆盖的执行任务。'
+    : 'starter docs are one document-replacement rollback unit; do not split spec, plan, and tasks into execution tasks that overwrite each other.';
+  return `---
+template: sdd-init-onboarding-plan-v3
+version: 3.0.0
+contract: sdd-plan-doc-v3
+sdd_managed_starter: true
+---
+
+${title}
+
+## 0. Metadata
+
+- spec_id: \`onboarding\`
+- plan_id: \`onboarding\`
+- branch: \`${branch}\`
+- status: \`draft\`
+- created_at: \`${timestamp}\`
+- updated_at: \`${timestamp}\`
+
+## 1. Upstream Contract Trace
+
+| Spec Source | Plan Response | Notes |
+|---|---|---|
+| FR-1 / FR-2 | starter initialization route | replace with real trace before implementation |
+| AC-1 / AC-2 | status and preserve checks | starter evidence only |
+
+## 2. Planning Problem / Strategy Framing
+
+${strategy}
+
+## 3. Current State Analysis
+
+- The repository has SDD scaffolding but no accepted real change request.
+- Current spec/plan/tasks are onboarding placeholders.
+- Runtime close remains the authority for accepted stage artifacts.
+
+## 4. Target Design Overview
+
+Replace onboarding documents with project-specific spec, plan, and tasks before execution. The target plan must describe implementation surfaces, state/data/API impact, rollback, and validation coverage for the real request.
+
+## 5. Change Topology / Responsibility Boundaries
+
+| Boundary | Owner | Write Surface | Rollback Unit |
+|---|---|---|---|
+| onboarding document replacement | SDD editor | \`specs/${branch}/spec.md\`, \`specs/${branch}/plan.md\`, \`specs/${branch}/tasks.md\` | onboarding-documents |
+
+${boundary}
+
+## 6. Interface / API / Schema Impact
+
+None for the starter scaffold. Re-evaluate after the first real spec.
+
+## 7. State / Data / Migration Impact
+
+None for the starter scaffold. Re-evaluate after the first real spec.
+
+## 8. Validation Strategy
+
+| Acceptance | Validation Method | Evidence |
+|---|---|---|
+| AC-1 | \`sdd status --branch ${branch}\` | document visibility status |
+| AC-2 | preserve/force behavior | init behavior or focused test |
+
+## 9. Risk Control
+
+| Risk | Impact | Control |
+|---|---|---|
+| starter mistaken for implementation plan | vague work enters execute | require replacement spec/plan/tasks before implementation |
+| split creates overlapping writers | rollback confusion | keep onboarding replacement as one rollback unit |
+
+## 10. Rollback Strategy
+
+Restore starter documents or replace all semantic documents coherently with reviewed real branch documents.
+
+## 11. Implementation Notes
+
+Do not implement source code from this plan. This plan only explains how to replace onboarding placeholders safely.
+
+## 12. Open Plan Questions
+
+- What is the first real feature or change request?
+- Which implementation surfaces does the real request touch?
+- Which validation evidence will close the real acceptance criteria?
+
+## 13. Task-stage Constraints
+
+Forbidden: task IDs, task lists, execution waves, dependency graph, \`workType\`, \`executionLane\`, \`sdd-task\` blocks, implementation checklist.
+
+Tasks stage should create exactly the executable work-unit orchestration needed after a real plan exists. It must preserve writable ownership and rollback boundaries.
+
+## 14. Close Quality Evidence
+
+- implementation strategy contract: \`starter only\`
+- upstream trace checked: \`starter\`
+- writable ownership risk noted: \`yes\`
+- ready_for_tasks: \`false until replaced by a real plan\`
+`;
+}
+
+export function renderInitTasksDocument(branch: string, timestamp: string, docsLanguage: string): string {
+  const zh = usesChineseInitDocs(docsLanguage);
+  const title = zh ? '# Tasks: Project Onboarding / 项目入门' : '# Tasks: Project Onboarding';
+  const boundary = zh
+    ? 'Allowed scope 仅限于把 starter onboarding scaffold 替换为项目专属的 SDD spec、plan 和 tasks；不得直接进入实现。'
+    : 'Allowed scope is limited to replacing this starter onboarding scaffold with project-specific SDD spec, plan, and tasks; do not proceed directly to implementation.';
+  const completionEvidence = zh
+    ? '更新后的 spec.md、plan.md、tasks.md diff，以及 `sdd status --branch ${branch}` 输出。'
+    : 'Updated spec.md, plan.md, tasks.md diff plus `sdd status --branch ${branch}` output.';
+  return `---
+template: sdd-init-onboarding-tasks-v3
+version: 3.0.0
+contract: sdd-tasks-doc-v3
+sdd_managed_starter: true
+---
+
+${title}
+
+## 0. Metadata
+
+- tasks_id: \`onboarding\`
+- spec_id: \`onboarding\`
+- plan_id: \`onboarding\`
+- branch: \`${branch}\`
+- status: \`draft\`
+- created_at: \`${timestamp}\`
+- updated_at: \`${timestamp}\`
+- produced_by: \`sdd init\`
+
+## 1. Projection Inputs
+
+| Upstream Source | Accepted Ref / Hash | Projected Meaning |
+|---|---|---|
+| \`specs/${branch}/spec.md\` | \`starter\` | starter onboarding problem and non-implementation boundary |
+| \`specs/${branch}/plan.md\` | \`starter\` | replace placeholders coherently before execute |
+
+## 2. Projection and Split Strategy
+
+- Projection rule: synthesize the starter spec/plan into one docs-only replacement task; do not copy the starter documents into the task body.
+- Primary split axis: \`single onboarding replacement unit\`
+- Split rationale: spec、plan、tasks placeholders must be replaced coherently before execute receives real implementation context.
+- Merge rationale: splitting starter replacement can leave downstream stages with misleading partial context.
+- Out of scope: implementation code, validation execution, worktrees, commits, sync-back, release.
+
+## 3. Change Boundary / Rollback Map
+
+| Change Surface / Domain Area | Primary Task | Other Touches | Boundary / Rollback Note |
+|---|---|---|---|
+| project SDD starter documents | \`ONBOARDING-1\` | \`None\` | replace the three starter docs together or restore them together |
+
+No task overlap is allowed in this starter scaffold.
+
+## 4. Execution Topology
+
+| Wave | Tasks | Purpose | Dependency Gate |
+|---|---|---|---|
+| 1 | \`ONBOARDING-1\` | replace placeholders with real SDD documents | user provides the first real feature/change request |
+
+## 5. Work Units
+
+### ONBOARDING-1: Replace starter SDD documents with the first real request
+
+#### Execution Signal
+
+- Task kind: \`docs\`
+- Primary lane: \`docs\`
+- Supporting lanes: \`none\`
+- Execute mode: \`document\`
+
+
+#### Task Projection
+
+- Outcome this task contributes to: the project has real spec、plan、tasks documents before any execute work starts.
+- Current state: starter onboarding documents describe placeholders only.
+- Target state: the first real request is projected into project-specific spec、plan、tasks documents.
+- Plan decision to preserve: starter replacement is one coherent docs rollback unit, not implementation authorization.
+
+#### Change Boundary
+
+Allowed:
+
+- replace \`specs/${branch}/spec.md\`
+- replace \`specs/${branch}/plan.md\`
+- replace \`specs/${branch}/tasks.md\`
+
+Out of scope:
+
+- source code changes
+- validation command execution
+- commits, release, sync-back, or worktree operations
+
+Overlap / rollback note:
+
+- ${boundary}
+
+#### Implementation Direction
+
+Use the user's first real feature or change request to replace the starter documents. The replacement tasks.md should project the accepted spec/plan meaning into execute-ready task briefs, not paste upstream text or expose platform schema as the main content.
+
+- Start from: the user's first real feature or change request and the starter documents under \`specs/${branch}/\`.
+- Change sequence:
+  1. Replace starter spec with the real problem and acceptance meaning.
+  2. Replace starter plan with the real implementation strategy and boundaries.
+  3. Replace starter tasks with execute-ready task projections from the accepted spec/plan.
+- Preserve: docs-only onboarding; no implementation authorization before real tasks are accepted.
+- Avoid: source code changes, validation execution, commits, release, sync-back, or worktree operations.
+
+#### Execute Readiness Check
+
+After reading this task alone, execute should know:
+
+- Where to start: \`specs/${branch}/spec.md\`, \`specs/${branch}/plan.md\`, and \`specs/${branch}/tasks.md\`.
+- What to change first: replace the starter spec with the first real request.
+- What behavior must change: placeholder SDD documents become project-specific accepted documents.
+- What must not change: source code and release state stay untouched.
+- How to know this task is complete: ${completionEvidence}
+
+#### Runtime Anchors
+
+\`\`\`sdd-task
+id: ONBOARDING-1
+status: pending
+workType: docs
+executionLane: docs
+wave: 1
+dependencies: []
+primaryWritableOwnership:
+  - specs/${branch}/spec.md
+  - specs/${branch}/plan.md
+  - specs/${branch}/tasks.md
+touches:
+  - specs/${branch}/spec.md
+  - specs/${branch}/plan.md
+  - specs/${branch}/tasks.md
+completionEvidence:
+  - ${completionEvidence}
+failureRoute: tasks-revise
+\`\`\`
+
+#### Completion Evidence
+
+${completionEvidence}
+
+#### Validation Handoff
+
+- Covered by: \`sdd status --branch ${branch}\`
+- That validation must prove: the replacement documents are visible to runtime status.
+- If validation fails:
+  - revisit this task when: one of the starter documents was not replaced coherently.
+  - revise tasks when: the starter replacement boundary is no longer docs-only.
+  - revise plan/spec when: the first real request lacks enough problem or strategy context.
+
+## 6. Dependency / Ordering Rationale
+
+- \`ONBOARDING-1\` is the only starter task.
+- The onboarding docs are one rollback unit because partial replacement can leave misleading downstream context.
+
+## 7. Validation / Acceptance Coverage
+
+| Projected Acceptance / Risk | Covered By | Coverage Meaning | Notes |
+|---|---|---|---|
+| starter documents are replaced coherently | \`ONBOARDING-1\`, \`sdd status --branch ${branch}\` | task | starter document visibility only |
+
+This starter task has completion evidence but no independent product acceptance validation.
+
+## 8. Failure Routing / Repair Policy
+
+| Failure Type | Route | Reason |
+|---|---|---|
+| placeholder replacement incomplete | \`tasks-revise\` | starter task boundary is still docs-only |
+| first real request unclear | \`spec-revise\` | accepted spec must define the real problem before planning |
+| design boundary missing | \`plan-revise\` | accepted plan must define executable surfaces before task execution |
+
+## 9. Open Execution Questions
+
+- What is the first real feature or change request?
+- Which docs language should the project use for long-lived SDD prose?
+
+## 10. Tasks Close Quality Evidence
+
+- accepted spec ref/hash checked: \`starter\`
+- accepted plan ref/hash checked: \`starter\`
+- task projection synthesizes starter spec/plan meaning: \`yes — docs-only replacement\`
+- change boundaries and rollback map reviewed: \`yes — one onboarding rollback unit\`
+- completion evidence defined: \`yes\`
+- validation handoff mapped: \`yes — status visibility only\`
+- task-review-agent verdict: \`not run for init scaffold\`
+`;
+}
+
+