lee-spec-kit 0.7.11 → 0.8.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lee-spec-kit",
-  "version": "0.7.11",
-  "description": "Agent-guided development harness CLI for spec-driven projects",
+  "version": "0.8.1",
+  "description": "Document-centered harness engineering toolkit for AI agent development",
   "type": "module",
   "bin": {
     "lee-spec-kit": "./dist/index.js",

package/templates/en/common/README.md

@@ -11,23 +11,23 @@ npx lee-spec-kit onboard --strict
 # 1) Detect project
 npx lee-spec-kit detect --json
 
-# 2) If detected, read context first
-npx lee-spec-kit context --json-compact
+# 2) If detected, read the workflow policy
+npx lee-spec-kit docs get agents --json
 ```
 
 - Apply lee-spec-kit workflow only when `isLeeSpecKitProject: true`.
-- Use `context --json-compact` as the read-only state probe, then use `flow` as the default execution/resume entrypoint.
-- Determine approval waiting only from the latest `context --json-compact` / `flow --json-compact`.
-- When `approvalRequest.required=true`, keep approval open until it is resolved: briefly restate the current stage from `matchedFeature.currentSubstate*` when available, then show the exact CLI approval lines and wait for user approval (`<LABEL>` or `<LABEL> OK`) before execution.
-- For command execution, default to `npx lee-spec-kit flow <featureRef> --approve <LABEL> --execute`.
-- When `approvalRequest.required=false`, do not invent a separate label approval prompt.
+- Use workspace-scoped `AGENTS.md`, official Codex hooks, and the active feature docs as the default runtime path.
+- Resolve the active feature, then treat `spec.md`, `plan.md`, `tasks.md`, and `decisions.md` as the working SSOT.
+- Ask for approval only at documented workflow checkpoints and before remote or destructive actions.
+- Use `npx lee-spec-kit commit-audit --json` before `git commit` when staged docs paths need validation.
+- Use `npx lee-spec-kit workflow-audit --json` before stopping when code or feature docs changed.
 - If `isLeeSpecKitProject: false`, skip lee-spec-kit-specific flow and continue with normal workflow.
 
 ## New Project Start Order
 
 - Scaffold the code project first (for example Next.js/NestJS), then run `lee-spec-kit init`.
 - After that, write top-level requirements in `docs/prd/`, then continue with `idea` and `feature`.
-- Verify detection with `detect --json`, then continue with `context`.
+- Verify detection with `detect --json`, then continue through `docs get agents --json` and the active feature docs.
 - In most cases (default: embedded), the steps above are all you need.
 - Choose standalone only when docs are managed separately from the code repo. In that case, prefer running init from a parent workspace folder (for example `workspace/docs`, `workspace/project`) and set both docs/project paths together. (e.g. `npx lee-spec-kit init --docs-repo standalone --dir ./docs --project-root ./project`)
 
@@ -77,7 +77,7 @@ Recommended flow:
 - **Unmanaged docs entries**: any top-level docs entry outside the canonical surface
   - Examples: `docs/plans/`, `docs/superpowers/`, or another skill-created folder
   - Treat them as staging/reference inputs only, not the active workflow SSOT
-  - Once a feature is active, `context` may block execution with a `docs_normalize` step until these entries are normalized or explicitly allowlisted
+  - Normalize or allowlist them before commit; `commit-audit` blocks staged non-canonical docs paths
   - Normalize them into feature-local docs:
     - design/spec artifact → `spec.md`, `plan.md`, `decisions.md`
     - implementation plan artifact → `plan.md`, `tasks.md`
@@ -117,7 +117,9 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
 - `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)
-- `approval` (object, optional): Override `[CHECK required]` / `requiresUserCheck` policy in `context` output
+- `approval` (object, optional): optional approval-checkpoint metadata for repo policy and custom validators
+  - The Codex-native default path still asks at documented checkpoints and before remote/destructive actions first.
+  - Legacy runtime consumed this field directly; keep it only when you intentionally want category-based checkpoint metadata.
   - Current default:
     - `mode: "category"`
     - `default: "skip"`

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

@@ -1,107 +1,53 @@
 # Agents Guide
 
 Operating rules for AI code assistants.
-This document covers **policy only**.
+This document defines workflow policy, not a custom runtime loop.
 
 ---
 
-## 🚨 User Approval Handling (MUST)
+## Detection Gate
 
-These are the mandatory user approval rules.
+- Run `npx lee-spec-kit detect --json` first.
+- Use lee-spec-kit policy only when detection returns `status === "ok"` and `isLeeSpecKitProject === true`.
+- If detection fails or returns false, ignore lee-spec-kit-specific rules and continue normally.
 
