@guanlin4924/devflow-pi 0.1.60 → 0.1.63

package/plugins/devflow-core/skills/workflow-project-context/SKILL.md

@@ -1,852 +1,127 @@
 ---
 name: workflow-project-context
-description: "Use when a new or existing project needs .planning initialization, repository discovery, project context, navigation files, or rule-package setup."
+description: "Use when a project needs database-backed initialization, repository discovery, project facts, code indexing, navigation, or initialization recovery."
 ---
 
-## Legacy Command Metadata
-
-Original slash-command metadata retained only as workflow invocation guidance.
-
-```yaml
-argument-hint: '[--auto]'
-user-invocable: true
-pattern: inversion+generator+reviewer
-resumable: true
-state-file: .planning/STATE.md
-allowed-tools:
-- Read
-- Bash
-- Write
-- Glob
-- Grep
-- ask
-```
-
 # Project Initialization
 
-Initialize project context only. Do not create requirements, roadmap, research files, commits, tags, or Git repositories unless the user explicitly asks.
-
-## Outputs
-
-Always create or update:
-
-- `.planning/PROJECT.md` — project facts, structure, navigation, constraints, and decisions
-- `.planning/STATE.md` — initialization state, project locations, scan status, and next recommended step
-- `.planning/navigation/INDEX.md` — codebase registry: maps each codebase to its navigation file, plus rule package index and downstream read contract
-- `.planning/navigation/{name}.md` — one file per codebase: framework, entries, conventions, commands (name comes from user-provided codebase name)
-- `.planning/code-index/` — machine code intelligence index location; generated by `workflow-code-index` by default unless fast mode skips it
-- `.context/static-runtime-context/` + `.context/static-runtime-context.json` — Core-owned, Git-bound static declarations snapshot; never a production-health or capacity assertion
-- `.context/spec/design/` — conditional frontend design rule package; installed after code-index for projects with frontend codebases
-- `.planning/project-context-run.json` — current-run evidence: run identity, code-index status, dynamically discovered depth specs, source paths, and source fingerprints
-- `.context/spec/index.md` — generated technical specification registry: maps stack profiles and codebase specs
-- `.context/spec/stacks/{stack_key}.md` — deduplicated stack-level technical rules for each detected stack profile
-- `.context/spec/frontend/{name}.md` / `.context/spec/backend/{name}.md` — codebase-specific technical rules generated from explicit rules and observed conventions
-- `.planning/rules/INDEX.md` — project rule index, the first file downstream skills read for project-specific conventions
-- `.planning/execution-contract.md` — layer order, TDD strategy, codegen and verification gates
-- `.planning/toolchain.md` — consolidated build, test, lint, mock, and migration commands
-
-Also record existing project rule package locations when found (these are accumulated over time, not created during initialization):
-
-- `.planning/lessons/`
-- `.planning/milestones/`
-- `.planning/requirements/`
-- `.context/spec/`
-- `.context/workflow/`
-- `.context/lessons/`
-- root `AGENTS.md`, `CLAUDE.md`, or equivalent instruction files
-
-Do not create by default:
-
-- `.planning/REQUIREMENTS.md`
-- `.planning/ROADMAP.md`
-- `.planning/research/`
-- `.planning/config.json`
-
-## Pattern
+Initialize project context only. Do not create requirements, approved API contracts, prototypes, roadmaps, commits, tags, repositories, or workflow state.
 
-This skill combines three patterns:
+## Authority and ownership
 
-- **Inversion**: ask for required project locations before scanning or generating files.
-- **Generator**: fill templates from `assets/`.
-- **Reviewer**: check the generated files against `references/navigation-guide.md`.
+The control database under the product data directory is the only machine authority for initialization. `.devflow/project.json` locates project identity. Workspaces, scan configurations, input snapshots, runs, facts, evidence, index references, current pointers, document jobs, and authority revisions are stored through `devflow_project_context`.
 
-Load bundled resources only when needed:
+Never determine current initialization state from Markdown, file mtimes, or duplicated run markers. Never write `.planning/STATE.md`, execution contracts, workflow artifacts, requirements, approvals, or user instruction files.
 
-**Internal resource URL rule (mandatory):** `skill://` URLs identify one exact
-resource. Never pass a `skill://` URL to Glob or Grep and never append `*`,
-`**`, or other wildcard syntax to it. First choose a concrete template name
-from the inventory below, then use Read with the complete URL. A generated
-project file such as `.context/spec/frontend/index.md` is an output and is not
-the same thing as a source template under `assets/`.
+Human-readable files are projections. Existing unmanaged files are preserved; the generator writes a `.devflow-pending` sibling when it cannot prove that the current file is its previous output.
 
-Available depth templates:
+## Modes
 
-- frontend: `api-client`, `case-editor`, `components`, `directory-structure`, `forms`, `routing`, `state`, `testing`
-- backend: `directory-structure`, `engine`, `errors`, `locator`, `model`, `repository`, `router`, `scheduler`, `schema`, `service`, `testing`
+- Full mode is the default. It performs bounded static fact collection and builds, validates, and audits an immutable code-index generation before the context snapshot becomes current.
+- Fast mode is allowed only when the user explicitly requests `--fast` or `--skip-code-index`. Pass a deliberately limited `requiredKinds` list. It records the index as explicitly skipped and never masquerades as full mode.
+- Static initialization never runs discovered build, test, migration, service, network, or database commands. Those strings are facts, not instructions.
 
-- Read `assets/project-initialization-template.md` before writing `PROJECT.md`.
-- Read `assets/codebase-navigation-template.md` before writing each codebase navigation file.
-- Read `assets/navigation-index-template.md` before writing `.planning/navigation/INDEX.md`.
-- Read `assets/context-spec-index-template.md` before writing `.context/spec/index.md`.
-- Read `assets/stack-spec-template.md` before writing each `.context/spec/stacks/{stack_key}.md`.
-- Read `assets/codebase-backend-spec-template.md` before writing each backend/service `.context/spec/backend/{name}.md`.
-- Read `assets/codebase-frontend-spec-template.md` before writing each frontend `.context/spec/frontend/{name}.md`.
-- Read `assets/spec-templates/backend/{template}.md` before writing each backend depth spec file.
-- Read `assets/spec-templates/frontend/{template}.md` before writing each frontend depth spec file.
-- Read `assets/agents-md-template.md` before writing root `AGENTS.md`.
-- Read `assets/context-domain-index-template.md` before writing `.context/spec/frontend/index.md`, `.context/spec/backend/index.md`, and `.context/spec/design/index.md`.
-- Read `assets/state-template.md` before writing `.planning/STATE.md`.
-- Read `assets/execution-contract-template.md` before writing `.planning/execution-contract.md`.
-- Read `assets/toolchain-template.md` before writing `.planning/toolchain.md`.
-- Read `assets/rules-index-template.md` before writing `.planning/rules/INDEX.md`.
-- Read `assets/run-manifest-template.json` before writing `.planning/project-context-run.json`.
-- Read `references/navigation-guide.md` before scanning code and again before final review.
-- Run `scripts/validate_initialization.py` as the final completion gate.
+## Intake and identity
 
