lee-spec-kit 0.9.10 → 0.9.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lee-spec-kit",
-  "version": "0.9.10",
+  "version": "0.9.13",
   "description": "Document-centered harness engineering toolkit for AI agent development",
   "type": "module",
   "bin": {
@@ -11,7 +11,9 @@
   "files": [
     "dist",
     "templates",
-    "assets"
+    "assets",
+    "resources",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "keywords": [
     "docs",
@@ -26,7 +28,7 @@
     "workflow"
   ],
   "author": "Lee Yoonsu",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "engines": {
     "node": ">=18.0.0"
   },

package/resources/openwiki-skills/lee-spec-kit-technical-writing/.lee-spec-kit-skill.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "owner": "lee-spec-kit",
+  "adapterId": "lee-spec-kit.technical-writing",
+  "skillName": "lee-spec-kit-technical-writing"
+}

package/resources/openwiki-skills/lee-spec-kit-technical-writing/LICENSE.md

@@ -0,0 +1,9 @@
+# License and attribution
+
+The files in this `lee-spec-kit-technical-writing` skill directory are licensed under the [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International license](https://creativecommons.org/licenses/by-nc-sa/4.0/).
+
+They are an adapted and condensed work based on [Technical Writing](https://github.com/toss/technical-writing), copyright Viva Republica, Inc., which is distributed under the same CC BY-NC-SA 4.0 license.
+
+Changes made for lee-spec-kit include reorganizing the source guidance into an agent skill, condensing it around code-grounded repository documentation, adding an OpenWiki-specific workflow and review checklist, and writing new adapter and evidence-boundary instructions. This notice does not imply endorsement by the original author.
+
+The CC BY-NC-SA 4.0 license applies only to this skill directory. It does not replace the MIT license for lee-spec-kit source code or other package contents.

package/resources/openwiki-skills/lee-spec-kit-technical-writing/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: lee-spec-kit-technical-writing
+description: Plan, write, and revise code-grounded OpenWiki documentation around a new developer's goal. Use for every reader-facing repository Knowledge page, including tutorials, how-to guides, explanations, references, and onboarding navigation.
+license: CC-BY-NC-SA-4.0
+---
+
+# OpenWiki Technical Writing
+
+Make the repository easier to understand without weakening evidence or inventing facts.
+
+## Plan the Knowledge route
+
+1. Identify the new developer's immediate question.
+2. Classify the page as a tutorial, how-to guide, explanation, or reference.
+3. Build the smallest complete route around reader goals. Do not mirror the source tree or target a fixed page count.
+4. Give each page one primary goal. Split a page when its sections serve different goals, but keep one short connected flow together.
+5. When planning page jobs, copy the applicable writing instructions into every job. A later page worker must not have to infer the writing policy from the page path or neighboring output.
+6. Include the reader question and document type in each job's purpose and instructions. The page title and outline must answer that question; a system name alone is not a reader goal.
+
+Read [information-architecture.md](references/information-architecture.md) and [document-patterns.md](references/document-patterns.md) before submitting a repository page plan.
+
+## Write each page
+
+1. Gather tracked repository evidence before outlining the answer.
+2. Put the reader's result, conclusion, or next action first.
+3. Arrange sections in the order a new developer needs them.
+4. Use specific headings, stable terminology, concrete subjects, and short sentences that carry one main idea.
+5. Link prerequisite, neighboring, and next-step pages where they remove guesswork.
+6. Add at least one descriptive Markdown source link to every generated reader-facing page except the index. Use `[label](repo://path)` or `[label](repo://path#Lx-Ly)` and prefer a stable line range when it points the reader to the relevant contract. Reserve `repo://` for tracked source files included in the repository fingerprint. Link another Knowledge page with a page-relative Markdown path, never `/openwiki/...` or `repo://openwiki/...` hrefs. Claim sidecars and inline code citations do not satisfy this requirement.
+7. Resolve every Knowledge link to the exact planned path, including `.md`, but write its href relative to the current page directory. From `/openwiki/architecture/system.md` to `/openwiki/operations/workers.md`, use `../operations/workers.md`. Canonical `/openwiki/...` identifiers belong in plans and metadata; OpenWiki visualize 0.5.0 requires relative Markdown hrefs. Do not infer a shortened slug or extensionless alias.
+8. Write Markdown URL targets with literal `/` characters. Never JSON-escape a Knowledge link as `\/openwiki\/...` or insert backslashes before slashes.
+9. Finish the draft before editing it. In this second stage, choose one dominant document type, separate unrelated reader goals, and revise every paragraph for focus and natural terminology. Do not submit the first draft.
+10. In the final stage, reconcile commands, conditions, exceptions, links and Claims with the edited prose, then submit the page. Check that every `repo://` target is a tracked regular file; directories belong in code notation or need a link to a relevant file inside them. Keep all three stages in the page job, without a separate model, score, or review artifact.
+
+Technical accuracy is the hard constraint. If evidence is missing or conflicting, state the uncertainty instead of making the prose sound complete.
+
+Unavailable input does not prove that a file is absent from the repository. Use available tracked-file metadata to check existence without opening excluded content. If that metadata is unavailable, describe the visibility limit instead of claiming absence. Do not relax ignore rules or read secrets to remove uncertainty.
+
+## Load page-specific guidance
+
+- Read [document-patterns.md](references/document-patterns.md) and use the pattern matching the assigned page type.
+- Read [information-architecture.md](references/information-architecture.md) when changing page scope, order, headings, or cross-links.
+- For Korean output, read [korean-style.md](references/korean-style.md) before drafting or revising any reader-facing prose, including frontmatter descriptions.
+
+## Final review
+
+- Can a new developer tell within the opening section what this page helps them do or understand?
+- Does the page answer one primary question without hiding another document inside it?
+- Are commands, paths, identifiers, boundaries, and runtime sequences exact and evidence-backed?
+- Does every generated reader-facing page except the index contain at least one useful `repo://` Markdown source link?
+- Does every page-relative Knowledge href resolve to the exact planned page, including `.md`, without a root-leading slash?
+- Do Markdown URL targets use literal forward slashes without backslashes?
+- Are prerequisites introduced before dependent concepts?
+- Do headings describe their section instead of using vague labels such as “Details” or “Overview” repeatedly?
+- Are important terms used consistently throughout the page and neighboring pages?
+- Does every link help the reader prepare, understand context, or continue?
+- Does the page distinguish current runtime facts from requirements, plans, and historical decisions?
+- For Korean output, does the page keep the same reader-friendly speech level without falling back to declarative `-다` or formal `-습니다` prose?
+
+## License boundary
+
+This adapted skill is separately licensed under CC BY-NC-SA 4.0. See [LICENSE.md](LICENSE.md) for attribution and scope.

package/resources/openwiki-skills/lee-spec-kit-technical-writing/references/document-patterns.md

@@ -0,0 +1,54 @@
+# Document patterns
+
+Choose the pattern from the reader's goal, not from the source files available.
+
+## Tutorial
+
+Use when a new developer needs guided experience.
+
+1. State the result they will reach.
+2. List only required prerequisites.
+3. Present a safe, reproducible sequence.
+4. Show checkpoints that confirm progress.
+5. End with the next useful concept or task.
+
+## How-to guide or troubleshooting
+
+Use when the reader has a concrete task or failure.
+
+1. Name the goal or symptom precisely.
+2. State assumptions and required state.
+3. Give ordered actions with observable results.
+4. Explain important branches and recovery steps.
+5. Link deeper explanations instead of interrupting the procedure.
+
+## Reference
+
+Use when the reader needs exact facts during work.
+
+1. Define scope and version assumptions.
+2. Organize entries predictably.
+3. Keep fields, paths, commands, defaults, and constraints exact.
+4. Use tables only when repeated fields are genuinely easier to compare.
+5. Add examples that clarify the contract without replacing it.
+
+## Explanation
+
+Use when the reader needs a mental model.
+
+1. Lead with the core idea or boundary.
+2. Connect components through cause, data flow, or ownership.
+3. Explain why the structure exists only when repository evidence supports it.
+4. Separate current behavior from requirements and historical decisions.
+5. End with practical implications for navigation or change.
+
+One page may contain a small supporting section of another type, but one pattern should remain dominant.
+
+Use goal-oriented titles when they help the reader choose a page:
+
+- tutorial: “Start CopySinger locally”;
+- how-to: “Choose tests for a change”;
+- explanation: “Understand job leases and recovery”;
+- reference: “Environment variables”.
+
+Do not force an action title on a reference page when a stable lookup noun is clearer.

package/resources/openwiki-skills/lee-spec-kit-technical-writing/references/information-architecture.md

@@ -0,0 +1,53 @@
+# Information architecture
+
+Design the page around the reader's route through the repository.
+
+## Start from the reader's purpose
+
+Use these four document types as the default navigation model:
+
+- `tutorials/`: a guided learning path that reaches a working result;
+- `how-tos/`: a concrete task or problem to finish;
+- `explanations/`: a mental model, boundary, or design reason to understand;
+- `reference/`: exact values, contracts, states, commands, or paths to look up.
+
+OpenWiki generates directory indexes itself; do not include those indexes in a page plan or edit their control fields. Use the required `/openwiki/quickstart.md` as the human entrypoint and group its navigation links by reader purpose. Use a system-oriented group such as `architecture/` or `operations/` only when it is clearer for the reader than the four default types; do not create both groupings for the same content.
+
+Before choosing a path, record the reader question and document type in the page job. “How do I start the app locally?” is a tutorial; “How do I recover a failed job?” is a how-to; “Why does a worker need a lease?” is an explanation; “Which values configure a worker?” is a reference. Separate these goals even when they share source files. Pass this classification to the page worker through the job purpose and instructions, without requiring a new frontmatter schema.
+
+This is a planning preference, not a page-count target. A small repository may need only a few pages. A large repository should split pages only where the reader's goal, prerequisite, or evidence ownership changes.
+
+## Scope one primary topic
+
+A page should resolve one main question. Split material when sections serve different goals, require different prerequisites, or need to be maintained by different evidence.
+
+Keep closely related facts together. Do not split a short, sequential explanation merely to produce more pages.
+
+## Order by reader need
+
+Use this default sequence when it fits:
+
+1. What this page explains and why it matters
+2. Prerequisites or surrounding context
+3. Main components or steps
+4. Boundaries, exceptions, and failure behavior
+5. Where to go next
+
+Put the value or conclusion before background that only makes sense afterward. Introduce a term before relying on it.
+
+## Use informative headings
+
+Headings should let a reader predict the section's content. Prefer “How a vocal analysis job reaches the worker” over “Runtime flow”. Keep sibling headings grammatically parallel when they represent comparable concepts.
+
+## Build useful routes
+
+Link only when it reduces navigation work:
+
+- prerequisite: what the reader must know first;
+- context: a related boundary or concept;
+- next step: where the reader can continue a task;
+- evidence: the tracked file supporting a factual claim.
+
+Use descriptive link text. Avoid unexplained chains of “here”, raw host paths, or duplicate links that lead to the same destination.
+
+Keep canonical `/openwiki/...md` paths for planning and page identity. In Markdown, use links relative to the current page: `../quickstart.md` from a one-level-deep page, or `../operations/workers.md` between sibling sections. This lets OpenWiki visualize resolve the intended relationship. Do not add unrelated links or duplicate indexes solely to make the graph connected.

package/resources/openwiki-skills/lee-spec-kit-technical-writing/references/korean-style.md

@@ -0,0 +1,71 @@
+# Korean technical style
+
+Write Korean that reads naturally while preserving code-level precision.
+
+## Keep a reader-friendly voice
+
+- Use `해요체` for explanations: `사용해요`, `확인할 수 있어요`, `경계예요`.
+- Use `-하세요` when the reader needs to act: `명령을 실행하세요`, `상태를 확인하세요`.
+- Do not fall back to declarative `-다` prose or formal `-습니다` prose. Do not mix speech levels to vary sentence endings.
+- Keep warnings direct and respectful. State the risk, then tell the reader what to do.
+- Preserve literal identifiers and quoted runtime text even when their wording does not follow this voice.
+
+## Prefer direct sentences
+
+- Put the actual actor in the subject when ownership matters.
+- Use a concrete verb instead of turning an action into an abstract noun.
+- Keep one main idea per sentence. Split a sentence when conditions and results compete for attention.
+- Remove framing such as “살펴보겠습니다” when the content can begin directly.
+- Avoid opening with “이 문서는 … 설명해요” when the result or problem can be stated directly.
+- Prefer specific paths, states, and outcomes over vague words such as “관련”, “처리”, or “부분”.
+
+## Write titles for scanning
+
+- Use a concrete goal or concept rather than a stack of nouns joined with punctuation.
+- For a tutorial or how-to, prefer `시작하기`, `변경하기`, `찾기`, or `해결하기`.
+- For an explanation, prefer `이해하기` when it makes the reader's purpose clearer.
+- For a reference, a stable noun title such as `환경 변수` or `작업 상태` is often clearer than an artificial action title.
+
+## Keep terms stable
+
+Use Korean for ordinary explanatory words: `worker` → `워커`, `ownership` → `소유권`, `lifecycle` → `수명 주기`, `focused test` → `변경 범위 테스트`, `persist` → `저장`, `retry` → `재시도`. These examples apply to prose, not identifiers: keep `leaseOwner`, `MixingJob`, `pnpm test`, product names, and exact API fields unchanged. Explain an unfamiliar term once, then use the same wording. Do not translate an identifier merely to make a sentence look more Korean.
+
+For example, prefer “워커는 작업의 소유권을 확인한 뒤 결과를 저장해요” over “worker는 job ownership을 확인한 뒤 result를 persist해요”. Both sentences must still be supported by the same source evidence.
+
+Choose one Korean term for each concept and reuse it. Keep identifiers, commands, paths, model names, and public API names unchanged. Add a short Korean explanation the first time an unfamiliar English term appears; do not alternate translations afterward.
+
+## Edit paragraph density
+
+Give each paragraph one point. Start with the behavior or result, then explain its condition or reason. When a paragraph moves from setup commands to runtime theory or troubleshooting, move that material to its own section or link to the corresponding planned page. Use a table for exact values and an ordered list for dependent actions. Do not remove exceptions, limits, or failure behavior just to shorten the text, and do not split one connected idea to satisfy a sentence-count target.
+
+## Control density
+
+Use paragraphs for a connected explanation, ordered lists for sequences, bullets for independent choices, and tables for repeated comparisons. Do not turn every sentence into a bullet. Put conditions before an action only when the reader must check them first.
+
+## Make relationships explicit
+
+Name what changed, what caused it, and what observes the result. Avoid omitted subjects when two services, processes, or documents could be the actor. State whether a described rule is a current code fact, durable requirement, active plan, or historical decision.
+
+## Read once for rhythm
+
+After checking facts, read the page as prose. Vary sentence structure without changing speech level, remove unnecessary passive forms, and shorten stacked modifiers. Do not trade exact meaning for variety.
+
+## Rewrite dense repository prose
+
+Before:
+
+> 이 문서는 시스템 경계와 요청 표면을 설명한다. 브라우저 요청은 서버에서 처리되며 작업은 큐에 기록된다.
+
+After:
+
+> 짧은 웹 요청과 오래 걸리는 작업을 분리해요. 서버는 작업을 큐에 기록하고 바로 응답해요. 워커가 남은 처리를 이어가요.
+
+Before:
+
+> 환경 변수 설정 및 데이터베이스 마이그레이션 수행
+
+After:
+
+> 로컬 데이터베이스 준비하기
+
+The rewrite changes presentation, not facts. Keep exact commands, identifiers, limits, states, and failure behavior grounded in repository evidence.

package/templates/en/common/README.md

@@ -56,12 +56,18 @@ Keep product roadmaps in `prd/`, but manage implementation sequencing and work p
 
 ### Knowledge Architecture and authority
 
-1. Feature SDD (`spec.md`, `plan.md`, `tasks.md`, `decisions.md`) is normative for requirements, scope, decisions, and acceptance.
-2. Human-owned PRD, architecture, onboarding, and operations documents are the curated project-wide current state.
-3. `openwiki/` is a derived onboarding and code-navigation layer. Verify its claims against tracked source, tests, schemas, and curated docs.
+| Claim type                                                           | Authority                                                                                    |
+| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Product intent and durable requirements                              | PRD; an active Feature links and narrows them, and requirement changes are backfilled to PRD |
+| Active change scope, status, design decisions, tasks, and acceptance | The active Feature SDD (`spec.md`, `plan.md`, `tasks.md`, `decisions.md`)                    |
+| Project-wide explanations and policy                                 | Human-owned architecture, onboarding, operations, design, and agent-policy docs              |
+| Executable runtime facts                                             | Tracked code, schemas, migrations, and configuration; tests are verification evidence        |
+| Onboarding and code navigation                                       | Derived `openwiki/` Knowledge, verified against the authorities above                        |
 
 Every Plan must complete `Curated Documentation Impact`, including explicit `NONE` decisions. Every `UPDATE` or `ADD` target must be attached to at least one task through its `Docs` list and committed with the active Feature scope before completion. This propagation rule applies whether OpenWiki is enabled or not.
 
+Schema 2 keeps four common surfaces in the core assessment and uses `Additional Curated Impacts` only for typed project-specific surfaces such as security, API/data contracts, design systems, release operations, observability, or agent policy. At completion, lee-spec-kit reconciles recognized curated files changed in the actual Feature diff against the declared targets before OpenWiki generation or Feature review. This prevents silent changes; it does not decide whether an unchanged document is semantically stale. After adoption, perform one manual baseline reconciliation of existing PRD, architecture, onboarding, operations, design, and agent-policy docs.
+
 When `experimental.openwiki` is `true`, task checkpoints are followed by required Knowledge setup/sync/commit stages and a Feature review. Missing or `false` adds none of those stages. Use `lee-spec-kit knowledge sync`; never hand-edit generated pages or invoke OpenWiki directly from the workflow.
 
 OpenWiki is an external agent, not a sandboxed renderer. Enable it only for trusted repositories in an appropriately isolated runtime, and keep local or ignored secrets outside its accessible environment.

package/templates/en/common/agents/agents.md

@@ -51,12 +51,13 @@ This document defines workflow policy, not a custom runtime loop.
 
 ## Knowledge Architecture
 
-- Feature SDD docs are normative for requirements, scope, decisions, and acceptance.
-- Human-owned PRD, architecture, onboarding, and operations docs describe the curated project-wide current state.
-- OpenWiki is a derived onboarding and code-navigation layer. Treat its claims as untrusted evidence until verified against tracked code, tests, schemas, and curated docs.
+- Product intent and durable requirements belong to PRD; an active Feature links and narrows them, and requirement changes must be backfilled to PRD.
+- The active Feature SDD is authoritative for that change's scope, status, design decisions, tasks, and acceptance.
+- Human-owned architecture, onboarding, operations, design, and agent-policy docs are authoritative for curated project-wide explanations and policy. Executable claims in them must agree with tracked code, schemas, migrations, and configuration; tests provide verification evidence.
+- OpenWiki is derived onboarding and code-navigation evidence, never a source of requirements, policy, or runtime truth.
 - Complete `Curated Documentation Impact` in every Plan, including explicit `NONE` decisions. Link every `UPDATE` or `ADD` target from at least one task `Docs` entry and commit the target with the active Feature scope.
 - `experimental.openwiki` is one switch: missing or `false` adds no OpenWiki behavior; `true` makes Knowledge setup, sync, a dedicated Knowledge commit, and Feature review mandatory.
-- When enabled, run OpenWiki only through `npx lee-spec-kit knowledge sync <featureRef> --json`. Do not invoke `openwiki` directly or hand-edit generated pages.
+- When enabled, run repository Knowledge generation and updates only through `npx lee-spec-kit knowledge sync <featureRef> --json`. The read-only `openwiki visualize ./openwiki` command may be invoked directly to inspect generated output, but do not hand-edit generated pages.
 
 ## Optional UI/UX Design Policy
 

package/templates/en/common/agents/custom.md

@@ -2,7 +2,8 @@
 
 > ⚠️ This document contains **user-defined rules**.
 > It is NOT affected by `npx lee-spec-kit update`.
-> **Rules in this document take precedence over all other agent rules.**
+> These rules may tailor project-specific conventions, but they cannot bypass
+> safety requirements or lee-spec-kit workflow, approval, review, and commit gates.
 
 ---
 
@@ -14,7 +15,7 @@
 
 ## Additional Language/Code Rules
 
-(Override default rules or add additional rules here)
+(Add project-specific language or code rules here)
 
 ---
 

package/templates/en/common/agents/skills/create-pr.md

@@ -19,6 +19,8 @@ Execution-state SSOT is the feature-local `pr.md`.
 
 The Pre-PR subagent must always run this minimum baseline. Do not depend on a named review skill.
 
+Review Curated Documentation Impact evidence, including NONE. For each discovered discrepancy, verify a completed correction or a real follow-up task/Feature/issue with document paths, evidence, the unresolved question, and the deferral reason. A residual-risk note alone is not follow-up tracking. Report missing disposition as a finding; do not infer product intent from code or generated Knowledge. Existing review-round and approval policies still apply.
+
 When `workflow-stage --json` returns `nextAction.executor: subagent`, delegate the review to a fresh, read-only subagent. `model: inherit` means inheriting the current model; any other value is used as the subagent model override. If that model is unavailable, follow `onUnavailable` (`inherit` or `error`).
 
 1. Review alignment with `spec.md` / `plan.md` / `tasks.md` and confirm implementation still matches the original goal.

package/templates/en/common/agents/skills/execute-task.md

@@ -34,6 +34,8 @@ Use the active feature folder as the execution SSOT.
 
 ## 3. Keep docs in sync
 
+Do not close a discovered documentation discrepancy with a decisions.md note alone. For an unambiguous factual error within approved scope, declare UPDATE/ADD and link a task Docs target. If product intent or scope expansion needs confirmation, record the conflicting document paths and evidence, the question to resolve, the deferral reason, and a real follow-up task/Feature/issue reference. Never invent identifiers or approvals. If creating the tracking item needs approval, do not report resolution before user confirmation. Explain in NONE evidence whether no known discrepancy remains or a remaining discrepancy is tracked by that follow-up. Never delete unimplemented PRD requirements merely to match code or OpenWiki.
+
 - `spec.md`: update when user-visible scope or acceptance criteria change
 - `plan.md`: update when architecture, file structure, or test strategy changes
 - `decisions.md`: record non-obvious decisions, trade-offs, compatibility behavior, and user-requested behavior changes

package/templates/en/common/features/README.md

@@ -57,9 +57,9 @@ npx lee-spec-kit workflow-stage <feature-ref> --json
 
 Use the returned `stage`, `nextAction`, and `implementationAllowed` values as the current workflow state.
 
-Before Plan review or approval, complete `Curated Documentation Impact`. Explicit `NONE` values prove the surface was reviewed; every `UPDATE` or `ADD` target must appear under `Docs` in at least one task.
+Before Plan review or approval, complete Schema 2 `Curated Documentation Impact`. Assess all four core surfaces, and use typed `Additional Curated Impacts` only for applicable project-specific surfaces; an explicit additional `NONE` proves that no extra category applies. Every `UPDATE` or `ADD` target must appear under `Docs` in at least one task and in the committed Feature diff. Existing projects require one manual baseline reconciliation before per-Feature checks can keep the curated layer current.
 
-When `experimental.openwiki=true`, all completed task checkpoints advance through required `knowledge_setup`, `knowledge_sync`, and `knowledge_commit` stages before Feature review. The Feature reviewer receives `openwiki/index.md`, the verified receipt, and every Plan-declared curated target; SDD and curated project docs remain authoritative. The Knowledge surface includes a final lee-spec-kit protection block in `.openwikiignore`.
+When `experimental.openwiki=true`, all completed task checkpoints advance through required `knowledge_setup`, `knowledge_sync`, and `knowledge_commit` stages before Feature review. The Feature reviewer receives `openwiki/index.md`, the verified receipt, and every Plan-declared curated target; use the claim-specific authority matrix in `docs/README.md` rather than treating generated Knowledge as authoritative. The Knowledge surface includes a final lee-spec-kit protection block in `.openwikiignore`.
 
 With Plan review enabled, planning follows `plan Review → fresh read-only Plan review → plan approval`. The review is bound to the returned `specHash` and `planHash`; changing either document's content invalidates the prior evidence. The reviewer checks the Verification Contract and test decisions without editing docs.
 

package/templates/en/common/features/feature-base/decisions.md

@@ -12,6 +12,7 @@ If unmanaged docs artifacts exist outside the canonical docs surface (for exampl
 Recording principles:
 
 - Prefer `npx lee-spec-kit decision add <feature-ref> --title "..." --context "..." --decision "..." --rationale "..." --evidence "..."` when creating a new ADR.
+- Append manual entries after the last ADR in D001 → D002 order, never before the document guidance, and preserve existing IDs. Update the same ADR's Trace/Evidence for reruns and verification results; create a new ADR only for a new choice or scope change.
 - Every ADR must capture both **Decision (what was chosen)** and **Trace (how it was evaluated and validated)**.
 - Use fixed timing checkpoints:
   - Task start (`[TODO] -> [DOING]`): add 1-3 lines for `Context/Constraints` and `Trace (initial hypothesis)`

package/templates/en/common/features/feature-base/plan.md

@@ -51,8 +51,11 @@ src/
 
 ## Curated Documentation Impact
 
+Do not close a discovered documentation discrepancy with a decisions.md note alone. For an unambiguous factual error within approved scope, declare UPDATE/ADD and link a task Docs target. If product intent or scope expansion needs confirmation, record the conflicting document paths and evidence, the question to resolve, the deferral reason, and a real follow-up task/Feature/issue reference. Never invent identifiers or approvals. If creating the tracking item needs approval, do not report resolution before user confirmation. Explain in NONE evidence whether no known discrepancy remains or a remaining discrepancy is tracked by that follow-up. Never delete unimplemented PRD requirements merely to match code or OpenWiki.
+
 > Complete this assessment even when every decision is `NONE`. `NONE` means the surface was reviewed and no human-owned project document needs to change. Generated OpenWiki synchronization is evaluated separately.
 
+- **Schema**: 2
 - **Assessment**: Pending
   - Values: Pending | Complete
 - **Product requirements**: -
@@ -70,6 +73,24 @@ src/
 
 ---
 
+## Additional Curated Impacts
+
+> Assess conditional project-wide documents such as constitution/custom policy, design systems, API/data contracts, security, release, and observability. When none apply, record `Decision: NONE` and leave the table empty.
+
+- **Assessment**: Pending
+- **Decision**: -
+  - Values: NONE | DECLARED
+
+| Kind | Decision | Target | Reason |
+| ---- | -------- | ------ | ------ |
+| -    | -        | -      | -      |
+
+Allowed kinds: `engineering-agent-policy`, `design-system-ux`, `api-data-contract`, `security-privacy`, `release-deployment`, `observability`, `other-curated`
+
+Each `DECLARED` row uses `UPDATE` or `ADD` and a `docs:<path>` or `project:<path>` target. Link every target from a task `Docs` list.
+
+---
+
 ## Verification Contract
 
 ### Change Classification
@@ -87,9 +108,9 @@ src/
 
 ### Test Decisions
 
-| Contract / Requirement | Decision | Test Level | Realistic Regression Protected | Independent Oracle |
-| ---------------------- | -------- | ---------- | ------------------------------ | ------------------ |
-| (AC/FR reference)      | NONE \| UPDATE \| ADD | Unit \| Integration \| E2E \| Non-test | (failure this prevents) | (spec/released behavior/external reference) |
+| Contract / Requirement | Decision              | Test Level                             | Realistic Regression Protected | Independent Oracle                          |
+| ---------------------- | --------------------- | -------------------------------------- | ------------------------------ | ------------------------------------------- |
+| (AC/FR reference)      | NONE \| UPDATE \| ADD | Unit \| Integration \| E2E \| Non-test | (failure this prevents)        | (spec/released behavior/external reference) |
 
 ### Excluded Tests
 

package/templates/ko/common/README.md

@@ -56,12 +56,18 @@ npx lee-spec-kit docs get agents --json
 
 ### Knowledge Architecture와 권한
 
-1. Feature SDD(`spec.md`, `plan.md`, `tasks.md`, `decisions.md`)는 요구사항, 범위, 결정, 인수 조건의 규범입니다.
-2. 사람이 관리하는 PRD, 아키텍처, 온보딩, 운영 문서는 프로젝트 전체의 curated 현재 상태입니다.
-3. `openwiki/`는 파생된 온보딩·코드 탐색 계층입니다. 그 내용은 tracked 소스, 테스트, 스키마, curated 문서로 다시 검증합니다.
+| 주장 유형                                        | 기준                                                                     |
+| ------------------------------------------------ | ------------------------------------------------------------------------ |
+| 제품 의도와 장기 요구사항                        | PRD. 활성 Feature는 이를 연결·구체화하며 요구사항 변경은 PRD에 다시 반영 |
+| 활성 변경의 범위·상태·설계 결정·태스크·인수 조건 | 활성 Feature SDD(`spec.md`, `plan.md`, `tasks.md`, `decisions.md`)       |
+| 프로젝트 전체 설명과 정책                        | 사람이 관리하는 아키텍처·온보딩·운영·디자인·에이전트 정책 문서           |
+| 실행 가능한 런타임 사실                          | tracked 코드·스키마·마이그레이션·설정. 테스트는 검증 증거                |
+| 온보딩과 코드 탐색                               | 위 기준으로 검증하는 파생 `openwiki/` Knowledge                          |
 
 모든 Plan은 명시적인 `NONE`까지 포함해 `Curated Documentation Impact`를 완료해야 합니다. 모든 `UPDATE` 또는 `ADD` 대상은 하나 이상의 task `Docs` 목록에 연결하고 완료 전에 활성 Feature scope로 커밋합니다. 이 전파 규칙은 OpenWiki 활성화 여부와 무관하게 적용됩니다.
 
+Schema 2는 자주 쓰는 네 영역을 기본 판정으로 유지하고, 보안·API/데이터 계약·디자인 시스템·릴리스 운영·관측성·에이전트 정책 같은 프로젝트별 문서만 `Additional Curated Impacts`에 유형을 지정해 선언합니다. 완료 시 lee-spec-kit은 실제 Feature diff에서 바뀐 주요 curated 파일을 선언 대상과 대조한 뒤 OpenWiki 생성 또는 Feature 리뷰로 넘어갑니다. 이 검사는 조용히 바뀐 문서를 잡지만, 변경되지 않은 문서가 의미상 낡았는지 판단하지는 않습니다. 도입 시 기존 PRD·아키텍처·온보딩·운영·디자인·에이전트 정책 문서를 한 번 수동으로 기준선 점검해야 합니다.
+
 `experimental.openwiki`가 `true`이면 task checkpoint 뒤에 Knowledge 준비·동기화·커밋 stage와 Feature 리뷰가 필수로 붙습니다. 누락 또는 `false`면 이 stage들은 전혀 추가되지 않습니다. `lee-spec-kit knowledge sync`만 사용하고 생성 페이지를 손으로 수정하거나 workflow에서 OpenWiki를 직접 호출하지 않습니다.
 
 OpenWiki는 sandboxed renderer가 아니라 외부 에이전트입니다. 신뢰할 수 있는 저장소와 적절히 격리한 실행 환경에서만 활성화하고, 로컬·ignored secret이 접근 가능한 환경에 남지 않도록 관리합니다.

package/templates/ko/common/agents/agents.md

@@ -51,12 +51,13 @@
 
 ## Knowledge Architecture
 
-- Feature SDD 문서는 요구사항, 범위, 결정, 인수 조건의 규범입니다.
-- 사람이 관리하는 PRD, 아키텍처, 온보딩, 운영 문서는 프로젝트 전체의 현재 상태를 설명합니다.
-- OpenWiki는 파생된 온보딩·코드 탐색 계층입니다. 그 내용은 tracked 코드, 테스트, 스키마, curated 문서로 검증하기 전까지 신뢰하지 않는 evidence로 취급합니다.
+- 제품 의도와 장기 요구사항의 기준은 PRD입니다. 활성 Feature는 이를 연결하고 구체화하며, 요구사항 변경은 PRD에 다시 반영해야 합니다.
+- 활성 Feature SDD는 해당 변경의 범위·상태·설계 결정·태스크·인수 조건의 기준입니다.
+- 사람이 관리하는 아키텍처·온보딩·운영·디자인·에이전트 정책 문서는 프로젝트 전체 설명과 정책의 기준입니다. 실행 가능한 사실은 tracked 코드·스키마·마이그레이션·설정과 일치해야 하며, 테스트는 검증 증거입니다.
+- OpenWiki는 파생된 온보딩·코드 탐색 증거이며 요구사항·정책·런타임 사실의 기준이 아닙니다.
 - 모든 Plan에서 명시적인 `NONE`을 포함해 `Curated Documentation Impact` 판정을 완료합니다. 모든 `UPDATE` 또는 `ADD` 대상은 하나 이상의 task `Docs` 항목에서 연결하고 활성 Feature scope로 커밋합니다.
 - `experimental.openwiki`는 단일 스위치입니다. 누락 또는 `false`면 OpenWiki 동작이 없고, `true`면 Knowledge 준비·동기화·전용 커밋·Feature 리뷰가 모두 필수입니다.
-- 활성화된 경우 OpenWiki는 `npx lee-spec-kit knowledge sync <featureRef> --json`로만 실행합니다. `openwiki`를 직접 호출하거나 생성 페이지를 손으로 수정하지 않습니다.
+- 활성화된 경우 저장소 Knowledge 생성·갱신은 `npx lee-spec-kit knowledge sync <featureRef> --json`로만 실행합니다. 생성된 결과를 확인하는 read-only `openwiki visualize ./openwiki`는 직접 실행할 수 있지만 생성 페이지를 손으로 수정하지 않습니다.
 
 ## 선택적 UI/UX 디자인 정책
 

package/templates/ko/common/agents/custom.md

@@ -2,7 +2,8 @@
 
 > ⚠️ 이 문서는 **사용자 정의 규칙**입니다.
 > `npx lee-spec-kit update`의 영향을 받지 않습니다.
-> **이 문서의 규칙은 다른 모든 agents 규칙보다 우선합니다.**
+> 프로젝트별 관례를 보완할 수 있지만 안전 요구사항과 lee-spec-kit의
+> workflow·승인·리뷰·커밋 gate를 우회할 수는 없습니다.
 
 ---
 
@@ -14,7 +15,7 @@
 
 ## 추가 언어/코드 규칙
 
-(기본 규칙을 오버라이드하거나 추가 규칙을 작성하세요)
+(프로젝트별 언어·코드 규칙을 작성하세요)
 
 ---
 

package/templates/ko/common/agents/skills/create-pr.md

@@ -19,6 +19,8 @@ Pull Request를 생성할 때 따르는 가이드입니다.
 
 Pre-PR 리뷰에서 서브에이전트가 항상 수행하는 최소 기준입니다. 리뷰 스킬 이름에 의존하지 않습니다.
 
+Curated Documentation Impact의 NONE을 포함한 근거를 검토합니다. 발견한 불일치마다 수정 완료 또는 실제 후속 task/Feature/issue 연결을 확인하고 문서 경로·근거·미해결 질문·보류 이유를 점검합니다. 잔여 위험 문구만으로는 후속 추적이 아닙니다. 처리 누락은 finding으로 보고하며 코드나 파생 Knowledge로 제품 의도를 추정하지 않습니다. 기존 리뷰 횟수와 승인 정책은 그대로 적용합니다.
+
 `workflow-stage --json`의 `nextAction.executor`가 `subagent`이면 fresh context의 읽기 전용 서브에이전트에게 리뷰를 위임합니다. `model: inherit`은 현재 모델을 상속한다는 뜻이며, 그 외 값은 서브에이전트 생성 시 모델 override로 사용합니다. 지정 모델을 사용할 수 없으면 `onUnavailable` 정책(`inherit` 또는 `error`)을 따릅니다.
 
 1. `spec.md` / `plan.md` / `tasks.md` 기준으로 변경 범위 정합성을 확인하고, 구현이 원래 목적에 맞는지 점검합니다.

package/templates/ko/common/agents/skills/execute-task.md

@@ -34,6 +34,8 @@
 
 ## 3. 문서 동기화
 
+발견한 문서 불일치는 `decisions.md`에만 남기고 종료하지 않습니다. 현재 사실의 명백한 오류가 승인 범위 안에 있으면 `UPDATE`/`ADD`와 task `Docs`로 연결합니다. 제품 의도 확인이나 범위 확장이 필요하면 충돌한 문서 경로·근거, 확인할 질문, 보류 이유와 실제 후속 task/Feature/issue 참조를 기록합니다. 없는 번호나 승인을 만들지 않습니다. 추적 항목 생성에 승인이 필요하면 사용자 확인 전 해결된 것으로 기록하지 않습니다. `NONE`의 근거에는 알려진 불일치가 없거나, 남은 불일치가 해당 후속 항목으로 추적되고 있음을 설명합니다. 코드나 OpenWiki에 맞추기 위해 미구현 PRD 요구를 삭제하지 않습니다.
+
 - `spec.md`: 사용자-visible scope 또는 acceptance criteria가 바뀌면 갱신합니다
 - `plan.md`: 아키텍처, 파일 구조, 테스트 전략이 바뀌면 갱신합니다
 - `decisions.md`: 비자명한 결정, 트레이드오프, 호환성 처리, 사용자 요청으로 바뀐 동작을 기록합니다

package/templates/ko/common/features/README.md

@@ -57,9 +57,9 @@ npx lee-spec-kit workflow-stage <feature-ref> --json
 
 반환되는 `stage`, `nextAction`, `implementationAllowed` 값을 현재 워크플로우 상태로 사용하세요.
 
-Plan 검수 또는 승인 전에 `Curated Documentation Impact`를 완료합니다. 명시적인 `NONE`은 해당 영역을 검토했다는 증거이며, 모든 `UPDATE` 또는 `ADD` 대상은 하나 이상의 task `Docs` 아래에 있어야 합니다.
+Plan 검수 또는 승인 전에 Schema 2 `Curated Documentation Impact`를 완료합니다. 네 기본 영역을 모두 판정하고, 프로젝트별 추가 영역이 적용될 때만 typed `Additional Curated Impacts`를 사용합니다. 추가 영역의 명시적인 `NONE`은 해당 범주가 없음을 검토했다는 증거입니다. 모든 `UPDATE` 또는 `ADD` 대상은 하나 이상의 task `Docs`와 커밋된 Feature diff에 함께 있어야 합니다. 기존 프로젝트는 Feature별 검사를 신뢰하기 전에 한 번의 수동 baseline reconciliation을 수행합니다.
 
-`experimental.openwiki=true`이면 완료된 모든 task checkpoint 뒤에 필수 `knowledge_setup`, `knowledge_sync`, `knowledge_commit` stage를 거쳐 Feature 리뷰로 이동합니다. Feature reviewer는 `openwiki/index.md`, 검증 receipt, Plan이 선언한 모든 curated target을 받으며, SDD와 curated 프로젝트 문서가 계속 상위 권한을 가집니다. Knowledge surface에는 `.openwikiignore`의 마지막 lee-spec-kit 보호 블록도 포함됩니다.
+`experimental.openwiki=true`이면 완료된 모든 task checkpoint 뒤에 필수 `knowledge_setup`, `knowledge_sync`, `knowledge_commit` stage를 거쳐 Feature 리뷰로 이동합니다. Feature reviewer는 `openwiki/index.md`, 검증 receipt, Plan이 선언한 모든 curated target을 받으며, 생성된 Knowledge를 기준으로 삼지 않고 `docs/README.md`의 주장 유형별 권한 표를 따릅니다. Knowledge surface에는 `.openwikiignore`의 마지막 lee-spec-kit 보호 블록도 포함됩니다.
 
 Plan 검수가 활성화되면 계획 단계는 `plan Review → fresh 읽기 전용 Plan 검수 → plan 승인` 순서로 진행됩니다. 검수는 반환된 `specHash`와 `planHash`에 묶이며 두 문서 중 하나의 내용이 바뀌면 기존 evidence가 무효입니다. reviewer는 문서를 수정하지 않고 Verification Contract와 테스트 결정을 점검합니다.
 

package/templates/ko/common/features/feature-base/decisions.md

@@ -12,6 +12,7 @@ canonical docs surface 밖의 unmanaged docs 산출물(예: `docs/plans/*`, `doc
 기록 원칙:
 
 - 새 ADR 생성에는 `npx lee-spec-kit decision add <feature-ref> --title "..." --context "..." --decision "..." --rationale "..." --evidence "..."` 사용을 우선하세요.
+- 수동 작성도 마지막 ADR 뒤에 추가해 D001 → D002 순서를 유지하세요. 문서 안내문 앞에 삽입하거나 기존 ID를 재번호화하지 마세요. 같은 결정의 재실행·검증 결과는 해당 ADR의 Trace/Evidence를 갱신하고, 새 선택이나 범위 변경일 때만 새 ADR을 만드세요.
 - 모든 ADR은 **Decision(무엇을 선택했는가)** + **Trace(어떻게 고민했고 무엇을 확인했는가)** 를 함께 남깁니다.
 - 작성 타이밍을 고정합니다.
   - 태스크 시작(`[TODO] -> [DOING]`): `Context/Constraints`와 `Trace(초기 가설)`를 1~3줄로 먼저 기록