-> ⚠️ Do not decide approval only from the action type. Workflow approval-waiting is determined by the latest `context --json-compact` / `flow --json-compact` output.
-> ✅ In approval-waiting state, replies must be in `<label>` or `<label> OK` format (e.g. `A`, `A OK`).
-> ℹ️ Under the default policy, the main workflow approval boundaries are `spec_approve` and `implementation_approve`. Project config may add more.
-> ℹ️ Some direct remote helper commands still require explicit command confirmation such as `--confirm OK`; that command-level confirm is separate from label-gated workflow approval.
+## Default Runtime
 
-If the current action is approval-waiting, share the matching details before execution:
+- Prefer Codex native execution with workspace-scoped `AGENTS.md` plus official Codex hooks.
+- If the user gives a generic request such as continuing the next feature according to the rules, interpret it through this workflow automatically.
 
-| Current action (examples) | What to share |
-| --- | --- |
-| Spec / plan / tasks review | The document or the exact section being reviewed |
-| Task completion / final checklist | Outcome and verification evidence |
-| Commit / push / merge | Commit message, included files, branch |
-| Issue creation | Before `npx lee-spec-kit github issue <featureRef> --create` |
-| PR creation | Before `npx lee-spec-kit github pr <featureRef> --create` |
-| Assignee change | Target username |
-
-Approval flow:
-1. Share details first
-2. Check whether approval is currently required via the latest `context --json-compact` (`approvalRequest.required`)
-3. If approval is required, wait for the exact CLI-provided label prompt response; if not, do not invent a separate approval prompt
-4. Execute after approval (for command execution, default to `npx lee-spec-kit flow <featureRef> --approve <LABEL> --execute`)
-
-Prohibited:
-- Proceeding without user response
+## Docs Are SSOT
 
----
-
-## 🧾 Label Response Contract (SSOT)
-
-- Treat approval-waiting as a separate state. Approval-waiting means the latest `context --json-compact` / `flow --json-compact` (fallback: `context --json` / `flow --json`) shows `approvalRequest.required=true`.
-- Do not infer approval-waiting from conversation tone, action type, or the mere presence of `actionOptions[]`.
-- Use the latest `npx lee-spec-kit context --json-compact` as the default source (fallback: `context --json` or `flow --json` when full detail is required; prefer `flow --json-compact` for default flow output).
-- When using auto results from `flow --json-compact` (or `flow --json`), treat `autoRun.resume.flowCommand` as SSOT for resume (including after context compression/reset).
-- Treat `AUTO_DELEGATED_HANDOFF` as a delegated pause, not a failure. Continue or resume the delegated run path and do not reopen the same approval label.
-- Treat `AUTO_MANUAL_REQUIRED` as an instruction-only automation boundary, not an immediate failure. Re-check `context --json-compact`, then decide stop/report by `approvalRequest.required` (`context --json` only for full-detail debugging fields).
-- Special case: if `matchedFeature.currentSubstateId === "change_request_sync"` or `matchedFeature.pendingChangeRequest` is present, treat that manual boundary as an internal docs-sync step first, not an immediate user-facing stop. Sync docs, clear the pending change field, then continue with fresh `context --json-compact` or `flow`.
-- Treat `AUTO_SELECTION_REQUIRED` as a feature-selection pause, not an execution failure. Resolve the active feature first, then continue with fresh `context --json-compact` or `flow`.
-- In approval-waiting state, if `matchedFeature.currentSubstateId` exists, prepend one brief current-stage recap derived from `matchedFeature.currentSubstateId/currentSubstateOwner/currentSubstatePhase`.
-- Then prefer `approvalRequest.userFacingLines` from `context --json-compact`. If full `--json` is used, fall back to `actionOptions[*].approvalPrompt` plus `approvalRequest.finalPrompt`. Do not add your own rewritten label summary before or between those lines.
-- Prefer `matchedFeature.currentSubstateOwner` plus `agentOrchestration.subAgentHandoff` as the delegation SSOT.
-- In non-approval state, do not append labels or `approvalRequest.finalPrompt` unless the user explicitly asked for current options.
-- If approval is still pending after answering an unrelated question, answer first, re-check `approvalRequest.required`, and if it is still `true`, re-open approval with one brief current-stage recap plus the exact CLI-provided approval lines (`approvalRequest.userFacingLines`, or `actionOptions[*].approvalPrompt` + `approvalRequest.finalPrompt` in full `--json`).
-- If user input does not contain a valid label, do not execute; request label selection again.
-- For non-delegated command options, prefer one-shot `flow --approve <LABEL> --execute`; do not split `context --approve` and `context --execute --ticket` across turns/sessions.
-- If `matchedFeature.currentSubstateOwner="subagent"` and `agentOrchestration.subAgentHandoff.required=true` with `mode="command"`, delegation is mandatory: call `spawn_agent` first. Do not execute that command directly from the main agent.
-- If that delegated command is handoff-only (`handoffOnly=true`, `advancesWorkflow=false`), treat `--execute` as handoff preparation only. Continue the delegated work immediately and do not re-approve the same label.
-- Do not delegate auto loops from `autoRun.available` alone. Delegate auto loops only when `agentOrchestration.subAgentHandoff.required=true` and `agentOrchestration.subAgentHandoff.mode="auto_run"`.
-- Prefer `agentOrchestration.subAgentHandoff` as the handoff SSOT. Pass only its minimal fields (`featureRef`, `category`, `cwd`, `cmd`) to the sub-agent.
-- For delegated runs, execute one-time verification from `subAgentHandoff.verify` (`pwd`, `git rev-parse --show-toplevel`) and cache by `verify.cacheKey`. If mismatched, stop and report; collect detailed logs only on mismatch.
-- Main-agent fallback is allowed only when sub-agent execution is unavailable (for example: tool not available, spawn failed, or sub-agent failed before command execution).
-- When fallback is used, report a one-line fallback reason to the user before running the command in the main agent.
+- Read `npx lee-spec-kit docs get agents --json` once at session start or right after context reset.
+- Read every unread `requiredDocs[*].command` from that response.
+- Resolve the active feature, then use that feature folder as the working SSOT.
+- Minimum active feature docs: `spec.md`, `plan.md`, `tasks.md`, `decisions.md`.
+- When GitHub workflow is involved, also use `issue.md` and `pr.md`.
+- After reading the active feature docs, run `npx lee-spec-kit workflow-stage <featureRef> --json` and follow only that `nextAction`.
 