-## Argument Handling
+Collect every codebase with a stable name, local path, and role (`frontend`, `backend`, `shared`, or `other`). Ask only for missing paths or a choice that changes authority. In automatic mode, use the current workspace as one `other` repository and preserve unknown business meaning as unknown.
 
-Parse `$ARGUMENTS` before Step 1:
-
-- `--auto`: non-interactive initialization. If codebase locations are not provided, treat the current workspace as a single codebase, scan boundedly, and mark anything not found as `待确认` or `pending`. Do not block on project-name or business-context questions; infer what is obvious and record missing facts.
-- `--fast` / `--skip-code-index`: fast initialization. Generate project context, navigation, specs, and rules, but skip Step 6.5 (code-index) and mark code-index as skipped in `STATE.md`, `PROJECT.md`, navigation INDEX, and rules INDEX. This is the ONLY condition under which code-index may be skipped. Without this flag, code-index is REQUIRED regardless of whether `.planning/` already exists.
-- `--with-code-index`: compatibility flag for explicit full initialization. This is the default behavior; after navigation generation, run Step 6.5 to build/validate/audit `.planning/code-index/`, then carry its status into the remaining generated context and rule files.
-- Other text may be used as project-name or project-context hint when it is not a path.
-
-At invocation start, before scanning or writing:
-
-1. Generate a unique `run_id`.
-2. Capture `run_started_at` as an ISO-8601 UTC timestamp.
-3. Set mode to `full`, or `fast` only when one of the explicit skip flags is present.
-4. Carry the same `run_id`, `run_started_at`, `code_index_status`, and skip reason into all templates and `.planning/project-context-run.json`. Use `none` when full mode has no skip reason.
-
-In non-auto mode, ask the intake questions below.
-
-## Existing Planning Update Policy
-
-If `.planning/` already exists:
-
-1. Read existing `.planning/PROJECT.md`, `.planning/STATE.md`, and `.planning/navigation/*.md` before writing.
-2. Preserve user-authored business context, constraints, key decisions, and missing information unless the user explicitly asks to replace them.
-3. Refresh only machine-derived fields. This includes: detected paths, frameworks, entries, commands, scan status, navigation index, rule package files (execution-contract.md, toolchain.md, rules/INDEX.md), **all currently discovered depth spec files (Step 7.4)**, **code index (Step 6.5)**, and **static runtime-context (Step 6.5a)**. The presence of existing output files does NOT exempt a step from re-execution — machine-derived fields must be regenerated to reflect current codebase state.
-4. If provided codebase locations differ from existing records, record the change in `STATE.md` under `Change Log`.
-5. Never delete existing planning files during initialization. Preserve user-authored content in execution-contract.md and toolchain.md when refreshing machine-derived fields.
-
-## Step 1 — Intake Gate
-
-Before any initialization, ask for all codebases in the project:
+Inspect registered workspaces and configuration before scanning:
 
 ```text
-请提供项目涉及的所有代码库。每个代码库需要三个信息：
-  - 地址：本地路径或 Git 仓库 URL；如果在当前目录，请写”当前目录”
-  - 类型：描述这个代码库的角色（如：C端前端、后台前端、后端服务、定时任务、SDK等）
-  - 名称：简短的标识名称，用作导航文件名（如：union-next、saas-admin、union-api）
-
-示例（3个代码库的项目）：
-  1. byn-web/packages/union-next   C端前端    union-next    联盟客户侧
-  2. byn-web/packages/saas-admin   后台前端   saas-admin     运营后台
-  3. union/                        后端服务   union          联盟核心服务
-
-如果只有1个代码库，写1行即可。
-```
-
-Do not proceed until at least one codebase is provided, except in `--auto` mode where the current workspace is used as a single codebase with `待确认` type and name inferred from the directory.
-
-Accepted values per codebase:
-- **Path**: local path (`./frontend`, `/path/to/web`), Git URL (`https://...`, `git@...`), current workspace (`当前目录`, `same repo`, `.`)
-- **Type**: freeform text describing the codebase's role. Common values: `C端前端`, `后台前端`, `后端服务`, `定时任务`, `SDK`, `公共组件库`, `移动端` — but these are not hardcoded; use whatever the user provides.
-- **Name**: short identifier safe as a filename segment (letters, digits, hyphens). Used for `.planning/navigation/{name}.md`.
-
-If a Git URL is provided, record it. Ask before cloning; do not clone automatically.
-
-Record the codebase list for use in Step 3 (scan) and Step 6 (generate navigation files).
-
-## Step 2 — Minimal Project Questions
-
-Ask only what cannot be inferred from code:
-
-1. Project name
-2. What the product/system does
-3. Primary users or business domain
-4. Non-negotiable constraints, if any
-
-If the user says these are unknown, continue and mark them as `待确认`.
-
-## Step 3 — Structure Scan (Four-Phase)
-
-Read `references/navigation-guide.md`. Run the following four phases for EACH codebase from Step 1. Each phase has its own scan depth, output, and gate. Do not skip phases.
-
-Exclude generated/dependency directories in all phases: `node_modules`, `dist`, `build`, `.next`, `.nuxt`, `target`, `vendor`, `.git`, `coverage`.
-
-### Step 3a — Directory Map (Mandatory)
-
-Scan the codebase's top-level and second-level directory layout. This is the factual layer — what directories exist and what they contain.
-
-Scan method:
+devflow_project_context(action="workspaces")
+devflow_project_context(action="config")
 ```
-1. rg --files from codebase root → extract top-level and second-level directories
-2. Identify key manifest/config files: package.json, go.mod, Makefile, Dockerfile, README
-3. For each directory, infer purpose from file names and README content
-4. Do NOT read source files in depth — only directory names and manifests
-```
-
-Output (write to `{name}.md` → `## Structure → ### Directory Map`):
-- ASCII directory tree (top-level + second-level)
-- Table: Directory | Purpose | Notes
-
-Gate: every top-level and second-level directory is listed with a purpose (one sentence, inferred from file names is acceptable). Key entry files (main.go, main.ts, router files, handler files) are identified.
-
-### Step 3b — Call Chain Map (Mandatory)
-
-Trace the call chains through the codebase. This is the connectivity layer — how code connects across directories.
-
-**Dual-path routing** (decide before scanning):
-
-```
-For each codebase, check if a rule file exists in this order:
-  1. .cursorrules within the codebase root
-  2. AGENTS.md / CLAUDE.md at project root or codebase root
-
-If a rule file EXISTS → Path A: Conventions first
-  1. Execute Step 3c first to extract conventions
-  2. Use extracted conventions to guide call chain tracing
-  (e.g., if convention says "handler→service→repository→dao", follow that pattern)
-
-If NO rule file → Path B: Call chain first
-  1. Trace call chains from entry points by following imports/method calls
-  2. The traced patterns will feed into Step 3c for convention extraction
-```
-
-Scan method:
-
-**Backend-type codebases** (type contains "后端" or "服务"):
-```
-1. Find handler files (look for route registration patterns):
-   - Go: files with RegisterRoutes, gin routes, or echo routes
-   - Java: @RestController, @RequestMapping
-   - Node: router files, controller files
-2. For each handler, extract registered routes and the methods they call
-3. Follow the call chain: handler method → service method → repository method → dao method
-4. Find job/scheduler files (look for cron patterns, @Scheduled, job registration):
-   - Extract cron expression or trigger condition
-   - Trace the job's call chain into services
-5. Find external integration packages/directories:
-   - Identify outbound HTTP clients, gRPC clients, message queues
-```
-
-Output (write to `{name}.md` → `## Structure → ### Call Chain Map`):
-- `#### API Modules` table: Route Group | Handler | Routes | Service → Repository → DAO
-- `#### Scheduled Jobs` table: Job | Cron | Trigger Type | Call Chain | Notes
-- `#### External Integrations` table: Integration | Path | Direction | Notes
-
-Gate: every handler file identified in 3a has its call chain traced (at minimum: handler→service). Every job file has its trigger and target service identified.
-
-**Frontend-type codebases** (type contains "前端"):
-```
-1. Read router configuration → extract all routes with their page components
-2. For each page component, read the file and extract:
-   - Imported child components (from page-private and common components)
-   - Imported composables/hooks
-   - API calls (direct or through composables)
-3. For each composable, extract:
-   - API client methods called
-   - State shape (reactive/ref/store)
-4. Build the route→component→composable→API call tree
-```
-
-Output (write to `{name}.md` → `## Structure → ### Call Chain Map`):
-- `#### Route-Component Map` table: Route | Page Component | Child Components | Composables | API Calls
-- `#### Data Flow` table: Composable / Store | API Client | State Shape | Consumed By
-
-Gate: every route has its page component and at least the first-level child components listed. Every composable used by more than one component is in the Data Flow table.
 
