lee-spec-kit 0.9.11 → 0.9.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lee-spec-kit",
-  "version": "0.9.11",
+  "version": "0.9.14",
   "description": "Document-centered harness engineering toolkit for AI agent development",
   "type": "module",
   "bin": {
@@ -11,8 +11,22 @@
   "files": [
     "dist",
     "templates",
-    "assets"
+    "assets",
+    "resources",
+    "THIRD_PARTY_NOTICES.md"
   ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "lint:test": "eslint tests",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc -p tsconfig.tests.json --noEmit",
+    "test": "pnpm build && vitest run",
+    "test:race": "pnpm build && vitest run tests/race.test.mjs",
+    "format": "prettier --write .",
+    "prepublishOnly": "pnpm build"
+  },
   "keywords": [
     "docs",
     "template",
@@ -26,7 +40,7 @@
     "workflow"
   ],
   "author": "Lee Yoonsu",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "engines": {
     "node": ">=18.0.0"
   },
@@ -54,15 +68,5 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "lint": "eslint src",
-    "lint:test": "eslint tests",
-    "typecheck": "tsc --noEmit",
-    "typecheck:test": "tsc -p tsconfig.tests.json --noEmit",
-    "test": "pnpm build && vitest run",
-    "test:race": "pnpm build && vitest run tests/race.test.mjs",
-    "format": "prettier --write ."
-  }
-}
+  "packageManager": "pnpm@10.7.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

@@ -66,9 +66,9 @@ Keep product roadmaps in `prd/`, but manage implementation sequencing and work p
 
 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.
+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 Feature review; OpenWiki generation follows integration separately. 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.
+When `experimental.openwiki` is true, local workflows publish an isolated, revision-bound Knowledge artifact after verified integration and before cleanup. GitHub uses the base-branch push CI scaffolded by `knowledge ci`. Feature commits and review do not contain generated Wiki. Use the returned `knowledge publish` command and inspect failures with `knowledge status`.
 
 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.
 
@@ -156,7 +156,7 @@ The OpenWiki experiment is controlled separately with the single `--openwiki tru
 - `docsRepo` ("embedded" | "standalone"): How docs are managed
 - `pushDocs` (boolean, optional): Only written when `docsRepo: "standalone"` (whether to push to remote)
 - `docsRemote` (string, optional): Only written when `pushDocs: true` (remote repo URL)
-- `experimental.openwiki` (boolean): one switch for the complete required OpenWiki Knowledge flow; missing/`false` disables it, and `true` requires Node.js 22+, OpenWiki `>=0.5.0 <1.0.0`, Knowledge sync/receipt/commit, and Feature review
+- `experimental.openwiki` (boolean): enables post-integration Knowledge artifacts; requires Node.js 22+ and OpenWiki `>=0.5.0 <0.6.0`. No generated Knowledge commit or forced Feature review.
 - `workflow.agentExecution.task` (object): task implementation delegation settings
   - `enabled`: delegates each `task_execute` action to a subagent; new projects default to `true`, while projects created before this setting existed keep it disabled until explicitly enabled
   - `type`: currently only `"subagent"` is supported
@@ -296,3 +296,30 @@ New projects delegate task implementation and enable Plan review by default. Exi
   }
 }
 ```
+
+
+### Feature check configuration (0.9.14)
+
+`workflow.featureChecks` is the executable project baseline for local completion.
+An empty list requires configuration; it does not mean that tests passed.
+Use `npx lee-spec-kit config --checks-detect` to print read-only Node script suggestions,
+then save a reviewed JSON array with `config --checks-file <path>`.
+Use `--project-root <path>` for discovery when the project root is ambiguous.
+Include build when the project produces build artifacts. If a selected test already
+runs build, document that coverage in the Plan and omit the duplicate command.
+Discovery does not infer nested script coverage or execute scripts.
+For projects without executable checks, use `config --checks-skip-reason <reason>`.
+Use `--component <name>` with the configuration commands for component overrides
+(`workflow.featureChecksByComponent`); otherwise the common baseline applies.
+
+Legacy `postMergeChecks` are read as Feature checks only when `featureChecks` is
+absent. `update` migrates that list without adding commands or overwriting an
+existing Feature list. Invalid entries remain visible and cause a validation error.
+Changing checks invalidates verification for pending integration. Completed,
+cleaned Features retain their historical completion state.
+
+The Plan's Verification Contract must reference the effective baseline and list
+Feature-specific extra checks in the executable configuration before verification.
+Record manual/UI evidence separately. Update the configuration before final review
+and verification, not after verification. Local base synchronization happens before
+checks; this does not fetch remote branches.

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