-Approval-waiting output must reuse the exact CLI-provided prompt lines. A single concise current-stage recap derived from `matchedFeature.currentSubstate*` is allowed before those lines. Do not invent label-summary wrappers such as `Current status:` / `Available labels:` or paraphrase label meanings.
+## Execution Rules
 
----
-
-## 📚 Built-in Docs Read Policy (MUST)
+- lee-spec-kit owns docs structure, workflow stages, and validators.
+- Codex owns the execution loop, tool usage, and hook lifecycle.
+- Do not start implementation unless `workflow-stage --json` reports `stage === "implementation"` and `implementationAllowed === true`.
+- Treat spec/plan/tasks approval, issue creation, and branch creation as hard gates before implementation.
+- 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` when staged docs paths need validation.
+- Use `npx lee-spec-kit workflow-audit --json` as the default end-of-turn docs sync check.
 
-- Use `docs get` once per session start (or right after context compression/reset).
-- Do not re-read the same doc again in the same session.
-- From `requiredDocs[*].command`, fetch only docs not yet read in this session.
-- You may re-read only when:
-  - user explicitly asks for policy refresh
-  - policy/config changed (for example after `update`)
-  - session restarted or context was compressed/reset
+## Approval Rules
 
----
-
-## Required References
-
-- Highest-priority custom rules: `/docs/agents/custom.md`
-- Project principles: `/docs/agents/constitution.md`
-- Root guide: `npx lee-spec-kit docs get agents --json`
-- Git workflow: `npx lee-spec-kit docs get git-workflow --json`
-- Task execution: `npx lee-spec-kit docs get execute-task --json`
-- Issue procedure/doc: `npx lee-spec-kit docs get create-issue --json` → `npx lee-spec-kit docs get issue-doc --json`
-- PR procedure/doc: `npx lee-spec-kit docs get create-pr --json` → `npx lee-spec-kit docs get pr-doc --json`
-
----
-
-## Scope Split
-
-- Docs structure/path rules: use `docs/README.md` as SSOT
-- Canonical docs surface is limited to the top-level entries defined by `docs/README.md`. Treat any non-allowlisted extra `docs/*` top-level entry as unmanaged docs.
-- Unmanaged docs entries (for example `docs/plans/*`, `docs/superpowers/*`, or another skill-created docs folder) are staging/reference inputs only. When a feature is active, normalize them into feature-local docs and treat the feature folder as the final SSOT.
-- If `context` surfaces a `docs_normalize` action/category, complete that normalization step before continuing implementation or workflow actions.
-- ADR format: use feature `decisions.md` template as SSOT
-- Issue/PR execution state: use each feature's `issue.md` and `pr.md` as SSOT
+| Current action (examples) | What to share |
+| --- | --- |
+| Issue creation | Before `npx lee-spec-kit github issue <featureRef> --create` |
+| PR creation | Before `npx lee-spec-kit github pr <featureRef> --create` |
 
----
+- Ask the user for approval at documented workflow checkpoints and before remote or destructive actions.
+- If `workflow-stage --json` says `approvalRequired === true`, stop and ask the user at that checkpoint.
+- Share the exact artifact or plan before remote GitHub actions.
 
-## Language / Formatting Rules
+## Formatting Rules
 
-- Replies: English (or project language policy in `custom.md`)
-- Code/file names: English
-- Date/time: use user's local system time
+- Replies: English unless project policy overrides it
+- Code and filenames: English
+- Dates and times: use the user's local system time

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

@@ -1,61 +1,36 @@
-# Feature Implementation Process: CLI-driven
+# Feature Implementation Process: Docs-first
 
-This document defines the **only rule** for adding a new Feature.
-As an agent, do not trust your own judgment—follow the **CLI output** only.
+This guide defines how to start or continue a feature in the Codex-native lee-spec-kit path.
 
 ---
 
-## 🔄 The Loop (repeat forever)
-
-Repeat this loop until the Feature is complete (docs committed).
-
-### Step 1: Check context
-
-Run this command whenever you start work or finish a step:
-
-```bash
-npx lee-spec-kit context
-```
-
-### Step 2: Execute one option only (Next Options)
-
-Read `👉 Next Options (Atomic)`, choose exactly one option (`A/B/C`), and execute **only that option**.
-For gated actions, proceed only after the user replies in **`<label>` or `<label> OK` format** (e.g. `A`, `A OK`).
-
-- If the CLI indicates **Review**, share the document with the user and stop.
-- If the CLI asks for writing a file, write that file and follow the format.
-- If the CLI prints a command, **copy/paste and run it exactly**. (It may include repo-safe `git -C ...` commands and scopes like `project` vs `docs`.)
-- When requesting approval, present labels as `A: ...` using the exact CLI detail/cmd text. Do not paraphrase command options.
-- For approved command options, default to one-shot execution via `npx lee-spec-kit flow <slug|F001|F001-slug> --approve <LABEL> --execute` to avoid session mismatch.
-
-### Step 3: Repeat
-
-After completing the action, go back to Step 1 and run `context` again.
-
----
-
-## 🛑 Strict rules
-
-1. **Do not jump ahead**: Never do “Plan” when the CLI says “Spec”.
-2. **Do not skip**: Do not fake issue numbers/statuses to advance steps.
-3. **No self-judgment**: If unsure, run `context` again.
-
-> Note: the workflow steps may change over time. Do not memorize step numbers.
-> Treat `context` output as the SSOT.
-
----
-
-## Getting started
-
-If the Feature folder does not exist yet:
-
-- If the user's request includes an explicit Idea ref such as `I001`, `I001-slug`, or `docs/ideas/...`, preserve that ref and create the feature with `npx lee-spec-kit feature <name> --idea <ref>`.
-- Do not infer an Idea ref. Use `--idea` only when the request explicitly names one.
-
-```bash
-# 1) Create the folder
-npx lee-spec-kit feature <name> -d "<description>"
-
-# 2) Enter the loop
-npx lee-spec-kit context
-```
+## Start
+
+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>"`
+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.
+
+## Working Rules
+
+- Docs are the SSOT. Follow the active feature docs directly.
+- Progress through the documented stages directly:
+  - `spec.md` defines scope and review state
+  - `plan.md` defines the implementation approach
+  - `tasks.md` drives execution order
+  - `issue.md` / `pr.md` are part of the stage gate once the feature reaches GitHub workflow stages
+- Do not begin implementation just because `tasks.md` exists. Implementation starts only when `workflow-stage --json` allows it.
+- When scope or behavior changes, update the active feature docs in the same turn before continuing.
+- Ask for approval at documented review checkpoints and before remote or destructive actions.
+- Use `npx lee-spec-kit commit-audit --json` before `git commit` when docs-path validation matters.
+- Use `npx lee-spec-kit workflow-audit --json` before stopping when code or feature docs changed.
+
+## Strict Rules
+
+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.

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

@@ -8,7 +8,10 @@ Execution-state SSOT is the feature-local `issue.md`.
 ## Prerequisites
 
 - [ ] `spec.md` completed
-- [ ] Latest `context --json-compact` checked
+- [ ] `plan.md` completed
+- [ ] `tasks.md` completed and execution-ready
+- [ ] Active feature docs reviewed
+- [ ] `npx lee-spec-kit workflow-stage <feature-ref> --json` says the next stage is issue preparation or issue creation
 
 ---
 
@@ -38,9 +41,7 @@ Use `issue.md` status (`Draft | Ready`) as the actual workflow state.
 | Labels   | `enhancement`, `bug`, `documentation`, etc. |
 | Assignee | `@me` (default)                             |
 
-### 2. Move to `Ready` (request approval only when context requires it)
-
-> ⚠️ **Workflow label approval is conditional**
+### 2. Move to `Ready`
 
 Share the `issue.md` draft:
 
@@ -48,16 +49,13 @@ Share the `issue.md` draft:
 - Full body draft (from `issue.md`)
 - Labels
 
-Then re-check the latest `npx lee-spec-kit context --json-compact`.
-
-- If `approvalRequest.required=true`, show the exact CLI-provided approval lines and wait for a label reply (`A` or `A OK`) before continuing.
-- If `approvalRequest.required=false`, do not invent a separate label prompt; refine the draft and set `issue.md` status to `Ready`.
+Refine the draft and set `issue.md` status to `Ready` once the document is complete.
 
 ### 3. Create Issue (when `issue.md` is `Ready`)
 
 Remote issue creation must use the lee-spec-kit helper.
 Do not call `gh issue create` directly or pass raw `issue.md` to `--body-file`.
-Command-level remote confirmation is still required even when workflow label approval is not:
+Remote confirmation is always required:
 
 - share the final title/body/labels with the user
 - then run the helper with `--confirm OK`
@@ -69,6 +67,7 @@ npx lee-spec-kit github issue F001 --create --confirm OK --labels enhancement
 After creation:
 - sync created issue number into `tasks.md`
 - keep `issue.md` status as `Ready` (creation state is tracked in `tasks.md`)
+- re-run `npx lee-spec-kit workflow-stage <feature-ref> --json` and continue from the returned next stage instead of jumping straight into implementation
 
 ---
 
@@ -76,6 +75,6 @@ After creation:
 
 - **Draft generator**: `npx lee-spec-kit github issue <feature-name>`
 - **Remote creation rule**: must use `npx lee-spec-kit github issue <feature-name> --create --confirm OK --labels ...`
-- **Workflow approval rule**: only wait for label approval when `approvalRequest.required=true`
+- **Workflow approval rule**: ask the user for approval before remote issue creation
 - **Remote confirm rule**: share title/body/labels first, then run `--create --confirm OK`
 - **Execution-state SSOT**: `docs/features/.../<feature>/issue.md`

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

@@ -9,6 +9,7 @@ Execution-state SSOT is the feature-local `pr.md`.
 
 - [ ] All tasks in `[DONE]` state
 - [ ] All checkboxes in `tasks.md` "Completion Criteria" are checked
+- [ ] `npx lee-spec-kit workflow-stage <feature-ref> --json` says the next stage is PR preparation or PR creation
 - [ ] Changes committed
 - [ ] Branch pushed
 
@@ -22,7 +23,7 @@ Always run this checklist in Pre-PR review. Treat it as the minimum baseline, th
 2. Inspect regression, exception handling, critical/security risks, side effects, user flow impact, and release readiness.
 3. Check maintainability: split oversized functions/files when needed, reuse/integrate existing code where appropriate, and remove obsolete code.
 4. Judge whether the implementation actually fits the feature intent and scope documented in `spec.md` / `plan.md` / `tasks.md`.
-5. When `workflow.prePrReview.evidenceMode=path_required` (default), run the review agent first, generate `review-trace.json`, then run `npx lee-spec-kit pre-pr-review <feature-ref> --evidence review-trace.json`. In `evidenceMode=any`, direct record mode without `--evidence` is also allowed unless execution evidence is explicitly enforced.
+5. When `workflow.prePrReview.evidenceMode=path_required` (default), generate a real review artifact such as `review-trace.json` before approval. In `evidenceMode=any`, direct record mode without a separate artifact is also allowed unless execution evidence is explicitly enforced.
 6. `Pre-PR Evidence` should follow the configured evidence policy. In `path_required`, it must point to a real existing path.
 7. Record `Summary`, `Feature Intent Summary`, `Implementation Fit`, `Missing Cases`, `Spec Alignment Checked`, `Finding Count`, `Blocking Findings`, `Findings`, and `Residual Risks` with non-placeholder content.
 8. Use `commandsExecuted` only for optional audit/targeted verification that you actually chose to run during review.
@@ -145,9 +146,7 @@ echo \"![](https://github.com/${REPO}/releases/download/${TAG}/ui-1.png)\"
 - Write a Mermaid **`sequenceDiagram`** in the PR body and keep it aligned with the generated body template format.
 - Apply this rule based on change type (logic/structure), not by frontend/backend classification.
 
-### 4. Move to `Ready` (request approval only when context requires it)
-
-> ⚠️ **Workflow label approval is conditional**
+### 4. Move to `Ready`
 
 Before creating the PR, share the following **in a code block**:
 
@@ -155,18 +154,13 @@ Before creating the PR, share the following **in a code block**:
 - Full body template (from `pr.md`)
 - Labels (at least 1; cannot be empty)
 
-Then re-check the latest `npx lee-spec-kit context --json-compact`.
-
-- If `approvalRequest.required=true`, wait for the exact CLI-provided `<LABEL>` or `<LABEL> OK` reply.
-- If `approvalRequest.required=false`, do not invent a separate label prompt.
-
 Before moving on, refine `pr.md` Changes/Tests sections based on actual work and set `pr.md` status to `Ready`.
 
 ### 5. Create PR (when `pr.md` is `Ready`)
 
 Remote PR creation must use the lee-spec-kit helper.
 Do not call `gh pr create` directly or pass raw `pr.md` to `--body-file`.
-Command-level remote confirmation is still required even when workflow label approval is not:
+Remote confirmation is always required:
 
 - share the final title/body/labels with the user
 - then run the helper with `--confirm OK`
@@ -179,6 +173,7 @@ After creation:
 - record created PR link into `tasks.md`
 - record/keep PR status as `Review`
 - keep `pr.md` status as `Ready` (creation/merge state is tracked by `tasks.md` PR/PR Status)
+- re-run `npx lee-spec-kit workflow-stage <feature-ref> --json` and continue from the returned review/merge stage
 
 ---
 
@@ -221,6 +216,6 @@ Use **current branch name** for file links in PR body:
 
 - **Body template generator**: `npx lee-spec-kit github pr <feature-name>`
 - **Remote creation rule**: must use `npx lee-spec-kit github pr <feature-name> --create --confirm OK --labels ...`
-- **Workflow approval rule**: only wait for label approval when `approvalRequest.required=true`
+- **Workflow approval rule**: ask the user for approval before remote PR creation or merge
 - **Remote confirm rule**: share title/body/labels first, then run `--create --confirm OK`
 - **Execution-state SSOT**: `docs/features/.../<feature>/pr.md`

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

@@ -1,111 +1,50 @@
-# Task Execution Process: CLI-driven
+# Task Execution Process: Docs-first
 
-This document defines the **only rule** for executing tasks.
-As an agent, follow `npx lee-spec-kit context` as the single source of truth.
+Use the active feature folder as the execution SSOT.
 
 ---
 
-## 🔄 The Loop (repeat forever)
+## 1. Pick the current task
 
-Repeat this loop until the Feature is complete.
+- Before touching code, run `npx lee-spec-kit workflow-stage <feature-ref> --json`.
+- Only continue if it reports `stage === "implementation"` and `implementationAllowed === true`.
+- Resolve the active feature first.
+- In `tasks.md`, either:
+  - continue the single `[DOING]` task, or
+  - move the next highest-priority `[TODO]` task to `[DOING]`
+- Work one task at a time. Do not batch-complete multiple tasks in one pass.
 
-### Step 1: Check context
+## 2. Execute and record
 
-```bash
-npx lee-spec-kit context
-```
+- Keep `tasks.md` aligned with reality:
+  - do not mark `[DONE]` without real completion and verification
+  - update `Acceptance` and `Checklist` in the same edit when closing a task
+  - if a completed task needs follow-up, add a new task instead of rewriting history
+- If you need to add a new task, prefer `npx lee-spec-kit task add <feature-ref> --title "..." --ref NON-PRD|PRD-*`.
+- Do not leave placeholder `Acceptance` or `Checklist` items in newly added tasks.
 
-### Step 2: Do the next action only
+## 3. Keep docs in sync
 
-Execute exactly one option from `👉 Next Options (Atomic)` as printed by the CLI.
+- `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
+- If `Pending Change Request` is present, sync `tasks.md` first, then update supporting docs and clear the field before resuming implementation
 
-- If the CLI points to an active task, focus on that task only.
-- Treat task state transitions in `tasks.md` **"Task Rules"** as SSOT.
-- Treat `approvalRequest.required` from `context --json-compact` as SSOT for approval waiting (`--json` only when full-detail debugging fields are required).
-  - `false`: continue without label approval.
-  - `true`: wait for label-token approval (`A`, `A OK`) before execution.
-- Default execution model is **main-agent orchestration + sub-agent-first execution for sub-agent-owned run states**. Use `matchedFeature.currentSubstateId/currentSubstateOwner/currentSubstatePhase` from `context --json-compact` as the execution-state SSOT when present.
-- Main agent owns approval boundaries, state transitions, record/commit steps, and remote operations. Sub-agent execution is the default for command substates owned by `subagent` (for example `task_run`, `pre_pr_review_run`, `code_review_run`, and auto-run handoff commands).
-- `pre_pr_review` is split into `pre_pr_review_run` (sub-agent review execution) and `pre_pr_review_record` (main-agent recording of evidence/results).
-- PR review follows the same pattern: `code_review_run` is the sub-agent review/fix execution state, and the merge/push/final decision stays in the main-agent finalize state.
-- Prefer `matchedFeature.currentSubstateOwner` plus `agentOrchestration.subAgentHandoff` as the delegation SSOT.
-- When `matchedFeature.currentSubstateOwner="subagent"` and `agentOrchestration.subAgentHandoff.required=true` with `mode="command"`, delegation is mandatory: call `spawn_agent` first and do not execute the command directly from the main agent.
-- Do not delegate auto loops from `autoRun.available` alone. Delegate auto loops only when `agentOrchestration.subAgentHandoff.required=true` and `agentOrchestration.subAgentHandoff.mode="auto_run"`.
-- Use `agentOrchestration.subAgentHandoff` as the minimal handoff contract (`featureRef`, `category`, `cwd`, `cmd`).
-- If an action option exposes `handoffOnly=true` and `advancesWorkflow=false`, do not treat `--execute` success as workflow progress. Finish the delegated work and update the required evidence/state before running `context` again.
-- Run `subAgentHandoff.verify.commands` only once per session using `verify.cacheKey` (`pwd`, `git rev-parse --show-toplevel`). Stop/report on mismatch, and gather detailed logs only when mismatch happens.
-- Main-agent fallback is allowed only when sub-agent execution is unavailable (for example: tool not available, spawn failed, or sub-agent failed before command execution). Before fallback execution, report a one-line fallback reason to the user.
-- Use `autoRun.command` only when `context --json-compact` exposes `autoRun.available=true`.
-- If `autoRun.policyEligible=true` but `autoRun.executableNow=false`, handle `autoRun.manualBoundary` first instead of starting an auto loop.
-- For long-running auto execution, start with `flow <feature> --auto-... --start-auto --json-compact` and prefer `autoRun.run.resumeCommand` (`flow --resume <RUN_ID>`) after interruption/compression (`--json` only when full-detail debugging fields are required).
-- If auto execution stops, treat `autoRun.resume` from `flow --json-compact` (or `flow --json`) as SSOT. After interruption/compression, resume with `autoRun.resume.flowCommand`; if needed, check current state first with `autoRun.resume.contextCommand`.
-- Treat `AUTO_DELEGATED_HANDOFF` as a delegated pause, not a crash. Reuse the delegated run path and continue the delegated work before asking for a fresh approval label.
-- Treat `AUTO_MANUAL_REQUIRED` as an automation boundary (instruction-only segment), not an immediate crash. Re-check `context --json-compact` and report whether `approvalRequest.required` is now true.
-- Treat `AUTO_SELECTION_REQUIRED` as a feature-selection pause, not a crash. Resolve the active feature first, then rerun `context --json-compact` or `flow`.
-- If `matchedFeature.currentSubstateId === "change_request_sync"` or `matchedFeature.pendingChangeRequest` is present, sync docs before more code work: update `tasks.md` first, add or retag the affected task, and if shipped behavior or scope changed, sync `decisions.md` plus `spec.md` / PRD refs as needed. Clear `Pending Change Request` after syncing, then rerun `context --json-compact` or `flow`.
-- If the CLI prints commands, copy/paste them. (In standalone setups commands may include `git -C ...` and scopes like `project`/`docs`.)
-- Follow `agents.md` **"Label Response Contract (SSOT)"**. Show label prompts only in approval-waiting state, and reuse the exact CLI-provided approval lines instead of paraphrasing them.
-- If you answer a side question while `approvalRequest.required=true`, answer first, then briefly restate `matchedFeature.currentSubstateId/currentSubstateOwner/currentSubstatePhase` when available and re-show the exact CLI approval lines before waiting again.
-- For non-delegated command options, default to `npx lee-spec-kit flow <slug|F001|F001-slug> --approve <LABEL> --execute` and avoid split `context --approve` / `context --execute --ticket` runs across turns.
-- If the current command is delegated (`matchedFeature.currentSubstateOwner="subagent"` and `agentOrchestration.subAgentHandoff.required=true` with `mode="command"`), call `spawn_agent` first and pass the handoff contract instead of executing that command from the main agent.
-- If `flow/context --execute --json` returns `approved_handoff_prepared`, stop re-approving the same label. Complete the delegated work first, then refresh context.
+## 4. Commit and stop guardrails
 
-### Step 3: Update tasks.md (only what you did)
+- Before `git commit`, use `npx lee-spec-kit commit-audit --json` when docs-path validation matters.
+- Before stopping, use `npx lee-spec-kit workflow-audit --json` if code or feature docs changed.
+- Keep one row per test command in the `tasks.md` test log and update that row on reruns instead of appending duplicates.
 
-Keep `tasks.md` aligned with reality.
+## 5. Approval boundaries
 
-- Do not mark `[DONE]` without actually completing the work and verifying criteria.
-- If you need to change a completed task, add a new task instead of rewriting history.
-- If you need to add a new task, prefer `npx lee-spec-kit task add <feature-ref> --title "..." --ref NON-PRD|PRD-*`. Use an existing PRD key such as `PRD-FR-001` or `PRD-SCOPE-V1-DESKTOP-EDITOR`. Add `--acceptance` and `--check` inline when you already know the concrete items.
-- Do not leave placeholder `Acceptance` / `Checklist` items in a newly added task. `task-run` will block until those fields contain concrete execution/verification items.
-- If manual editing is unavoidable, append the new task directly below the last existing task block in the `Task List` section.
-- Do not insert it near the current task or right before `Completion Criteria` / the next `##` heading.
-- When handling a mid-implementation user change request, treat `Pending Change Request` as a temporary sync marker: reflect the request in `tasks.md`, sync supporting docs if the behavior/scope changed, then clear that field before resuming implementation.
+- Ask for approval only at documented review checkpoints and before remote or destructive actions.
+- Before issue creation, PR creation, push, merge, or similar remote actions, share the exact artifact or plan first.
+- Codex may delegate implementation work, but docs updates, approval handling, and remote actions stay with the main session.
 
-### Step 3.25: Record decisions (strongly recommended, effectively required)
+## Strict Rules
 
-To avoid “why did we implement it like this?” losing context, **record any non-obvious or tradeoff-heavy implementation choice** in `decisions.md`.
-
-Record a decision if any of these apply:
-
-- There was a tradeoff (performance / reliability / security / maintainability)
-- You introduced a new rule/heuristic/state transition (e.g., context detection logic, exception criteria)
-- The user asked “why did you do it this way?” (requested rationale/justification)
-- The user explicitly asked to change behavior (requirements/policy/criteria changes)
-- You changed behavior for compatibility or as a workaround
-- You changed data shape, file structure, or CLI output rules
-- You expect future readers to ask “why this way?”
-
-Timing rules:
-
-- When moving a task to `[DOING]`, first add 1-3 lines for `Context/Constraints` and `Trace (initial hypothesis)`.
-- Before moving a task to `[DONE]`, finalize `Options/Decision/Rationale` and strengthen `Trace (final reasoning)`.
-- After PR merge, append 1-2 lines in `Trace (post-merge check)` with actual outcome/impact.
-
-Evidence rules:
-
-- Every ADR must include at least one Evidence link (commit, PR, or test/log evidence).
-- Prefer filling all three (`Commit`, `PR`, `Test/Log`); if not applicable, mark as `N/A`.
-
-Use the feature’s `decisions.md` template format as final SSOT. (Context/Constraints/Options/Decision/Rationale/Trace/Evidence/Consequences)
-
-### Step 3.5: Commit per task (important)
-
-- Complete **only one task at a time** (do not batch-finish multiple tasks in one commit).
-- After you share the outcome/verification, mark the task `[DONE]` and update the task-local checklist items in the same edit. `task-complete` will reject `[DONE]` if unchecked checklist boxes remain. If approval is required (`approvalRequest.required=true`), reuse the exact CLI-provided approval lines and wait for a `<LABEL>` or `<LABEL> OK` reply first. If approval is not required, do not invent a separate approval prompt before marking `[DONE]`.
-- In `tasks.md` test logs, keep one entry per test command and update its date/result on reruns (do not keep appending duplicates). Use `YYYY-MM-DD` in local date.
-- If `context` shows `[CHECK required]`, for commits/push/merge, **share the commit message + included files and wait for the latest CLI-provided label reply** before running the commands.
-- Once all tasks are `[DONE]`, share the "Completion Criteria" checklist with the user. If that point is approval-waiting, get a `<LABEL>` or `<LABEL> OK` reply before checking it; otherwise get a normal confirmation reply. (especially the final outcome/user confirmation item).
-  - Note: both progress approval and final approval must follow the current `approvalRequest.required` state. When approval is label-gated, always use label replies instead of standalone `OK` as the approval token.
-
-### Step 4: Repeat
-
-After finishing a meaningful chunk of work, run `context` again.
-
----
-
-## 🛑 Strict rules
-
-1. **No skipping**: Never “finish” tasks by editing status only.
-2. **No jumping ahead**: If the CLI is waiting for approvals, stop and ask the user.
-3. **No rewriting history**: Do not modify `[DONE]` tasks; add a new one.
+1. Do not skip required doc updates.
+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.

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

@@ -106,7 +106,7 @@ When a feature is already in progress, treat those files as staging/reference ar
 
 - If the extra docs entry is intentional, add it to `.lee-spec-kit.json` `allowedDocsEntries`
 - If it is a planning/reference artifact, normalize it before continuing active feature execution
-- If `context` surfaces `docs_normalize`, handle that step first
+- `commit-audit` blocks staged unmanaged or non-canonical feature docs until they are normalized or allowlisted
 
 - Move user-facing scope and acceptance criteria into `spec.md`
 - Move architecture/file structure/test strategy into `plan.md`