-### Step 3c — Conventions (Mandatory)
+A copied project manifest creates a distinct workspace. Rebind a moved directory only after the user identifies the old workspace:
 
-Extract the coding conventions that govern this codebase. This is the rules layer — how code should be written.
-
-**If Path A (rule file existed, 3c was already executed before 3b):**
-- The conventions extracted from .cursorrules / AGENTS.md were used to guide 3b.
-- Now cross-validate: did the actual code follow these conventions? If violations found, note them.
-
-**If Path B (no rule file, 3c runs after 3b):**
-- Infer conventions from the patterns observed during 3b call chain tracing.
-- If a pattern is consistent across all modules (e.g., every handler calls a service interface), record it as a convention.
-- If patterns are inconsistent, record the dominant pattern and note the variations.
-
-Scan method:
-```
-1. If .cursorrules or AGENTS.md / CLAUDE.md exist, read them and extract:
-   - Layer/component hierarchy rules
-   - Naming conventions
-   - Data conversion rules (VO↔Domain↔Model)
-   - Error handling patterns
-   - Code generation or documentation rules
-2. If no rule file, infer from 3b observations:
-   - Consistent directory patterns → layer convention
-   - Consistent method signatures → interface convention
-   - Consistent import patterns → dependency direction
-3. Mark any convention as "推断" (inferred) when not backed by an explicit rule file.
+```text
+devflow_project_context(action="rebind-workspace", workspaceId="<old-workspace>")
 ```
 
-Output (write to `{name}.md` → `## Structure → ### Conventions`):
-
-**Backend-type**: Table with columns Category | Rule | Source
-Categories: Layer order, Conversion (VO↔Domain↔Model), Interface/DI, Error handling, Naming, Swagger/API docs
-
-**Frontend-type**: Table with columns Category | Rule | Source
-Categories: Component hierarchy, Data flow (composable/store), Route naming, Style/theme, API client, State management
-
-Source values: `{rule_file_name}` (explicit rule), `代码推断` (inferred from code patterns), or `待确认` (not observed).
+Do not infer move/copy identity from timestamps or similar directory names.
 
-Gate: at least Layer order (backend) or Component hierarchy (frontend) is recorded. Inferred conventions are marked as `代码推断`, not as facts.
+## Legacy input
 
-### Step 3d — Stack Profile Extraction (Mandatory)
+Legacy `.planning` or `.context` files are never read as current machine facts. On an explicit import request, register selected files as historical material in shadow mode:
 
-Extract a normalized stack profile for each codebase. This is the dependency fingerprint layer: which runtime, framework, major versions, and key libraries govern the codebase.
-
-Scan method:
-```
-1. Read detected manifest files from 3a:
-   - Frontend/Node: package.json, pnpm-lock.yaml, yarn.lock, package-lock.json
-   - Python: pyproject.toml, requirements.txt, poetry.lock, uv.lock
-   - Go: go.mod
-   - Java/Kotlin: pom.xml, build.gradle, build.gradle.kts
-2. Extract only dependency names and versions needed to identify the stack profile:
-   - language/runtime
-   - primary framework and major version
-   - key libraries that materially change conventions (e.g., Ant Design, Zustand, FastAPI, Pydantic major version, SQLAlchemy vs SQLModel, Gin, GORM, Spring Boot)
-   - package manager/build tool
-   - test framework if detectable
-3. Compute a stable `stack_key` from:
-   language + framework + framework major version + key libraries
-   Examples: `python-fastapi-pydantic2-sqlalchemy`, `react-vite-antd`, `go-gin-gorm`
-4. Record manifest path and dependency fingerprint. A hash of the manifest is acceptable; otherwise list key dependency versions.
+```text
+devflow_project_context(action="import-legacy", sources=[".planning/PROJECT.md"], requestId="<stable-request-id>")
 ```
 
-Output (write to `{name}.md` → `## Stack → ### Stack Profile`):
-- Table: Field | Value | Source
-- Required fields: language/runtime, framework, framework version, key libraries, package manager/build tool, test framework, manifest path, dependency fingerprint, stack_key
-
-Rules:
-- Do not merge different major versions or materially different key libraries into the same stack profile.
-- Do not put project-instance conventions into the stack profile. Stack profiles identify technology families; project-specific rules belong in codebase specs.
-- If a manifest exists but versions are ambiguous, record `待确认` for version and keep the manifest path.
+Imported prose remains `historical`, `observed=false`, and `approved=false`. Do not import requirements or design approval merely because text looks final.
 
-Gate: every local/scannable codebase has a stack profile. Remote/unavailable codebases may be `pending` with the known manifest or stack hint recorded.
+## Execute
 