@@ -56,8 +56,8 @@ This document defines workflow policy, not a custom runtime loop.
 - 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 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.
+- `experimental.openwiki=true` publishes Knowledge after integration: local workflows run the returned `knowledge publish` action after verified merge and before cleanup; GitHub workflows use the post-push CI created by `knowledge ci`. Missing or false disables this lifecycle.
+- Generate in an isolated worktree and publish revision-bound artifacts outside the source branch. Do not add generated Wiki or receipts to Feature commits or Feature review required documents. Keep curated PRD/architecture updates in the Feature.
 
 ## Optional UI/UX Design Policy
 
@@ -81,12 +81,12 @@ This document defines workflow policy, not a custom runtime loop.
 - Do not interrupt, replace, or abandon a running subagent solely because it has been quiet or has not changed files. Stop it only after an explicit user request, a terminal failure/cancellation, or an unrecoverable runtime status.
 - `workflow.agentReview.maxRounds` is the maximum number of fresh reviews for each Plan/task/Feature gate. A `changes_requested` decision on the final allowed review is remediated once, but the changed target is not reviewed again; preserve remaining findings and the post-review target change as residual risks and automatically complete the gate without asking for a user review-approval token. For example, `maxRounds=1` means review round 1, remediate once, then continue with no round 2. A `blocked` decision never auto-completes.
 - Treat spec/plan/tasks approval, issue creation, and branch creation as hard gates before implementation.
-- Follow `knowledge_setup`, `knowledge_sync`, and `knowledge_commit` exactly when returned. Commit only the verified Knowledge surface with the exact returned subject before Feature review.
+- Follow the post-integration `knowledge_sync` action (`knowledge publish`). Failures leave the verified merge and last good publication intact; inspect `knowledge status` and retry. `knowledge sync` is a legacy in-place tool, not the Feature workflow.
 - In standalone mode, do not hand-write `git worktree add`; run the exact `nextAction.command` from `workflow-stage` so the managed workspace path, stale directory cleanup, and `.env`/`.env.*` copy step stay consistent.
 - In local mode, do not stop after implementation approval. Follow the exact `local verify`, `local merge`, and `local cleanup` commands returned by `workflow-stage` until verified integration and cleanup produce `done`. A `feature_remediation` stage explicitly permits fixes in the Feature worktree.
 - In a `local-ff` or `local-squash` workflow, keep implementation approval and local merge approval distinct when `local_merge` is required: the first accepts the implementation, and the second authorizes the configured integration strategy, post-merge checks, and local cleanup.
 - Keep docs synced with code changes in the same turn whenever behavior or scope changes.
-- Use `npx lee-spec-kit commit-audit --json` before `git commit`; Feature-scoped commits use `#123` when an Issue is linked and the stable Feature ID such as `F027` for issue-less local workflows.
+- Use `npx lee-spec-kit commit-audit --json` before `git commit`; Feature-scoped commits use `#123` when an Issue is linked and the stable Feature ID such as `K7M2Q9RX4DAB` for issue-less local workflows.
 - Use `npx lee-spec-kit workflow-audit --json` as the default end-of-turn docs sync check.
 
 ## Approval Rules

package/templates/en/common/agents/git-workflow.md

@@ -65,11 +65,11 @@ Examples:
 ```text
 feat(#123): implement user auth
 docs(#123): clarify auth spec
-feat(F027): implement notification settings
-docs(F027): update notification docs
+feat(K7M2Q9RX4DAB): implement notification settings
+docs(K7M2Q9RX4DAB): update notification docs
 ```
 
-For local Features, the scope is the stable Feature ID (`F027`), not the full folder ref (`F027-notification-settings`). Feature-scoped commits without a scope, such as `docs: F027 ...`, are not canonical.
+For local Features, the scope is the stable Feature ID (`K7M2Q9RX4DAB`), not the full folder ref (`K7M2Q9RX4DAB-notification-settings`). Feature-scoped commits without a scope, such as `docs: K7M2Q9RX4DAB ...`, are not canonical.
 
 ### Type List
 
@@ -110,14 +110,7 @@ Run the returned `nextAction.command` instead of hand-writing the worktree path.
 that are no longer registered Git worktrees, and copies existing `.env`/`.env.*` files
 from the project root into the new worktree when the target file is absent.
 