-### After All Codebases — Project-Wide Sources
-
-After 3a/3b/3c/3d complete for all codebases, identify project-wide sources once:
-- `.planning/rules/`, `.planning/execution-contract.md`, `.planning/toolchain.md`, `.planning/lessons/`
-- `.planning/milestones/`, `.planning/requirements/`
-- `.context/spec/`, `.context/workflow/`, `.context/lessons/`
-- root `AGENTS.md` / `CLAUDE.md`
-
-Identify history model locations once:
-- primary: `.planning/milestones/`, `.planning/requirements/`, `.planning/lessons/`, `.planning/*/CONTEXT.md`
-- optional legacy: `features/`, `.context/lessons/`
-
-If a codebase location is unavailable or only a Git URL, write what is known and mark scan status as pending.
-
-Do not run `git init`.
-
-## Unknown Field Policy
-
-Avoid filling every table cell with `待确认`.
-
-- Required fields may be `待确认`: root, framework, app entry, router/controllers, commands.
-- Optional fields should be omitted from notes or summarized in `Missing Information` when not found.
-- If a whole area does not apply (e.g., frontend-type sections for a backend-only codebase), skip those sections in the codebase navigation file.
-- Each codebase gets its own navigation file regardless of type. There is no limit on the number of codebases.
-
-## Step 4 — Generate Base Directories
-
-Use this directory contract:
+For full initialization:
 
 ```text
-.planning/
-├── PROJECT.md                 # stable project overview and decisions
-├── STATE.md                   # workflow memory and initialization status
-├── project-context-run.json   # current-run completion evidence
-├── navigation/
-│   ├── INDEX.md               # codebase registry — maps each codebase to its navigation file
-│   ├── {name1}.md             # per-codebase navigation (e.g., union-next.md)
-│   ├── {name2}.md             # per-codebase navigation (e.g., saas-admin.md)
-│   └── ...                    # one file for each codebase from Step 1
-└── rules/
-    └── INDEX.md               # rule source registry
-
-.context/
-└── spec/
-    ├── index.md               # generated spec registry and read order
-    ├── stacks/
-    │   └── {stack_key}.md     # deduplicated stack-level rules
-    ├── frontend/
-    │   ├── index.md
-    │   └── {name}.md          # per-frontend codebase rules
-    ├── backend/
-    │   ├── index.md
-    │   └── {name}.md          # per-backend/service codebase rules
-    └── design/
-        └── index.md
+devflow_project_context(
+  action="scan",
+  mode="full",
+  repositories=[{"name":"app","path":".","role":"other"}],
+  documentMode="template",
+  requestId="<stable-request-id>"
+)
 ```
 
-The number of navigation files matches the number of codebases provided in Step 1. Codebase specs are generated only for matching codebase types. No hardcoded frontend/backend split is assumed beyond the user's type labels and scan evidence.
-
-Do not create requirement, roadmap, research, config, or `.context/spec/workflow/` directories during initialization unless explicitly requested.
-
-## Step 5 — Generate PROJECT.md
-
-Load `assets/project-initialization-template.md` and fill every section.
-
-Required emphasis:
-
-- Project basics
-- Codebase locations (from Step 1)
-- Current structure
-- Links to navigation files (INDEX.md and per-codebase files)
-- Constraints
-- Key decisions
-- Project rule package locations
-- History model locations, with `.planning/milestones/`, `.planning/requirements/`, and `.planning/lessons/` as primary history and `.context/lessons/` / `features/` as optional legacy sources
-- Missing information
-
-If a field is unknown, write `待确认` rather than guessing.
-
-## Step 5.5 — Generate Root AGENTS.md
+The static collector covers assets, technology, APIs, pages, data models, tasks and integrations, explicit rules and convention candidates, toolchain declarations, evidence provenance, and adapter capabilities. Observed facts require source evidence. Historical material, explicit rules, and model candidates remain distinguishable. Secret values must not enter facts, evidence snippets, model input, or generated documents.
 
-Load `assets/agents-md-template.md` and write `AGENTS.md` at the project root.
+Project initialization does not replace the architecture workflow's **Static Runtime Context Snapshot**. When that separately scoped architecture input is requested, collect it through `devflow_static_runtime_context(action="collect")`; do not treat it as a P0 dependency assessment or silently fold it into initialization facts.
 
-Fill from scan results:
+The scan freezes the complete file manifest, including uncommitted and untracked files, then scans again before publication. A modification, addition, deletion, permission failure, unsupported input, or configuration change has its own visible status and is never converted into an absence claim.
 
-- **Project name**: from Step 2 or PROJECT.md.
-- **Codebase count and types**: from Step 1 codebase list.
-- **Rule entry**: `.planning/rules/INDEX.md` as entry point.
-- **Spec entry**: `.context/spec/index.md` if spec files were generated.
+## Index behavior
 
-Do not create `.claude/`, `.codex/`, or compatibility symlinks. OMP reads the
-project-local `.omp/AGENTS.md`; root `AGENTS.md` remains the portable project rule entry.
+Python uses AST scopes. TypeScript, JavaScript, and Ruby use conservative structured scopes with declared inference limits. Other languages use file-level generic extraction. Declarations are not calls. Receiver or dynamic calls stay unresolved unless a supported resolver proves a target. Name uniqueness alone is at most an inference and generic text never becomes an exact method edge.
 
-## Step 6 — Generate Navigation Files
+Every full scan publishes an immutable generation under `.planning/code-index/snapshots/<generation>/`; root index files are compatibility projections. Current queries reject stale committed, modified, deleted, or newly added input. Historical queries name a generation. Relation traversal is cycle-safe and exposes depth, result limits, uncertainty, and truncation.
 
-Create `.planning/navigation/`.
+## Human-readable documents
 
-### 6.1 Generate INDEX.md
+Program-owned projections are `.planning/PROJECT.md`, `.planning/toolchain.md`, `.planning/navigation/INDEX.md`, `.planning/navigation/{codebase}.md`, `.planning/rules/INDEX.md`, and `.planning/initialization/report.md`.
 
-Load `assets/navigation-index-template.md` and fill the Codebase Registry with every codebase from Step 1. Each row maps a codebase name to its path, type, role, scan status, and navigation file path.
+Template mode is an explicit no-model fallback. A configured low-tier organizer may improve prose, but the program owns exact paths, commands, counts, tables, unknowns, and completion status. Model output containing internal identifiers, database structure, hashes, code blocks, or unsupported machine detail is rejected. Document failure never invalidates an already published data snapshot; retry `generate-docs` for that snapshot.
 
-### 6.2 Generate per-codebase navigation files
+## Query, refresh, cancellation, and recovery
 
-For EACH codebase from Step 1, load `assets/codebase-navigation-template.md` and generate `.planning/navigation/{name}.md`.
-
-Fill sections based on the codebase's user-provided type:
-
-**All codebases** fill these sections:
-- Identity (name, root, type, role, location, scan status)
-- Stack (framework, runtime, build tool, type-specific libraries, and Stack Profile from Step 3d)
-- Application Entry Points (app entry, and type-specific entries)
-- Commands (install, dev, build, test, lint, codegen)
-- Notes, Missing Information
-
-**Frontend-type codebases** (type contains "前端") additionally fill:
-- Stack: UI Library, State Management, Request Library
-- Entry Points: Router, Pages/Views, Layouts, API Client, Auth/Permission, Styles/Theme, Env Config
-- Structure: Directory Map (from 3a), Call Chain Map → Route-Component Map + Data Flow (from 3b), Conventions (from 3c)
-
-**Backend-type codebases** (type contains "后端" or "服务") additionally fill:
-- Stack: Database Access, API Style
-- Entry Points: Routes/Controllers, Middleware/Filters, Auth/Permission, Env Config, API Docs
-- Structure: Directory Map (from 3a), Call Chain Map → API Modules + Scheduled Jobs + External Integrations (from 3b), Conventions (from 3c)
-
-**Other types**: use the user-provided type to decide which sections to include. Prefer fewer sections with higher confidence over guessing.
-
-Rules:
-- Only write what was observed during scan. Do not invent paths or conventions.
-- If a section's data was not found during scan, write `待确认` for required fields or omit optional fields.
-- The `## Requirement-Relevant Areas` section is left with a placeholder `{{requirement_areas}}` — it will be filled by downstream skills as features are mapped to this codebase.
-- The `## Rule Sources` section points to `.planning/rules/INDEX.md` and lists only rule files found within this codebase's root (e.g., `.cursorrules`).
-
-## Step 6.5 — Code Index Refresh (REQUIRED)
-
-本步骤**必须**执行。仅当用户传入 `--fast` / `--skip-code-index` 时允许跳过，否则初始化视为未完成。已有输出、刷新场景或执行耗时均不构成豁免。
-
-In full mode, invoke `workflow-code-index` and run its deterministic implementation:
+Use a fixed `snapshotId` throughout one reasoning chain:
 
 ```text
-devflow_code_index(action="scan")
-devflow_code_index(action="validate")
-devflow_code_index(action="audit")
+devflow_project_context(action="query", snapshotId="<snapshot>", kind="api", limit=100)
+devflow_project_context(action="diff", fromSnapshotId="<old>", toSnapshotId="<new>")
+devflow_project_context(action="run-status", runId="<run>")
 ```
 
-All three commands must succeed. Do not treat pre-existing files as execution evidence. Step 10 verifies that these outputs were modified after `run_started_at`:
-
-- `.planning/code-index/index.sqlite`
-- `.planning/code-index/files.jsonl`
-- `.planning/code-index/symbols.jsonl`
-- `.planning/code-index/relations.jsonl`
-- `.planning/code-index/AUDIT.md`
-
-In fast mode, do not run the commands. Set `code_index_status` to `skipped`, record the explicit flag as `code_index_skip_reason`, and write the same current-run marker to `STATE.md`, `PROJECT.md`, navigation INDEX, and rules INDEX.
-
-After full-mode commands succeed, set `code_index_status` to `complete`, use skip reason `none`, and update the same marker in PROJECT and navigation INDEX. Rules INDEX and STATE receive it when generated in Steps 8 and 9.
+Follow `nextCursor` until null. A diff with incompatible scan configurations is `comparable=false`; do not interpret it as deletion. Refresh uses `scan` with a new request ID. Repeating one request ID with different input is an error.
 
-Do not require users to manually run Python when they invoked this skill.
-
-## Step 6.5a — Static Runtime Context Snapshot (REQUIRED)
-
-After Step 6.5, collect the separate P1 static-context snapshot:
+Cancellation and expired-lease recovery are explicit:
 
 ```text
-devflow_static_runtime_context(action="collect")
-devflow_static_runtime_context(action="inspect")
+devflow_project_context(action="cancel", runId="<run>")
+devflow_project_context(action="recover", runId="<run>")
 ```
 
-Run this in both full and fast modes. It reads the committed Git tree and may therefore collect manifest declarations even when code-index was intentionally skipped. Verify that the returned pointer exists and record the snapshot revision in the initialization summary.
-
-Do not describe this snapshot as production topology, resource health, capacity, or a list of deployed services. Its P1 scope is repository declarations and explicitly supported platform manifests only; unsupported resource bindings, integrations, and jobs remain `unknown` until a later collector can prove them.
-
-If the repository has no readable Git commit, retain the generated snapshot with incomplete coverage and record the limitation. Do not invent a working-tree baseline or silently skip the collection.
+A cancelled run never auto-publishes. A recovered stale worker receives a new lease and the old lease cannot write.
 
-## Step 6.6 — Design Rule Package (Conditional Required)
+## Authority, backup, and rollback
 