-```bash
-# Embedded fallback only: create dedicated worktree + branch
-mkdir -p .worktrees
-git worktree add -b feat/{issue-number}-{feature-name} .worktrees/feat-{issue-number}-{feature-name}
-
-# If branch already exists, attach worktree only
-git worktree add .worktrees/feat-{issue-number}-{feature-name} feat/{issue-number}-{feature-name}
-```
+For new embedded Features, follow `workspace_checkpoint` before branch creation. It commits only that Feature's planning docs. Then use the returned worktree command and continue from its workingDirectory. Do not manually create a worktree from a HEAD that lacks the Feature docs.
 
 > Continue implementation from the worktree path returned by `workflow-stage`.
 
@@ -132,17 +125,17 @@ git worktree add .worktrees/feat-{issue-number}-{feature-name} feat/{issue-numbe
 
 #### Standalone Mode Commit Guide
 
-Use the scope selected by the workflow: `#123` when an Issue is linked, otherwise the local Feature ID such as `F027`.
+Use the scope selected by the workflow: `#123` when an Issue is linked, otherwise the local Feature ID such as `K7M2Q9RX4DAB`.
 
 1. **Project Commit** (If code changed)
 
    ```bash
-   git commit -m "feat(F027): implement feature"
+   git commit -m "feat(K7M2Q9RX4DAB): implement feature"
    ```
 
 2. **Docs Commit** (If docs changed - **Run in Docs Repo**)
    ```bash
-   git commit -m "docs(F027): update feature docs"
+   git commit -m "docs(K7M2Q9RX4DAB): update feature docs"
    ```
 
 > 💡 **Core Rule**: At task completion, **all changed repositories** must be committed.
@@ -179,3 +172,11 @@ Use the scope selected by the workflow: `#123` when an Issue is linked, otherwis
 
 - [ ] Auto-delete head branches
 - [ ] Squash merging only
+
+## Feature isolation and integration
+
+New GitHub Feature IDs come from Issues selected before SDD planning; new local IDs are 12-character random values. Existing F-number documents remain compatible. One Feature has one owner and one active task; different Features can proceed independently.
+
+New standalone Features keep the primary docs checkout on its base branch and use `workspace prepare` for their docs worktree. Commit seed docs first and work from the returned docsDirectory. Project and docs integration are separate. In local mode, verify code integration, merge docs, publish OpenWiki when enabled, then clean up. GitHub publication runs independently on code base-branch pushes. The docs receipt is an empty Git commit and survives a docs clone. Use `workspace sync-docs` when the base advances and revalidate conflicts before integration. Failed integration never implies completion.
+
+Use task claim/status/transition/release for explicit task IDs, with the current tasks hash and session token. Legacy task lines without IDs retain document transitions. Run feature-audit in CI; review sharedDocumentationWarnings for shared curated targets. PR merge retries do not automatically rebase or force-push.

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

@@ -8,10 +8,7 @@ This guide defines how to start or continue a feature in the Codex-native lee-sp
 
 1. Run `npx lee-spec-kit detect --json`.
 2. If detected, read `npx lee-spec-kit docs get agents --json` and any unread follow-up docs.
-3. If the feature folder does not exist yet:
-   - preserve an explicit Idea ref only when the user actually named one (`I001`, `I001-slug`, or `docs/ideas/...`)
-   - create the feature with `npx lee-spec-kit feature <name> --idea <ref>` only for that explicit ref
-   - otherwise create it with `npx lee-spec-kit feature <name> -d "<description>"`
+3. If the Feature folder does not exist, use `feature <name> --issue <number>` in GitHub mode. Create an Issue first only after sharing its title/body and receiving authorization (`--create-issue --desc "<summary>" --confirm OK`). In local mode, use `feature <name> -d "<description>"`; a random ID is generated. Add `--idea <ref>` only when the user explicitly named that Idea. Never allocate a new F-number.
 4. Resolve the active feature and read its docs: `spec.md`, `plan.md`, `tasks.md`, `decisions.md`.
 5. Run `npx lee-spec-kit workflow-stage <feature-ref> --json` before taking the next workflow action.
 
@@ -36,3 +33,11 @@ This guide defines how to start or continue a feature in the Codex-native lee-sp
 1. Do not invent issue/PR numbers or status transitions.
 2. Do not skip required doc updates when scope, behavior, or evidence changed.
 3. Do not treat unmanaged docs artifacts as the active workflow SSOT until they are normalized into the feature folder or allowlisted.
+
+## Single-owner collaboration
+
+- Select the Feature by ID or an unambiguous branch; never choose by recency or numeric order.
+- New Features use code worktrees. For standalone docs, commit the seed and follow `workspace prepare`; work from the returned docsDirectory. Follow returned docs integration/cleanup steps after code integration.
+- Claim one owner session with `task claim`; use `task status` or workflow-stage's tasksHash and `task transition --session <token> --expected-hash <hash>`. Release the session at handoff. Never run two DOING/REVIEW tasks in one Feature.
+- Run `feature-audit --enforce --json` alongside workflow-audit; use `--base-ref <fetched-base>` in CI to check immutable identity. Resolve sharedDocumentationWarnings against the latest base.
+- If the base advances, sync it explicitly in the Feature worktree and reverify/review. Never automatically rebase and force-push during merge retries.

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

@@ -1,11 +1,13 @@
+> New Features: create/select the GitHub Issue before generating Feature docs. Use `npx lee-spec-kit feature <slug> --issue <number> --owner <email>`, or share the title/body and use `--create-issue --desc <body> --confirm OK`. The legacy `github issue F001` flow below remains for existing F-number Features. Issue creation is intake, not implementation approval.
+
 # GitHub Issue Creation Process
 
 Guide for creating GitHub Issues.
-Execution-state SSOT is the feature-local `issue.md`.
+For the legacy flow below, execution-state SSOT is the feature-local `issue.md`. New Features use Issue intake before SDD planning; the following completed-SDD prerequisites do not apply to intake.
 
 ---
 
-## Prerequisites
+## Legacy F-number workflow prerequisites
 
 - [ ] `spec.md` completed
 - [ ] `plan.md` completed
@@ -15,7 +17,7 @@ Execution-state SSOT is the feature-local `issue.md`.
 
 ---
 
-## Steps
+## Legacy steps
 
 ### 1. Prepare `issue.md` Draft
 

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
@@ -58,3 +60,7 @@ Use the active feature folder as the execution SSOT.
 2. Do not rewrite `[DONE]` tasks.
 3. Do not treat unmanaged docs artifacts as active workflow state until they are normalized or allowlisted.
 4. Do not start implementation while the workflow is still blocked on issue creation, branch creation, or any earlier stage gate.
+
+## Session and state commands
+
+For tasks with explicit IDs, the main agent claims the Feature with `task claim <id> --json`, reads `task status <id> --json`, and calls `task transition <id> <task-id> --from <state> --to <state> --session <token> --expected-hash <hash> --json`. Use the task selected by workflow-stage. Update acceptance/checklist/review evidence first, then read a fresh hash for the transition. Stale hashes, other owners, and competing sessions block mutations. Release with `task release <id> --session <token>` at handoff. These commands do not add approval boundaries. Legacy lines without explicit task IDs continue using document edits under the existing workflow gates.

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

@@ -59,7 +59,7 @@ Use the returned `stage`, `nextAction`, and `implementationAllowed` values as th
 
 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; 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 `experimental.openwiki=true`, Feature review receives the Plan-declared curated targets and checks them against code and product intent. Generated Wiki and receipts are not required inputs. After verified local integration, `knowledge_sync` invokes `knowledge publish` before cleanup. GitHub publishes revision-bound artifacts through the integration-branch CI scaffolded by `knowledge ci`. Generation failure preserves the code merge and last good artifact.
 
 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,6 +51,8 @@ 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
@@ -67,7 +69,7 @@ src/
 - **Reason**: -
 - **Targets**: -
   - Use comma-separated `docs:<path>` and `project:<path>` targets when any decision is UPDATE or ADD.
-  - Every target must be linked from a task `Docs` list and committed with the active Feature scope before Knowledge sync or Feature review.
+  - Every target must be linked from a task `Docs` list and committed with the active Feature scope before Feature review.
 
 ---
 
@@ -91,6 +93,9 @@ Each `DECLARED` row uses `UPDATE` or `ADD` and a `docs:<path>` or `project:<path
 
 ## Verification Contract
 
+Reference the effective workflow.featureChecks baseline, including component overrides. Register additional automatic checks in the executable configuration. State build coverage, reasons for avoiding duplicate builds, and manual verification evidence.
+
+
 ### Change Classification
 
 - **Type**: COPY | REFACTOR | BUG_FIX | NEW_BEHAVIOR | HIGH_RISK