-This step belongs to project initialization, not feature design. It runs **after the code index is available** and before the context-spec package is finalized.
-
-1. Determine applicability from the Step 1 codebase types and Step 3 scan evidence:
-   - If at least one local/scannable codebase is frontend-type, this step is required.
-   - If no frontend-type codebase exists, do not install UI recommendation assets; record `design_rule_pack.status: not_applicable` and reason `no_frontend_codebase` in the run manifest.
-2. For an applicable project, run the design-rule installer without overwriting project-local decisions or the project-context-owned index:
+Shadow import does not alter current pointers. Switch only after the database snapshot, index reference, and document conflicts have been reviewed:
 
 ```text
-devflow_design_rule(args=["--without-index"])
-```
-
-3. Verify these installed assets exist:
-   - `.context/spec/design/tokens/project-tokens.md`
-   - `.context/spec/design/recommendations/accessibility.md`
-   - `.context/spec/design/recommendations/component-library.md`
-   - `.context/spec/design/tools/ui-ux-pro-max/SKILL.md`
-4. Record `design_rule_pack.status: installed`, source `skill://workflow-design-rule-pack/assets/design/`, and the verified asset paths in `.planning/project-context-run.json`.
-5. Never use `--overwrite` during ordinary initialization. Existing confirmed project tokens and intentional local overrides take precedence. If an existing shared recommendation must be refreshed, require explicit user authorization and record it as a separate maintenance action.
-
-`--fast` only skips code-index generation. It does not skip this step for frontend projects.
-
-## Step 7 — Generate Context Spec Package
-
-Create `.context/spec/` after navigation files exist. Context specs are generated rule documents, not source-code indexes.
-
-### 7.1 Generate stack specs
-
-Use all Step 3d stack profiles, group by `stack_key`, and generate one `.context/spec/stacks/{stack_key}.md` per unique stack profile.
-
-Rules:
-- Deduplicate by `stack_key`, not by framework name alone.
-- If two codebases share the same framework but differ in major framework version or key libraries, generate separate stack specs.
-- Stack specs contain technology-stack guidance only. Do not include one codebase's local directory names, local naming habits, or route/module names as stack rules.
-- Stack specs must fill `## Per-Layer Rules` with stack-level guidance for every listed layer. Use `NOT_APPLICABLE` for layers that do not apply to the stack.
-- Each stack spec must include version metadata: generation date, source manifests, key dependency versions, dependency fingerprint, and regeneration triggers.
-
-### 7.2 Generate codebase specs
-
-For EACH frontend-type codebase, load `assets/codebase-frontend-spec-template.md` and write `.context/spec/frontend/{name}.md`.
-
-For EACH backend/service-type codebase, load `assets/codebase-backend-spec-template.md` and write `.context/spec/backend/{name}.md`.
-
-Codebase specs must:
-- Link to the matching stack spec by `stack_key`.
-- Separate `显式规则`, `代码推断`, and `待确认`.
-- Use navigation facts and actual scanned conventions; do not invent rules or promote inconsistent legacy code to a hard rule.
-- Include version metadata and regeneration triggers.
-
-### 7.3 Generate spec indexes
-
-Load `assets/context-spec-index-template.md` and write `.context/spec/index.md`.
-
-Load `assets/context-domain-index-template.md` and write:
-- `.context/spec/frontend/index.md`
-- `.context/spec/backend/index.md`
-- `.context/spec/design/index.md`
-
-For `.context/spec/design/index.md`, project-context is the only writer. When `design_rule_pack.status` is `installed`, add a `## Shared Design Rule Package` section that links to `tokens/`, `recommendations/`, and `tools/ui-ux-pro-max/`, preserves the priority order (confirmed project facts before recommendations), and identifies the pack as recommendations rather than project facts. When it is `not_applicable`, retain the explicit no-frontend reason.
-
-The root spec index must list:
-- Every stack spec with its `stack_key`.
-- Every codebase spec with codebase name, type, navigation file, and stack spec.
-- Read order for downstream skills:
-  1. `.planning/rules/INDEX.md`
-  2. `.context/spec/index.md`
-  3. matching `.context/spec/stacks/{stack_key}.md`
-  4. matching `.context/spec/frontend|backend/{codebase}.md`
-  5. matching `.context/spec/{domain}/index.md` and applicable depth specs
-  6. `.planning/navigation/{codebase}.md`
-  7. `.planning/code-index/` machine symbols/relations when present and source-level relation facts are needed
-  8. actual source files
-
-Each frontend/backend domain index must:
-
-- List every codebase-level spec in that domain.
-- Include a depth-spec registry row for every candidate topic and codebase.
-- Emit one exact machine marker per registry row:
-  - Present: `<!-- depth_spec: codebase={name}; domain={domain}; topic={topic}; status=present; path={output_path} -->`
-  - Not applicable: `<!-- depth_spec: codebase={name}; domain={domain}; topic={topic}; status=not_applicable; path=none -->`
-- Contain no marker from an earlier run that is absent from the current run manifest.
-
-### 7.4 Generate depth spec files (REQUIRED)
-
-本步骤**必须**执行。depth spec 是机器推导字段，刷新时必须与导航文件同步重新生成，禁止因为"已有旧文件"而跳过。
-
-Depth specs are topic-specific expansions of the codebase spec. Determine the topic list dynamically from navigation scan data, then load and fill the matching template from `assets/spec-templates/{codebase-type}/`. Do not iterate a hardcoded file list.
-
-**Backend topic discovery** (from backend-type codebase navigation):
-
-| Topic | Match rule | Conditional |
-|-------|-----------|-------------|
-| `service` | directory matching `**/service*/` or `**/svc/` | always when present |
-| `router` | directory matching `**/router*/`, `**/route*/`, `**/handler*/`, `**/controller*/`, `**/web/`, or route registration files | always when present |
-| `schema` | directory matching `**/schema*/`, `**/dto*/`, `**/vo*/`, `**/request*/`, `**/response*/`, or request/response type files | always when present |
-| `model` | directory matching `**/model*/`, `**/entity*/`, `**/domain/`, or ORM/entity files | always when present |
-| `repository` | directory matching `**/repository*/`, `**/repo*/`, `**/dao/`, or persistence adapter files | always when present |
-| `engine` | directory matching `**/engine*/`, `**/client*/`, `**/integration*/`, `**/external*/`, or outbound integration files | always when present |
-| `scheduler` | files or directories matching `**/cron*`, `**/job*`, `**/task*`, `**/scheduler*`, or framework scheduler annotations/registrations | presence of cron/job files |
-| `locator` | locator module detected | presence of locator-specific code |
-| `testing` | directory matching `**/test*/`, `**/tests/`, or files matching `**/*_test.*`, `**/test_*`, `**/*.spec.*` | always when present |
-| `directory-structure` | always | always |
-| `errors` | always | always — derived from HTTP exception and error mapping patterns |
-
-**Frontend topic discovery** (from frontend-type codebase navigation):
-
-| Navigation signal | Depth spec topic | Conditional |
-|---|---|---|
-| Router config, `app/`, `pages/`, `src/app/`, `src/pages/`, or framework file-based routes detected | `routing` | always when present |
-| API client dir/file exists (`**/api*/`, `**/client*/`, `**/request*`, `**/services*`) | `api-client` | always when present |
-| State management (store/redux/zustand/pinia/vuex/context/composable state) detected | `state` | always when present |
-| Components directory exists (`**/components/`, `**/ui/`, `**/widgets/`) | `components` | always when present |
-| Form patterns detected | `forms` | always when present |
-| Domain-specific editor detected | `case-editor` | presence of editor modules |
-| Test dir/file exists (`**/test*/`, `**/*.test.*`, `**/*.spec.*`) | `testing` | always when present |
-| always | `directory-structure` | always |
-
-**Generation rules:**
-
-Build `candidate_topics` and `expected_topics` independently for every local/scannable codebase:
-
-1. Enumerate `candidate_topics` from the current filenames in `assets/spec-templates/{backend|frontend}/`; do not copy a fixed count or list into a completion gate.
-2. Apply the discovery table to the navigation evidence. The matching subset becomes `expected_topics`.
-3. Record both sets in `.planning/project-context-run.json.topic_inventory`.
-
-The runtime inventory is the single source for generation and validation. A candidate topic must appear exactly once as either generated or `NOT_APPLICABLE`.
-
-Choose output paths without collisions:
-
-- When a domain has one codebase: `.context/spec/{domain}/{topic}.md`
-- When a domain has multiple codebases: `.context/spec/{domain}/{codebase}/{topic}.md`
-
-For each expected topic:
-
-1. Record the codebase's absolute or project-relative root as `codebase_root`.
-2. Collect every source file actually used to derive the topic as `source_paths` relative to that codebase root. Do not use directories or generated spec files as substitutes.
-3. Compute `source_fingerprint` with the same algorithm as `scripts/validate_initialization.py`: sort unique paths, hash each file, then hash the sequence of `relative_path + NUL + file_sha256 + newline`.
-4. Load `assets/spec-templates/{backend|frontend}/{topic}.md`, fill placeholders from navigation facts and stack template, and write the selected output path.
-5. Add one matching entry to `.planning/project-context-run.json.depth_specs`.
-6. Record every undiscovered candidate topic in `not_applicable_topics` and in the matching domain spec index.
-7. Emit the exact matching `depth_spec` machine marker in the domain index.
-
-Each depth spec uses the same structure: Generation Metadata, Scope, Source Summary (Type+Confidence), Stack-Specific Conventions, Observed Patterns, Rules (Strength+Source+Notes), Current Project Shape, Not Applicable, Pending Confirmation.
-
-Placeholder filling rules:
-- `{{run_id}}`: the current invocation's immutable run ID.
-- `{{generated_at}}`: ISO-8601 UTC time when this file was regenerated.
-- `{{source_fingerprint}}`: fingerprint computed from this manifest entry's `source_paths`.
-- `{{scope_path}}`: derived from codebase root + navigation scan.
-- `{{source_summary}}`: rows from navigation scan (`代码推断 | OBSERVED | high`), stack template (`SHOULD | medium`), and rule files (`MUST | high`).
-- `{{stack_layer_rules}}`: extract the matching subsection from `.context/spec/stacks/{stack_key}.md` → `## Per-Layer Rules`. If the subsection is `NOT_APPLICABLE`, record that in this field and in `{{not_applicable}}`.
-- `{{observed_rules}}`: rows or bullets from navigation facts, call-chain tracing, codebase conventions, explicit rule files, and lessons. Do not mix in generic stack rules here.
-- `{{rules_table}}`: merged rows from stack layer rules, observed project conventions, explicit rule files, and lessons. Each row is `\| {{rule}} | {{strength}} | {{source}} | {{notes}} |`.
-- `{{current_shape}}` / `{{directory_tree}}`: from navigation directory map and call chain map.
-- `{{not_applicable}}`: layers and patterns observed to be absent.
-- `{{pending}}`: items not yet confirmed.
-
-Topics not discovered are skipped. Record them in the domain index and run manifest as `NOT_APPLICABLE`. A skipped topic must not be added to `depth_specs`.
-
-If a topic is discovered but the matching template file is missing, do not silently skip it. Record a `PENDING_TEMPLATE` blocker in `.planning/STATE.md` front matter and in the matching domain spec index:
-
-```yaml
-blockers:
-  - type: PENDING_TEMPLATE
-    codebase: {{name}}
-    topic: {{topic}}
-    reason: found {{matched_path}} but no template in assets/spec-templates/{{backend_or_frontend}}/{{topic}}.md
-    impact: depth spec not generated for this layer
+devflow_project_context(action="authority")
+devflow_project_context(action="switch-authority", authority="database", expectedRevision=1)
 ```
 
-For the domain spec index, include the same topic, matched path, missing template path, and impact under `## Pending Confirmation`.
-
-Do not mark initialization fully complete while `PENDING_TEMPLATE` blockers exist.
-
-**Completion gate:**
-
-- Every frontend/backend codebase has its codebase-level spec.
-- Every present domain has its domain index.
-- Every domain index contains the current run ID and exactly the machine markers represented by the run manifest.
-- Every `(codebase, domain, topic)` in `expected_topics` has exactly one run-manifest entry and one output file.
-- Every undiscovered candidate topic is recorded as `NOT_APPLICABLE`, not generated to satisfy a fixed count.
-- No two manifest entries share one output path.
-- Every depth spec contains the current `run_id` and matching `source_fingerprint`.
-
-Any mismatch means Step 7.4 is incomplete.
-
-## Step 8 — Generate Rule Package Files
+Authority changes use compare-and-swap revisions. Rollback from database to legacy requires a verified compatibility export. Backup includes the database, manifest, and referenced immutable content. Restore validates project identity, schema, foreign keys, database hash, and every referenced content hash before replacement.
 
-Create the project rule package that downstream skills (`workflow-frontend-tech-spec`, `workflow-backend-tech-spec`) check first in their discovery order. This step consolidates information already collected during structure scan and generated context specs — it does not invent new rules.
+## Completion gate
 
-### 8.1 Create `.planning/rules/` directory
-
-```bash
-mkdir -p .planning/rules
-```
-
-### 8.2 Generate `.planning/execution-contract.md`
-
-Load `assets/execution-contract-template.md` and fill from scan results:
-
-- **Backend layer models**: from each backend-type codebase navigation file's "Layer Conventions" table. Map handler/service/repository/DAO directories and describe the dependency direction. One subsection per backend codebase.
-- **Conversion rules**: from `.cursorrules` (if present) or codebase navigation Notes. Capture domain↔vo↔model conversion rules verbatim.
-- **Interface rules**: from `.cursorrules` or code scan. E.g., "handler implements handler interface with RegisterRoutes method".
-- **Frontend component hierarchies**: from each frontend-type codebase navigation file's "Component Conventions" table. Map pages→page components→common components→layout→hooks. One subsection per frontend codebase.
-- **TDD Strategy**: already embedded in template default. Fill from codebase conventions when the project has explicit TDD rules. Keep the template default otherwise.
-- **Code Generation**: `待确认` unless codegen commands (wire, protobuf, swagger, etc.) were found during scan. If found, list each command with its source and run condition.
-- **Verification Gates**: already embedded in template default. Fill additional project-specific verification rules from codebase conventions when present. Keep the template default otherwise.
-
-Rules:
-- Only write what was observed during scan. Do not invent layer rules or component conventions.
-- If `.cursorrules` or `AGENTS.md` / `CLAUDE.md` contain explicit conventions, quote or summarize them in the relevant section.
-- Mark unobserved sections as `待确认`, not with guessed defaults.
-
-### 8.3 Generate `.planning/toolchain.md`
-
-Load `assets/toolchain-template.md` and fill from the "Commands" tables in all codebase navigation files:
-
-- Consolidate commands from each codebase, grouped by codebase name.
-- If database migration commands were found during scan, add them.
-- If code generation commands (wire, protobuf, swagger, etc.) were found, add them.
-- If a command is `待确认` in the navigation files, keep it as `待确认` here.
-
-### 8.4 Generate `.planning/rules/INDEX.md`
-
-Load `assets/rules-index-template.md` and fill status for every rule source:
-
-- Files created in Step 8 (`execution-contract.md`, `toolchain.md`) → status `present`.
-- Files created in Step 7 (`.context/spec/index.md`, stack specs, frontend/backend/design indexes, codebase specs) → status `present`.
-- Files found during Step 3 scan (`.cursorrules`, `AGENTS.md`, existing `.context/spec/`, etc.) → status `present` with path.
-- Files not found → status `missing`.
-- Files that don't apply (e.g., frontend rules for backend-only projects) → status `不适用`.
-
-This file is the first thing downstream skills read. It must accurately reflect what exists after initialization.
-
-## Step 9 — Generate STATE.md
-
-Load `assets/state-template.md` and create `.planning/STATE.md` with:
-
-- Initialization date
-- Current step
-- Completed steps
-- Pending steps
-- Each codebase: name, type, path, scan status, navigation file path, stack_key, and generated spec path
-- Whether `.planning/PROJECT.md` exists
-- Whether `.planning/navigation/` exists
-- Whether `.context/spec/` exists and each required spec file is complete
-- Whether each codebase navigation is complete
-- Whether `.planning/rules/INDEX.md`, `.planning/execution-contract.md`, and `.planning/toolchain.md` exist
-- Current `run_id`, `run_started_at`, and `code_index_status`
-- Design rule pack status and reason
-- Last scan timestamp
-- Blockers
-- Known missing information
-- Recommended next step, usually `workflow-requirement-baseline` after the user provides a requirement
-
-## Step 9.5 — Finalize Run Manifest
-
-Load `assets/run-manifest-template.json` and write `.planning/project-context-run.json`.
-
-Requirements:
-
-- `run_id` and `started_at` exactly match the values captured before Step 1.
-- `mode` is `full` or `fast`.
-- `code_index_status` is `complete` in full mode and `skipped` in fast mode.
-- `code_index_skip_reason` is `none` in full mode or the explicit skip flag in fast mode.
-- `design_rule_pack` has status `installed` with its verified assets for frontend projects, or `not_applicable` with a reason for projects without frontend codebases.
-- Every local/scannable frontend/backend codebase has one `topic_inventory` entry. Its `candidate_topics` come from current template filenames and its `discovered_topics` come from the Step 7.4 evidence match.
-- Every expected depth topic has one entry with its codebase root, actual output path, complete codebase-relative `source_paths`, and computed `source_fingerprint`.
-- Every undiscovered candidate topic is listed under `not_applicable_topics`.
-- JSON placeholders and example rows are fully removed.
-
-## Step 10 — Review Gate
-
-This is the final step. Before finishing, review generated files against `references/navigation-guide.md`, then run the deterministic completion validator.
-
-Check:
-
-- All codebase locations from Step 1 are recorded in INDEX.md Codebase Registry.
-- Each codebase has a navigation file at `.planning/navigation/{name}.md`.
-- Frameworks are recorded or marked `待确认` for each codebase.
-- Entry points and key directories are recorded or marked `待确认` for each codebase.
-- Each codebase has a Directory Map (3a gate: all top-level/second-level directories listed).
-- Each codebase has a Call Chain Map (3b gate: all handlers/routes traced).
-- Each codebase has Conventions (3c gate: at minimum layer order or component hierarchy recorded).
-- Each local/scannable codebase has a Stack Profile (3d gate: stack_key, manifest path, and dependency fingerprint recorded).
-- Every detected stack profile has `.context/spec/stacks/{stack_key}.md`.
-- Every frontend-type codebase has `.context/spec/frontend/{name}.md`.
-- Every backend/service-type codebase has `.context/spec/backend/{name}.md`.
-- Every depth topic discovered in Step 7.4 has exactly one output and manifest entry.
-- Every topic not discovered in Step 7.4 is recorded as `NOT_APPLICABLE`; no fixed topic count is imposed.
-- Every frontend/backend domain index has exactly the current manifest's depth-spec registry markers and no stale markers.
-- `.context/spec/index.md` lists every stack spec and codebase spec mapping.
-- All generated context specs include generation metadata and regeneration triggers; depth specs include the current run ID and source fingerprint.
-- Frontend-type codebases have Route-Component Map and Data Flow tables.
-- Backend-type codebases have API Modules, Scheduled Jobs, and External Integrations tables.
-- Commands are recorded or marked `待确认` for each codebase.
-- `.planning/execution-contract.md` exists and contains layer order and component hierarchy from scan results, not invented defaults.
-- `.planning/toolchain.md` exists and consolidates commands from all codebase navigation files.
-- `.planning/rules/INDEX.md` exists and accurately reflects generated `.context/spec/` files as present.
-- Project rule package locations are recorded when present, including `.context/spec/`, `.context/workflow/`, and lessons.
-- History model locations are recorded, and outbound-call style `features/` history is labeled as optional legacy rather than the default source.
-- `.planning/PROJECT.md` links to `.planning/navigation/INDEX.md`.
-- `.planning/navigation/INDEX.md` Codebase Registry links to every codebase navigation file.
-- `.planning/navigation/INDEX.md` includes downstream read contract.
-- `.planning/navigation/INDEX.md` and `.context/spec/index.md` describe `.planning/code-index/` as the machine fact layer before source reads, unless fast mode skipped generation.
-- Every frontend project has the design rule assets from Step 6.6, while `.context/spec/design/index.md` remains generated by project-context rather than overwritten by the installer.
-- Future output locations include `.planning/features/{功能名}/功能点梳理.md`.
-- No requirements or roadmap were generated without explicit user request.
-- `STATE.md` includes completion statuses and next action for each codebase.
-- Generated files include an initialization quality summary.
-
-Run **only after every manifest-declared output has been written and all four
-current-run status markers have been added**. This is a final gate, not a
-planning or progress check. Do not call it while the preceding steps are still
-describing or planning file updates.
-
-Run:
+Run the database validator with identifiers returned by the scan:
 
 ```text
-devflow_skill_script(script="project-context-validate", args=["--root", ".", "--manifest", ".planning/project-context-run.json"])
+devflow_skill_script(script="project-context-db-validate", args=["--database", "<control.db>", "--project-id", "<project-id>", "--workspace-id", "<workspace-id>", "--run-id", "<run-id>"])
 ```
 
-The validator checks current-run markers, full-mode code-index freshness, fast-mode skip evidence, template-derived topic inventory partitioning, dynamic depth-spec outputs, domain-index registry markers, source fingerprints, duplicate identities, and output-path collisions.
-
-Fix every reported gap and rerun the validator. If the command does not pass, initialization is incomplete and the final response must report the blocker instead of claiming success.
-
-Quality status rules:
-
-- `complete`: required fields are known and commands are identified.
-- `partial`: project is local and scannable, but some required fields are `待确认`.
-- `pending`: project location is remote/unavailable or scan could not run.
-- `not_applicable`: this codebase type does not support this field (e.g., component conventions for a backend service).
-
-## Downstream Read Contract
-
-This skill writes the contract and the initial rule package. Other skills consume them:
+Completion requires a stable immutable input, matching context snapshot, accounted required categories, evidence for observed facts, a registered immutable index in full mode, revision-safe pointer publication, and separate document statuses. Workflow `STATE` and other non-initialization authorities must remain unchanged.
 
-- Requirement discussion should read `.planning/PROJECT.md`, `.planning/navigation/INDEX.md`, and `.planning/rules/INDEX.md`.
-- Feature breakdown should read `.planning/PROJECT.md`, `.planning/navigation/INDEX.md`, and relevant codebase navigation files as needed.
-- Test guide generation should read `.planning/PROJECT.md`, `.planning/navigation/INDEX.md`, and `.planning/rules/INDEX.md`.
-- Frontend technical planning should read `.planning/rules/INDEX.md` → `.context/spec/index.md` → matching `.context/spec/stacks/{stack_key}.md` → matching `.context/spec/frontend/{codebase}.md` → `.context/spec/frontend/index.md` and applicable depth specs → `.planning/navigation/{codebase}.md` → `.planning/code-index/` when relation facts are needed → actual source files.
-- Backend technical planning should read `.planning/rules/INDEX.md` → `.context/spec/index.md` → matching `.context/spec/stacks/{stack_key}.md` → matching `.context/spec/backend/{codebase}.md` → `.context/spec/backend/index.md` and applicable depth specs → `.planning/navigation/{codebase}.md` → `.planning/code-index/` when relation facts are needed → actual source files.
-- Change-list generation should use `.planning/navigation/INDEX.md` for output locations and project conventions, and use discovered `.context/spec/` + `.planning/rules/` sources for task-level gates.
+Report partial, unsupported, skipped, failed, and unknown coverage honestly. Initialization success does not mean tests passed, services ran, designs were approved, or requirements were delivered.