[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M786ATFEF761FKKYG75EBQC9":3,"skill-same:01M786ATFEF761FKKYG75EBQC9":59},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":30,"commitSha":31,"skillDirectory":32,"forksCount":14,"repositoryHtmlUrl":33,"repositoryHomepageUrl":6,"ownerHtmlUrl":34,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":35,"install":36,"resources":48},"01M786ATFEF761FKKYG75EBQC9","sp-deep-research",null,"Use when a planning-ready spec still has feasibility risk and needs coordinated research, evidence packets, or disposable demo spikes before implementation planning.","chenziyang110\u002Flaunchdeck","chenziyang110","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F43693913?v=4","01M7863EBWK1D0P6A29YGEMAS4","Robin11","01M7863ECM1VB6RXDMHTW90D2T",0,"MIT","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsp-deep-research\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: \"sp-deep-research\"\ndescription: \"Use when a planning-ready spec still has feasibility risk and needs coordinated research, evidence packets, or disposable demo spikes before implementation planning.\"\nargument-hint: \"Describe the feasibility question, research tracks, or demo proof needed before planning handoff\"\ncompatibility: \"Requires spec-kit project structure with .specify\u002F directory\"\nmetadata:\n  author: \"github-spec-kit\"\n  source: \"templates\u002Fcommands\u002Fdeep-research.md\"\nuser-invocable: true\n---\n## Invocation Syntax\n\n- In this integration, invoke workflow skills with `\u002Fsp-plan`-style syntax.\n- References such as `\u002Fsp.plan`, `\u002Fsp.tasks`, or `next_command: \u002Fsp.plan` are canonical workflow-state identifiers and handoff values.\n- Preserve those canonical state tokens exactly in artifacts and workflow state; do not rewrite them to this integration's invocation syntax.\n\n\n\n## Workflow Contract Summary\n\n- **When to use**: The current spec package exists, but one or more capabilities do not yet have a credible implementation chain.\n- **Primary objective**: Coordinate focused research and isolated prototype evidence, synthesize implementation-chain decisions, and produce a planning handoff before \u002Fsp-plan.\n- **Primary outputs**: `FEATURE_DIR\u002Fdeep-research.md` with `Planning Handoff`, optional `FEATURE_DIR\u002Fresearch-spikes\u002F`, updated `alignment.md`, `context.md`, `references.md`, and `workflow-state.md`.\n- **Default handoff**: \u002Fsp-plan when feasibility is proven or explicitly accepted; otherwise \u002Fsp-clarify for requirement gaps or stop with blocked research risks.\n- **Execution note**: This summary is routing metadata only. Follow the full contract below end-to-end rather than inferring behavior from the description alone.\n\n## Blocked Exit Contract\n\nIf blocked after safe recovery, read and follow\n`.specify\u002Ftemplates\u002Fworkflow-blocker-template.md` and its JSON schema. Never\nreturn only an error or “ask a human”; preserve state and keep agent-capable\nrepair agent-owned. Set `human_action_required: true` only for authority,\ncredentials, protected systems, human decisions\u002Freviews, or physical access.\nTailor steps, expected results, failure paths, evidence, and resume action to\nCI, visual review, or product decisions. Never claim completion.\n\n## User Input\n\n```text\n$ARGUMENTS\n```\n\nYou **MUST** consider the user input before proceeding (if not empty).\n\n## Objective\n\nProduce a planning-ready research packet before implementation planning starts:\nprove or retire planning-critical feasibility questions, synthesize external and\nrepository evidence, validate uncertain links with disposable demo spikes when\nneeded, and hand `\u002Fsp.plan` the constraints and recommended implementation\ndirection it must preserve.\n\n## Context\n\n- Primary inputs: the current spec package, unresolved feasibility risks,\n  external references, repository evidence, research-agent findings, and any\n  disposable prototype evidence created in this command.\n- The active working set is `spec.md`, `alignment.md`, `context.md`,\n  `references.md`, `deep-research.md`, `research-spikes\u002F`, and\n  `workflow-state.md` inside the current `FEATURE_DIR`.\n- This command is research-only. It is not permission to implement production\n  behavior.\n\n## Process\n\n- Decide whether a feasibility and research handoff gate is actually needed.\n- Decompose unknown implementation chains by capability and independent\n  research track.\n- Dispatch subagents when independent research tracks can run in parallel and\n  produce evidence packets without conflicting writes.\n- Research external APIs, libraries, algorithms, platform constraints, and\n  repository patterns only where those facts change planning.\n- Build the smallest disposable demo or spike when research alone cannot prove\n  the chain.\n- Synthesize research-agent findings and spike results into planning decisions,\n  rejected options, risks, and a concrete `\u002Fsp.plan` handoff.\n- Run reverse coverage validation before handoff: every CAP → PH → Evidence chain must close.\n- Run readiness refusal checks; refuse handoff with a gap report when checks fail.\n- Run the Planning Handoff Readiness Checklist; do not recommend `\u002Fsp.plan` until all items pass.\n\n## Output Contract\n\n- Write or update `deep-research.md`.\n- Optionally write isolated scratch assets under `research-spikes\u002F`.\n- Update `alignment.md`, `context.md`, `references.md`, and `workflow-state.md`\n  when feasibility evidence changes planning readiness.\n- If this gate is not needed, still write a lightweight `deep-research.md`\n  with `**Status**: Not needed`, `Feasibility Decision`, `Planning Handoff`,\n  and `Next Command`; do not invent `CAP\u002FTRK\u002FEVD\u002FPH` IDs for already-proven\n  work.\n- Include a `Planning Handoff` section that `\u002Fsp.plan` can consume directly for\n  recommended approach, module boundaries, API\u002Flibrary choices, demo artifacts,\n  constraints, rejected options, and residual risks.\n- Use stable traceability IDs (`CAP-###`, `TRK-###`, `EVD-###`, `SPK-###`,\n  `PH-###`) plus an evidence quality rubric so `\u002Fsp.plan` can cite exactly which\n  research finding or spike supports each design decision.\n- Use `.specify\u002Ftemplates\u002Fexamples\u002Fdeep-research\u002F` as the output-shape\n  reference when available: `not-needed.md`, `docs-only-evidence.md`, and\n  `spike-required.md`.\n- Report which capabilities are proven, constrained, blocked, or no longer worth\n  planning.\n- Persist accepted evidence packets as `FEATURE_DIR\u002Fresearch-evidence\u002F\u003CEVD-###>.json`.\n\n## Guardrails\n\n- Do not edit production source files, tests, migrations, release config, or\n  implementation artifacts from `sp-deep-research`.\n- Keep demos disposable and isolated under `FEATURE_DIR\u002Fresearch-spikes\u002F` unless\n  the user explicitly asks to preserve a prototype elsewhere in a later\n  implementation workflow.\n- Skip this command when the change is a minor adjustment to an existing,\n  already-proven capability.\n- Do not let research subagents edit production files; they must either\n  return evidence packets or write only to their assigned disposable spike\n  directory.\n- A research pass without runnable evidence (spike result or repo path trace) is a failed pass.\n- Coordinator-only execution without subagent dispatch justification and recorded `subagent-blocked` reason is a failed pass.\n- Feasibility claims based only on documentation citations without live repository path reads are not sufficient for planning.\n- Subagent evidence packets without `paths_read` must be rejected; do not accept or synthesize them.\n- A structural-only refresh (reformatting findings without new evidence) is a failed pass.\n- Treat `context.md` Locked Decisions as immutable constraints during research.\n  Do not research alternatives that contradict a locked decision unless the\n  research explicitly proves the locked decision is infeasible, in which case\n  mark the affected CAP as `blocked` and escalate; do not silently replace the\n  locked decision.\n\n## Senior Consequence Analysis Gate\n\nRun this gate whenever the request, artifact set, defect, or planned change can affect lifecycle operations, running objects, concurrent work, destructive behavior, shared state, downstream consumers, compatibility, security-sensitive behavior, or multiple plausible product behaviors.\n\nProject cognition first. Use the project cognition runtime to identify ownership, consumers, state surfaces, change-propagation facts, verification routes, conflicts, known unknowns, and coverage gaps. Senior consequence analysis second. Turn those facts into explicit product and implementation obligations instead of treating the graph as the decision-maker.\n\nProject cognition readiness provides routing advice. If readiness is `query_ready`, read top-level `minimal_live_reads` first, then use lane-level `first_pass_paths` reasons. If readiness is `review`, inspect the returned `minimal_live_reads` before continuing and treat `coverage_diagnostics` as confidence and closeout signals. If readiness is `needs_rebuild`, continue with live repository evidence and recommend `\u002Fsp-map-scan -> \u002Fsp-map-build` only for brownfield first\u002Fmissing\u002Funusable baseline, schema failure, schema v1 or old broad-schema rebuild-required readiness, zero active-generation `path_index` rows outside `greenfield_empty`, missing or invalid `alias_index`, `explicit_rebuild_requested`, or `baseline_identity_invalid`. If readiness is `blocked`, report the blocked state and continue with live repository evidence unless the user's actual request is to fix cognition runtime state. If readiness is `unsupported_runtime`, continue with live evidence and record that compass intake was unavailable. If `baseline_kind=greenfield_empty`, continue with workflow artifacts and live requirements; do not recommend map-scan -> map-build solely because the graph has no paths. Carry relevant project cognition facts, returned `minimal_live_reads`, inference notes, and coverage gaps into the workflow's artifacts or durable state, but back consequence claims with live code, tests, scripts, configuration, or authoritative docs. Mutation closeout is separate from entry routing: entry stale may continue, but that does not allow source\u002Fruntime mutation workflows to defer closeout. Workflow-owned mutation closeout is not an external map-maintenance handoff; after changing project-related files or behavior, the workflow must run inline project cognition update from its changed paths, affected surfaces, and verification evidence, with `project-cognition mark-dirty` only as fallback when inline update cannot complete. `sp-map-update` is for manual\u002Fexternal maintenance and follow-up repair; it is external map maintenance, not routine closeout for this workflow's own changes. In shared routing summaries, sp-map-update is for manual\u002Fexternal maintenance and ordinary existing-baseline gaps.\n\nRequired output when the gate triggers:\n\n- **Affected Object Map**: name each object, record, worker, queue, artifact, command, API, file surface, user-visible state, or downstream consumer that can be affected.\n- **State-Behavior Matrix**: describe behavior for each important lifecycle state, including created, queued, running, paused, failed, cancelled, completed, resumed, archived, missing, stale, or partially refreshed states when relevant.\n- **Dependency Impact Table**: map direct dependencies, indirect consumers, shared state, compatibility surfaces, validation routes, and adjacent workflows that can break if semantics change.\n- **Recovery And Validation Contract**: state rollback, retry, idempotency, cleanup, migration, observability, and validation evidence required before handoff or completion.\n- **Coverage Gaps**: list what project cognition or live evidence cannot prove, who must resolve each gap, the latest safe resolve phase, the stop-and-reopen condition, and the routing decision: current workflow may continue with an assumption, must ask the user, must route to clarification or deep research, or must request map maintenance.\n- **Consequence Obligations**: assign stable `CA-###` IDs to every obligation that must survive downstream handoff, task generation, worker packets, verification, or debug closeout. Each `CA-###` must include claim, affected objects, owner workflow, latest resolve phase, status, and stop-and-reopen condition.\n\nStand down only for docs-only wording changes, trivial isolated fixes, or local refactors that cannot affect lifecycle operations, running state, destructive operations, shared state, downstream consumers, compatibility, security, or multiple behavior choices. Record the no-trigger reason or stand-down reason in the workflow's durable artifact or closeout before skipping the required outputs.\n\nIf the gate triggers and the current workflow cannot preserve the required outputs, stop and route to the workflow that can. Do not mark ready, resolved, handoff-ready, planning-ready, or complete while triggered consequence obligations remain unresolved, unmapped, or unsupported by validation evidence.\n\n[AGENT] For project-cognition-backed semantic intake, routing, audit, resume, or final-claim gates, read `references\u002Fsemantic-work-contract.md`.\n\n## Detailed References\n\nRead [Reference index](references\u002FINDEX.md) before applying shared semantic contracts.\n\n- [semantic work contract](references\u002Fsemantic-work-contract.md)\n\n## Mandatory Subagent Execution\n\nAll substantive tasks in ordinary `sp-*` workflows default to and must use subagents.\n\nThe leader orchestrates: route, split tasks, prepare task contracts, dispatch subagents, wait for structured handoffs, integrate results, verify, and update state.\n\nBefore dispatch, every subagent lane needs a task contract with objective, authoritative inputs, allowed read\u002Fwrite scope, forbidden paths, acceptance checks, verification evidence, and structured handoff format.\n\nUse `execution_model: subagent-mandatory`.\nUse `dispatch_shape: one-subagent | parallel-subagents`.\nUse `execution_surface: native-subagents`.\n\n\n## Pre-Execution Checks\n\n**Check for extension hooks (before deep research)**:\n- Check if `.specify\u002Fextensions.yml` exists in the project root.\n- If it exists, read it and look for entries under the `hooks.before_deep_research` key.\n- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally.\n- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.\n- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:\n  - If the hook has no `condition` field, or it is null\u002Fempty, treat the hook as executable.\n  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation.\n- For each executable hook, output the following based on its `optional` flag:\n  - **Optional hook** (`optional: true`):\n    ```\n    ## Extension Hooks\n\n    **Optional Pre-Hook**: {extension}\n    Command: `\u002F{command}`\n    Description: {description}\n\n    Prompt: {prompt}\n    To execute: `\u002F{command}`\n    ```\n  - **Mandatory hook** (`optional: false`):\n    ```\n    ## Extension Hooks\n\n    **Automatic Pre-Hook**: {extension}\n    Executing: `\u002F{command}`\n    EXECUTE_COMMAND: {command}\n\n    Wait for the result of the hook command before proceeding to the Outline.\n    ```\n- If no hooks are registered or `.specify\u002Fextensions.yml` does not exist, skip silently.\n\n**Maintain workflow quality without hook choreography**:\n- Confirm project cognition freshness and valid workflow entry before deeper research begins.\n- Keep `workflow-state.md` current as the durable source of truth for phase, allowed artifact writes, next action, and exit criteria.\n- Verify the final `deep-research.md` and `workflow-state.md` outputs before handoff instead of relying on chat narration.\n- Update durable state before compaction-risk transitions, prototype-evidence synthesis handoffs, or any stop where resume will depend on more than the visible conversation.\n\n## Project Learning\n\nThe CLI is the only agent-facing Learning read surface:\n\n1. Run `uvx --from git+https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Fspec-kit-plus.git@4a631657f75460886dbd12ebe48b14fc11cfe0bf specify learning start --command \u003Cclassic-command-name> --format json` before deeper non-trivial work.\n2. Select summaries by applicability and triggers; use `uvx --from git+https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Fspec-kit-plus.git@4a631657f75460886dbd12ebe48b14fc11cfe0bf specify learning list --command \u003Cclassic-command-name> --format json` only to filter or page.\n3. Execute one matching card's `show_argv`. Do not parse Learning storage.\n\n`start`, `list`, and `show` are read-only. Current repository evidence,\n`.specify\u002Fmemory\u002Fconstitution.md`, and explicit user direction override stale or\ncandidate Learning.\n\nAt closeout, corrections, retries, route changes, recovery, false leads, hidden\ndependencies, validation\u002Ftooling\u002Fstate\u002Fcognition gaps, constraints, and near\nmisses are capture signals. Prefer `uvx --from git+https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Fspec-kit-plus.git@4a631657f75460886dbd12ebe48b14fc11cfe0bf specify learning capture-auto`\nfrom owning state; manual capture includes summary, problem, action, triggers,\nsuccess criteria, avoid items, exceptions, and evidence.\n\n- `fast`: skip unless the task escalates.\n- `accept`, `analyze`, `ask`, `auto`, `constitution`, `explain`,\n  `implement-teams`, `taskstoissues`, and `team`: consume-only; do not violate\n  their write boundaries to capture.\n- Other non-trivial workflows: consume before deeper work; capture reusable\n  signals at closeout or record a no-learning decision.\n\nThe `policy` returned by the CLI is authoritative when prompt wording drifts.\n\n## Workflow Phase Lock\n\n- [AGENT] Create or resume `WORKFLOW_STATE_FILE` before substantial research.\n- Read `.specify\u002Ftemplates\u002Fworkflow-state-template.md`.\n- If `WORKFLOW_STATE_FILE` already exists, read it first and preserve still-valid `next_action`, `exit_criteria`, and `next_command` details instead of relying on chat memory alone.\n- Treat `WORKFLOW_STATE_FILE` as the stage-state source of truth on resume after compaction for the current command, allowed artifact writes, forbidden actions, authoritative files, next action, and exit criteria.\n- Set or update the state for this run with at least:\n  - `active_command: sp-deep-research`\n  - `phase_mode: research-only`\n  - `allowed_artifact_writes: deep-research.md, research-spikes\u002F, alignment.md, context.md, references.md, workflow-state.md`\n  - `forbidden_actions: edit production source code, edit tests, fix build\u002Ftooling, implement behavior, commit prototype code as production`\n  - `authoritative_files: spec.md, alignment.md, context.md, references.md, deep-research.md`\n  - `track_exit_states`: per TRK-### exit state\n  - `evidence_packet_acceptance`: accepted and rejected packet lists with reasons\n  - `failed_readiness_checks`: list of check IDs that failed\n  - `open_gaps`: gap ID, description, severity, and linked CAP\u002FTRK IDs\n  - `entry_source`: `sp-specify` | `sp-clarify` (which command routed here)\n  - `research_mode`: `full-research` | `supplement-research`\n- Do not edit production code, production tests, migrations, release config, or implementation artifacts from `sp-deep-research`.\n- When resuming after compaction, re-read `WORKFLOW_STATE_FILE` before proceeding.\n\n## Multi-Agent Research Orchestration\n\n- [AGENT] Treat the current session as the research coordinator. The coordinator owns scope control, join points, conflict resolution, and the final `deep-research.md` synthesis.\n- [AGENT] Before delegating, split the feasibility problem into independent research tracks only when the tracks can run in parallel without sharing write targets. Good tracks include:\n  - repository implementation-pattern evidence\n  - external API\u002Flibrary\u002Fplatform feasibility\n  - data shape, migration, permission, performance, or integration constraints\n  - alternative approach comparison\n  - disposable demo\u002Fspike validation\n- [AGENT] Dispatch subagents when independent tracks can run in parallel and that materially improves evidence quality or speed. When the next coordinator decision is blocked on a single tightly coupled fact, either create one safe packetized evidence lane for that fact or stop for escalation\u002Frecovery with the blocker recorded.\n- [AGENT] Give each subagent one bounded track, one expected output shape, and one write scope. Research-only subagents should return evidence packets in their final response. Demo\u002Fspike subagents may write only under `FEATURE_DIR\u002Fresearch-spikes\u002F\u003Ctrack-slug>\u002F`.\n- [AGENT] Do not duplicate work across subagents. If two tracks overlap, assign one owner and ask the other to focus on a distinct risk or alternative.\n- [AGENT] Require every subagent to return an evidence packet with:\n  - `track`\n  - `question`\n  - `sources_or_repo_evidence`\n  - `finding`\n  - `confidence: high | medium | low`\n  - `planning_implications`\n  - `constraints_for_sp_plan`\n  - `rejected_options`\n  - `residual_risks`\n  - `spike_artifacts` when applicable\n- [AGENT] After each subagent returns, apply the evidence packet acceptance protocol:\n  - **ACCEPT** when: `paths_read` is non-empty, `finding` is specific and evidence-backed, core question is answered, and no production files were edited.\n  - **REJECT** when: `paths_read` is empty or missing, `finding` is empty or only speculative, core question is unanswered, or the subagent edited production source files.\n  - Record every acceptance and rejection in `workflow-state.md`.\n  - For rejected packets: retry once with clarified instructions. If the retry also fails, mark the track as `blocked`, record `subagent-blocked` with the rejection reason, and escalate.\n  - Do not silently ignore or synthesize rejected evidence packets.\n\n  ```markdown\n  ## Evidence Packet Acceptance\n\n  | Track | Subagent | Status | Reason if Rejected | Action |\n  |-------|----------|--------|--------------------|--------|\n  | TRK-001 | agent-1 | ACCEPTED | — | — |\n  | TRK-002 | agent-2 | REJECTED | No paths_read | Retry once |\n  | TRK-003 | agent-3 | REJECTED | Edited source file | BLOCKED, escalate |\n  ```\n- [AGENT] Join all subagent results before writing final conclusions. Resolve contradictions by preferring runnable spike evidence, current repository evidence, primary documentation, then secondary sources in that order. Mark conflicts that remain unresolved instead of hiding them.\n- [AGENT] The coordinator must convert subagent packets into `Research Agent Findings`, `Synthesis Decisions`, and `Planning Handoff`; do not paste raw subagent output as the final artifact.\n- [AGENT] After accepting a subagent evidence packet, persist it as\n  `FEATURE_DIR\u002Fresearch-evidence\u002F\u003CEVD-###>.json` with the full evidence packet\n  fields plus the evidence quality rubric. This enables:\n  - independent audit without re-parsing `deep-research.md`\n  - direct citation by `\u002Fsp.plan` via evidence ID\n  - safe context-compaction recovery\n- [AGENT] If subagent dispatch is unavailable or unsafe, record the decision as `subagent-blocked` with the concrete reason, preserve the decomposed tracks as blocked work, and stop for escalation or recovery instead of continuing as coordinator-only execution.\n\n## Traceability and Evidence Quality Contract\n\n- Assign stable IDs before running research so later planning can cite specific evidence instead of paraphrasing it:\n  - capability IDs: `CAP-001`, `CAP-002`, ...\n  - research track IDs: `TRK-001`, `TRK-002`, ...\n  - evidence IDs: `EVD-001`, `EVD-002`, ...\n  - spike IDs: `SPK-001`, `SPK-002`, ...\n  - Planning Handoff item IDs: `PH-001`, `PH-002`, ...\n- Use the IDs consistently across `Capability Feasibility Matrix`, `Research Agent Findings`, `Implementation Chain Evidence`, `Demo \u002F Spike Evidence`, `Synthesis Decisions`, and `Planning Handoff`.\n- Every handoff item must trace back to at least one evidence ID, spike ID, repository path, or source reference.\n- Grade each evidence item using this rubric:\n  - **Source tier**: `repo-evidence | runnable-spike | primary-docs | official-example | standard | secondary-source | inference`\n  - **Reproduced locally**: `yes | no | not applicable`\n  - **Recency**: [date, version, or `not time-sensitive`]\n  - **Confidence**: `high | medium | low`\n  - **Plan impact**: `blocking | constraining | informative`\n  - **Limitations**: [what the evidence does not prove]\n- Stop each research track when it reaches one of these exit states:\n  - `enough-to-plan`\n  - `constrained-but-plannable`\n  - `blocked`\n  - `not-viable`\n  - `user-decision-required`\n  - `stale-needs-revalidation` — prior evidence may no longer be valid due to dependency or platform changes\n- Do not continue researching a track once it has enough evidence to support a planning decision. Convert the result into a handoff item and move on.\n- For every spike, record the reproducibility contract:\n  - hypothesis\n  - setup\u002Fenv\n  - command\n  - expected result\n  - actual result\n  - cleanup note\n  - what this does not prove\n\n## Outline\n\n1. **Setup**: Run `.specify\u002Fscripts\u002Fpowershell\u002Fcheck-prerequisites.ps1 -Json -PathsOnly` from repo root once (`--json --paths-only` \u002F `-Json -PathsOnly`). Parse:\n   - If `FEATURE_DIR` is not already explicit, prefer `uvx --from git+https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Fspec-kit-plus.git@4a631657f75460886dbd12ebe48b14fc11cfe0bf specify lane resolve --command deep-research --ensure-worktree` before guessing from branch-only context.\n   - When lane resolution returns a materialized lane worktree, continue research from that isolated worktree context instead of assuming the leader workspace already matches the active feature lane.\n   - `FEATURE_DIR`\n   - `FEATURE_SPEC`\n   - optional downstream paths if returned\n   - If JSON parsing fails, abort and instruct the user to verify the feature branch environment.\n   - Set `ALIGNMENT_FILE` to `FEATURE_DIR\u002Falignment.md`.\n   - Set `CONTEXT_FILE` to `FEATURE_DIR\u002Fcontext.md`.\n   - Set `REFERENCES_FILE` to `FEATURE_DIR\u002Freferences.md`.\n   - Set `DEEP_RESEARCH_FILE` to `FEATURE_DIR\u002Fdeep-research.md`.\n   - Set `SPIKES_DIR` to `FEATURE_DIR\u002Fresearch-spikes`.\n   - Set `WORKFLOW_STATE_FILE` to `FEATURE_DIR\u002Fworkflow-state.md`.\n\n2. **Create or resume the workflow state**:\n   - Read `.specify\u002Ftemplates\u002Fworkflow-state-template.md`.\n   - If `WORKFLOW_STATE_FILE` already exists, read it first and preserve still-valid `next_action`, `exit_criteria`, and `next_command` details instead of relying on chat memory alone.\n   - Determine entry source:\n     - If the prior `active_command` in `workflow-state.md` was `sp-specify` →\n       `entry_source: sp-specify`, `research_mode: full-research`\n     - If the prior `active_command` was `sp-clarify` →\n       `entry_source: sp-clarify`, `research_mode: supplement-research`\n     - If undetermined → default to `full-research`\n   - In `supplement-research` mode, preserve existing evidence and only research\n     newly added or changed capabilities.\n   - Record entry source and research mode in `deep-research.md` Research\n     Orchestration section.\n   - Persist at least:\n     - `active_command: sp-deep-research`\n     - `phase_mode: research-only`\n     - `allowed_artifact_writes: deep-research.md, research-spikes\u002F, alignment.md, context.md, references.md, workflow-state.md`\n     - `forbidden_actions: edit production source code, edit tests, fix build\u002Ftooling, implement behavior, commit prototype code as production`\n     - `authoritative_files: spec.md, alignment.md, context.md, references.md, deep-research.md`\n\n3. **Load current spec package and repository context**:\n   - `FEATURE_SPEC`\n   - `FEATURE_DIR\u002Falignment.md`\n   - `FEATURE_DIR\u002Fcontext.md`\n   - `FEATURE_DIR\u002Freferences.md` if present\n   - `FEATURE_DIR\u002Fdeep-research.md` if present\n   - `.specify\u002Fmemory\u002Fconstitution.md` if present\n   - `.specify\u002Fmemory\u002Fproject-rules.md` if present\n   - compact `learning start --command deep-research` results and only selected `learning show` records\n   - **Project cognition gate:** query the active project's runtime before broad\n     repository reads.\n\n     Run or emulate:\n\n     ```text\n     C:\\Users\\11034\\.specify\\bin\\project-cognition.exe compass --intent research --query=\\\"$ARGUMENTS\\\" --format json\n     ```\n\n     After the default compass packet, run the advanced `lexicon -> semantic_intake -> query` path only when `compass_state`, coverage diagnostics, localization, or live evidence requires explicit concept decisions. In that escalation, use `project-cognition lexicon --mode catalog` as the alias catalog, write agent-authored `semantic_intake` and `concept_decisions`, then run `project-cognition query --query-plan \"\u003Cquery_plan_json>\"`; include `query_plan`, `semantic_intake`, `concept_decisions`, `covered_facets`, `missing_facets`, `match_sources`, `lexicon_generation_id`, `repository_search_terms`, project-language search terms, and facet coverage; do not search only the raw user words before source search. Agent-owned semantic normalization remains mandatory: `agent_normalization` and raw lexicon ranking are bootstrap signals only; if `agent_normalization` is omitted, treat it as `required=false`; use `write_semantic_intake_from_alias_catalog` when needed. Raw lexicon ranking is only a bootstrap; CJK or mixed CJK\u002FASCII input still requires agent-owned normalization even when positive raw lexical matches exist. The agent still owns translation. Readiness values are `query_ready`, `review`, `needs_rebuild`, `blocked`, and `unsupported_runtime`.\n\n     Use the returned readiness:\n\n     - `query_ready`: read top-level `minimal_live_reads` first, then use lane-level `first_pass_paths` reasons.\n     - `review`: perform only the returned `minimal_live_reads` before continuing and inspect `coverage_diagnostics`.\n     - `blocked`: report the blocking runtime issue and continue with live evidence only where this workflow allows degraded navigation.\n     - **CARRY FORWARD**: Treat project-cognition results as repository-grounded\n       starting context. Preserve cited capabilities, constraints, affected\n       surfaces, and verification routes in `deep-research.md`, and distinguish\n       repository facts from external research findings.\n   - From `FEATURE_DIR\u002Falignment.md`, extract:\n     - `Feasibility \u002F Deep Research Gate` status per capability\n     - `Planning Gate Recommendation`\n     - Capabilities marked `Needed before plan` → these are the research targets\n     - Capabilities marked `Not needed` or `Completed` → skip, do not research\n     - Capabilities marked `Blocked` → preserve blocker, record reason, do not research unless unblocked\n   - targeted live files only when the project cognition runtime cannot prove the current implementation pattern\n   - external docs, API references, release notes, examples, or research material when they materially affect feasibility\n\n3b. **Detect staleness and prior evidence**:\n    - If `FEATURE_DIR\u002Fdeep-research.md` already exists from a prior run, compare\n      new findings against prior conclusions.\n    - For each CAP with prior evidence, check whether dependencies (library\n      versions, API endpoints, platform behavior) have changed since the last\n      research pass.\n    - Mark CAPs with potentially stale evidence as `stale-needs-revalidation`\n      and prioritize their research tracks.\n    - Record staleness triggers (version bumps, deprecation notices, etc.) in\n      the track description.\n\n    ```markdown\n    ## Differential Evidence Analysis\n\n    | CAP ID | Previous Conclusion | Previous Evidence | New Evidence | Status Change |\n    |--------|--------------------|--------------------|--------------|---------------|\n    | CAP-001 | proven | EVD-001 | EVD-005 confirms | Unchanged |\n    | CAP-002 | constrained | EVD-002 | SPK-003 disproves | **OVERTURNED** → blocked |\n    | CAP-003 | proven (2026-03) | EVD-004 | lib X v3→v4 | **STALE** → revalidate |\n    ```\n\n4. **Decide whether this gate is needed**:\n   - Skip deep research and recommend `\u002Fsp.plan` when all target capabilities already have a known implementation path in the repository or the work is only a minor adjustment to existing behavior.\n   - When skipping, still write a lightweight `deep-research.md` using `**Status**: Not needed`, `Feasibility Decision`, `Planning Handoff`, and `Next Command`; do not invent `CAP\u002FTRK\u002FEVD\u002FPH` IDs for work that is already proven.\n   - Continue when any capability depends on an unproven API, library, algorithm, platform behavior, data volume, permission boundary, external integration, performance envelope, generated-code workflow, native\u002Fplugin bridge, or other path where planning would otherwise guess.\n   - If the uncertainty is a requirement gap rather than feasibility risk, recommend `\u002Fsp.clarify` and update `workflow-state.md` with that route reason.\n\n5. **Build a capability feasibility matrix from the spec's capability decomposition**:\n   - Start from the capability list in `spec.md`. Each spec capability maps to one CAP-###.\n   - Do not invent new capability names; use the spec's decomposition as the source of truth.\n   - If a spec capability is too broad for focused research, split it into sub-capabilities (CAP-001a, CAP-001b) and note the split in `alignment.md`.\n   - For each capability, read its feasibility status from `alignment.md` and take action:\n\n   | Alignment Status | Action |\n   |-----------------|--------|\n   | `Needed before plan` | Create research track, assign TRK-### |\n   | `Not needed` | Mark `proven` or `not needed`, skip |\n   | `Completed` | Preserve existing evidence, skip |\n   | `Blocked` | Record blocker, do not research |\n\n5b. **Consequence-Sensitive Research Tracks**:\n   - If the Senior Consequence Analysis Gate is triggered or upstream artifacts carry `CA-###` consequence obligations, create research tracks for any unproven affected object, state-behavior matrix entry, dependency impact, recovery behavior, validation route, or coverage gap that planning would otherwise guess.\n   - Each consequence-sensitive `TRK-###` must name the linked `CA-###` obligation, the stop-and-reopen condition it can clear or confirm, the evidence needed, and the downstream workflow that must consume the result.\n   - Research outputs must not drop `CA-###` consequence obligations; carry them into `Planning Handoff`, `Synthesis Decisions`, `Validation implications`, and residual risks until they are resolved or explicitly deferred.\n   - If evidence disproves an upstream consequence assumption, preserve the obligation as blocked, record the stop-and-reopen condition, and route back to `\u002Fsp.clarify` instead of handing ambiguous semantics to `\u002Fsp.plan`.\n   - When a consequence obligation is proven enough for planning, record the evidence ID, affected objects, lifecycle states covered, dependency impact, recovery and validation contract, remaining coverage gaps, and whether the obligation is still open.\n\n   For each capability or module slice, record:\n   - stable capability ID (`CAP-###`) — mapped from spec capability name\n   - capability name (from spec.md)\n   - desired outcome (from spec.md)\n   - current evidence from the repository\n   - unknown implementation-chain link\n   - research questions\n   - independent research track owner when delegation is useful\n   - whether a disposable demo is required\n   - proof target: what evidence would be enough to plan safely\n   - result status: `proven`, `constrained`, `not viable`, `blocked`, or `not needed`\n\n   Before finalizing the matrix, check each CAP against the preset research dimensions.\n   At minimum, confirm or mark \"not applicable\" for:\n   - permissions \u002F auth boundary\n   - data volume \u002F performance envelope\n   - error \u002F exception \u002F rollback flow\n   - concurrency \u002F consistency\n   - logging \u002F observability\n   - migration \u002F compatibility\n   - external dependency SLO \u002F failure mode\n   - template \u002F generated-code propagation\n   - minimum verifiable test path\n\n6. **Select the research dispatch shape**:\n   - [AGENT] Before research fan-out begins, assess workload shape and the current agent capability snapshot, then apply the shared policy contract: `choose_subagent_dispatch(command_name=\"deep-research\", snapshot, workload_shape)`.\n   - Persist the decision fields exactly: `execution_model: subagent-mandatory`, `dispatch_shape: one-subagent | parallel-subagents`, `execution_surface: native-subagents`.\n   - Decision order is fixed:\n     - One safe validated track -> `one-subagent` on `native-subagents` when available.\n     - Two or more safe isolated tracks -> `parallel-subagents` on `native-subagents` when available.\n     - No safe lane, overlapping write scopes, missing contract, or unavailable delegation -> `subagent-blocked` with a recorded reason.\n   - For `deep-research`, safe fan-out means at least two independent research tracks with disjoint write scopes. Research-only tracks return evidence packets; demo tracks write only under their assigned `FEATURE_DIR\u002Fresearch-spikes\u002F\u003Ctrack-slug>\u002F`.\n   - Required join points:\n     - before final conflict resolution\n     - before writing `Synthesis Decisions`\n     - before writing `Planning Handoff`\n   - Record the chosen strategy, reason, any `subagent-blocked` condition, selected research tracks, write scopes, and join points in `deep-research.md`.\n   - Keep the shared workflow language integration-neutral. Do not present Codex-only runtime surface wording in this shared template.\n\n7. **Plan and run coordinated research**:\n   - Create research tracks from the capability matrix before searching broadly.\n   - For each track, assign a stable track ID (`TRK-###`) and define the exact question, evidence target, likely sources, whether a spike is needed, and how the result will affect `\u002Fsp.plan`.\n   - If two or more tracks are independent and subagent dispatch is available, dispatch bounded subagents according to the Multi-Agent Research Orchestration contract.\n   - If subagent dispatch is unavailable or low-confidence, record `subagent-blocked`, capture which tracks could not be dispatched, and stop before substantive research until the block is resolved or explicitly escalated.\n   - Search and read only sources that answer a named feasibility question.\n   - Prefer primary docs, official examples, standards, changelogs, release notes, library docs, code examples from the dependency itself, and current repository evidence.\n   - Cite external sources in `references.md` and summarize how each source affects the implementation chain.\n   - Separate facts from inference. If one source is weak or unverified, say so.\n   - Preserve rejected alternatives with explicit reasons when they matter to planning.\n   - Convert every completed track into an evidence packet with stable evidence IDs (`EVD-###`), evidence quality ratings, limitations, and a track exit state.\n\n8. **Run isolated demo validation when needed**:\n   - Assign a stable spike ID (`SPK-###`) and create the smallest runnable spike under `SPIKES_DIR` when docs and repository evidence cannot prove feasibility.\n   - Keep the spike intentionally disposable: no production imports unless read-only, no edits outside `FEATURE_DIR\u002Fresearch-spikes\u002F`, no migration or test-suite changes.\n   - Define the spike before writing it:\n     - hypothesis\n     - inputs \u002F fixture data\n     - setup\u002Fenv\n     - expected pass condition\n     - commands to run\n     - actual result capture format\n     - cleanup or non-persistence note\n     - what this does not prove\n   - Run the spike command if the local environment supports it.\n   - Capture command, exit status, relevant output summary, and evidence path in `deep-research.md`.\n   - If the environment cannot run the spike, record exactly what is missing and whether planning can still proceed with a manual-risk note.\n\n9. **Synthesize research into planning decisions**:\n   - Compare evidence packets across tracks.\n   - Resolve conflicts and record why one source or demo result won over another.\n   - Record every conflict and its resolution in the `Contradiction Resolution Log`.\n   - Unresolved conflicts must be marked `BLOCKED` and escalated; do not hide them.\n   - Identify the recommended approach, rejected approaches, and constraints `\u002Fsp.plan` must preserve.\n   - Translate demo observations into planning implications rather than leaving them as raw logs.\n   - Identify module boundaries, API\u002Flibrary choices, data flow notes, operational constraints, and validation implications that planning must account for.\n   - Assign stable Planning Handoff IDs (`PH-###`) to each decision or constraint that `\u002Fsp.plan` must consume.\n\n10. **Write `deep-research.md`**:\n   Use `.specify\u002Ftemplates\u002Fexamples\u002Fdeep-research\u002F` as the output-shape reference when available:\n   - `not-needed.md` for `**Status**: Not needed`\n   - `docs-only-evidence.md` when repository evidence and primary documentation are enough\n   - `spike-required.md` when a disposable demo proves the implementation chain\n\n   Use the lightweight structure below only when the gate is not needed:\n\n   ```markdown\n   # Deep Research: [FEATURE NAME]\n\n   **Feature Branch**: `[###-feature-name]`\n   **Created**: [DATE]\n   **Status**: Not needed\n\n   ## Feasibility Decision\n\n   - **Recommendation**: Proceed to `\u002Fsp.plan`\n   - **Reason**: [Why repository evidence already proves the implementation chain]\n   - **Planning handoff readiness**: Not needed\n\n   ## Planning Handoff\n\n   - **Handoff IDs**: Not needed\n   - **Status**: All capabilities have proven implementation chains in repository\n   - **Recommended approach**: [Existing implementation path `\u002Fsp.plan` should use]\n   - **Constraints `\u002Fsp.plan` must preserve**: [Existing boundary, behavior, or constraint]\n   - **PH items**: None (all capabilities proven — no research-generated handoff items)\n\n   ## Planning Handoff Readiness Checklist\n\n   - [ ] All capabilities have proven implementation chains in repository\n   - [ ] `alignment.md` updated with `Not needed` feasibility status\n   - [ ] `context.md` updated\n   - [ ] `workflow-state.md` updated with `next_command: \u002Fsp.plan`\n\n   ## Next Command\n\n   - `\u002Fsp.plan`\n   ```\n\n   Use the full structure below when any capability needed research, evidence, or a disposable spike:\n\n   ```markdown\n   # Deep Research: [FEATURE NAME]\n\n   **Feature Branch**: `[###-feature-name]`\n   **Created**: [DATE]\n   **Status**: [Ready for plan | Ready for plan with constraints | Blocked | Not needed]\n\n   ## Feasibility Decision\n\n   - **Recommendation**: [Proceed to `\u002Fsp.plan` | Proceed with constraints | Run `\u002Fsp.clarify` | Stop \u002F redesign]\n   - **Reason**: [Short evidence-based rationale]\n   - **Planning handoff readiness**: [Complete | Complete with constraints | Incomplete]\n\n   ## Capability Feasibility Matrix\n\n   | Capability ID | Capability | Unknown Link | Evidence Needed | Proof Method | Result |\n   | --- | --- | --- | --- | --- | --- |\n   | CAP-001 | [Name] | [What was uncertain] | [Proof target] | [docs \u002F repo evidence \u002F demo] | [proven \u002F constrained \u002F blocked \u002F not needed] |\n\n   ## Research Orchestration\n\n   - **Execution model**: subagent-mandatory\n   - **Dispatch shape**: [one-subagent | parallel-subagents | subagent-blocked]\n   - **Execution surface**: native-subagents\n   - **Reason**: [safe-one-subagent | safe-parallel-subagents | native-subagents-supported | no-safe-delegated-lane | unsafe-write-sets | packet-not-ready | runtime-no-subagents | low-delegation-confidence]\n   - **Selected tracks**:\n     - [track] -> [research-only evidence packet | demo spike write scope]\n   - **Join points**:\n     - before final conflict resolution\n     - before writing `Synthesis Decisions`\n     - before writing `Planning Handoff`\n\n   ## Research Agent Findings\n\n   | Track ID | Agent \u002F Mode | Question | Evidence IDs | Confidence | Exit State | Planning Implication |\n   | --- | --- | --- | --- | --- | --- | --- |\n   | TRK-001 | [child agent name or subagent-blocked status] | [Question] | EVD-001, SPK-001 | [high \u002F medium \u002F low] | [enough-to-plan \u002F constrained-but-plannable \u002F blocked \u002F not-viable \u002F user-decision-required] | [What `\u002Fsp.plan` must use] |\n\n   ## Evidence Quality Rubric\n\n   | Evidence ID | Supports | Source Tier | Source \u002F Path | Reproduced Locally | Recency \u002F Version | Confidence | Plan Impact | Limitations | Persisted |\n   | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n   | EVD-001 | CAP-001 \u002F PH-001 | [repo-evidence \u002F runnable-spike \u002F primary-docs \u002F official-example \u002F standard \u002F secondary-source \u002F inference] | [URL, file path, or spike path] | [yes \u002F no \u002F not applicable] | [date\u002Fversion\u002Fnot time-sensitive] | [high \u002F medium \u002F low] | [blocking \u002F constraining \u002F informative] | [what this does not prove] | research-evidence\u002FEVD-001.json |\n\n   ## Implementation Chain Evidence\n\n   ### [Capability Name]\n\n   - **Capability ID**: CAP-001\n   - **Chain**: [trigger\u002Finput -> module\u002FAPI\u002Flibrary -> state\u002Foutput -> validation]\n   - **Repository evidence**: [EVD IDs, files, patterns, existing behavior]\n   - **External evidence**: [EVD IDs, source links or references.md entries]\n   - **Demo evidence**: [SPK IDs, spike path and command result, or not needed]\n   - **Planning constraints**: [rules `\u002Fsp.plan` must preserve]\n   - **Residual risk**: [remaining uncertainty]\n\n   ## Demo \u002F Spike Evidence\n\n   - **Spike ID**: SPK-001\n   - **Spike**: [name]\n   - **Hypothesis**: [what it proves]\n   - **Path**: `research-spikes\u002F[name]`\n   - **Setup \u002F env**: [runtime, dependency, fixture, credentials placeholder, or not required]\n   - **Command**: `[command]`\n   - **Expected result**: [observable pass condition]\n   - **Actual result**: [passed \u002F failed \u002F not run, with summary]\n   - **Evidence summary**: [short result]\n   - **Cleanup note**: [what remains disposable or how to remove it]\n   - **What this does not prove**: [limits of the spike]\n   - **Planning implication**: [what design or validation decision follows]\n\n   ## Spike Log\n\n   - **Spike**: [name]\n   - **Hypothesis**: [what it proves]\n   - **Path**: `research-spikes\u002F[name]`\n   - **Command**: `[command]`\n   - **Result**: [passed \u002F failed \u002F not run]\n   - **Evidence summary**: [short result]\n\n   ## Synthesis Decisions\n\n   - **Recommended approach**: [PH-001 -> approach and why]\n   - **Rejected options**:\n     - [option] -> [evidence-based reason and evidence IDs]\n   - **Conflict resolution**:\n     - [conflict] -> [resolution and evidence priority]\n   - **Plan constraints**:\n     - PH-### -> [constraint `\u002Fsp.plan` must preserve]\n\n   ## Contradiction Resolution Log\n\n   When two or more evidence items produce conflicting findings, record the\n   resolution. Unresolved contradictions must be marked `BLOCKED` and escalated.\n\n   | Conflict | Evidence A | Evidence B | Resolution | Priority Basis | Suppressed Reason |\n   |----------|-----------|-----------|------------|----------------|-------------------|\n   | [e.g. API version] | EVD-002: v3 | EVD-005: v2 | v3 accepted | spike > docs | EVD-005 was outdated |\n   | [unresolved] | EVD-007: pattern A | SPK-003: pattern B | **BLOCKED** | — | Contradictory runnable evidence |\n\n   ## Planning Handoff\n\n   - **Handoff IDs**: PH-001, PH-002, ...\n   - **Recommended approach**: PH-001 -> [implementation direction `\u002Fsp.plan` should start from; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Architecture implications**: PH-002 -> [components, layering, boundaries, sequencing; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Module boundaries**: PH-003 -> [owners and interfaces to preserve; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **API \u002F library choices**: PH-004 -> [selected APIs\u002Flibraries and why; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Data flow notes**: PH-005 -> [inputs, state, outputs, side effects; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Demo artifacts to reference**: PH-006 -> [`research-spikes\u002F...` and command result; trace to SPK IDs]\n   - **Constraints `\u002Fsp.plan` must preserve**:\n     - PH-### -> [constraint; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Validation implications**: PH-### -> [tests\u002Fchecks the plan should include later; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Residual risks requiring design mitigation**:\n     - PH-### -> [risk; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Decisions already proven by research**:\n     - PH-### -> [decision; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n\n   - **PH consumption contract**:\n     - `mandatory` — `\u002Fsp.plan` must consume this PH; omitting it is a plan error.\n     - `optional` — `\u002Fsp.plan` may defer if the plan does not need it.\n     - `user-decision` — `\u002Fsp.plan` must ask the user before consuming or deferring.\n\n     Each PH item in the Traceability Index must carry its consumption contract in\n     the `Mandatory?` column.\n\n   ## Capability Cards\n\n   For each high-value or planning-critical capability, emit a capability card:\n\n   ### CAP-001: [Capability Name]\n\n   | Field | Detail |\n   |-------|--------|\n   | **Purpose** | [What this capability achieves] |\n   | **Owner** | [Owning module \u002F service \u002F surface] |\n   | **Truth lives** | [Code path, data table, config, or external service] |\n   | **Entry points** | [CLI command, API route, event handler, hook] |\n   | **Downstream consumers** | [What depends on this capability] |\n   | **Extend here** | [Safe extension points] |\n   | **Do not extend here** | [Fragile or contract-locked areas] |\n   | **Key contracts** | [Input shape, output shape, side effects, invariants] |\n   | **Change propagation** | [What breaks when this changes] |\n   | **Minimum verification** | [Command or check that proves this works] |\n   | **Failure modes** | [Known ways this can fail] |\n   | **Confidence** | [Verified \u002F Inferred \u002F Unknown-Stale] |\n\n   ## Research Exclusions\n\n   Areas, surfaces, or dimensions intentionally not researched in this pass.\n\n   | Excluded Area | Reason | Revisit Condition | Recorded By |\n   |---------------|--------|-------------------|-------------|\n   | [e.g. performance profiling] | [Not in feature scope] | [Before production deploy] | [Coordinator \u002F TRK-###] |\n\n   Every unverified dimension from the preset research checklist that was marked\n   \"not applicable\" or \"deferred\" must appear here with a revisit condition.\n\n   ## Planning Traceability Index\n\n   | PH ID | CAP ID | TRK ID | Evidence IDs | Evidence Quality | Plan Consumer | Required Plan Action | Mandatory? |\n   |-------|--------|--------|-------------|-------------------|---------------|----------------------|------------|\n   | PH-001 | CAP-001 | TRK-001 | EVD-001, SPK-001 | HIGH \u002F blocking | architecture | Use pattern X | mandatory |\n   | PH-002 | CAP-001 | TRK-002 | EVD-003 | MEDIUM \u002F constraining | data-model | Consider limit Y | optional |\n\n   ## Sources\n\n   - [Source title](URL) -> [why it matters]\n\n   ## Planning Handoff Readiness Checklist\n\n   - [ ] All CAPs have explicit exit status (`proven` \u002F `constrained` \u002F `blocked` \u002F `not-viable`)\n   - [ ] All PH items trace to evidence (EVD\u002FSPK\u002Frepo path)\n   - [ ] All spike results recorded with pass\u002Ffail outcome\n   - [ ] All residual risks explicitly linked to evidence IDs\n   - [ ] All research exclusions have revisit conditions\n   - [ ] `alignment.md` updated with feasibility result and Planning Gate Recommendation\n   - [ ] `context.md` updated with implementation-chain evidence, constraints, rejected options\n   - [ ] `references.md` updated with external sources\n   - [ ] `workflow-state.md` updated with exit criteria and `next_command`\n   - [ ] Reverse Coverage Validation passed (all CAP→PH→Evidence chains closed)\n   - [ ] Readiness Refusal Rules all PASS\n\n   ## Next Command\n\n   - [`\u002Fsp.plan` | `\u002Fsp.clarify` | stop with blocker]\n   ```\n\n11. **Update upstream artifacts when research changes planning readiness**:\n   - Update `alignment.md`:\n     - add feasibility result, capability status, implementation-chain confidence, Planning Handoff readiness, and Planning Gate Recommendation\n     - recommend `\u002Fsp.deep-research` only when more feasibility work remains\n     - recommend `\u002Fsp.plan` only when every planning-critical capability is proven, constrained enough, not needed, or explicitly force-accepted\n   - Update `context.md`:\n     - add implementation-chain evidence, Planning Handoff summary, spike paths, external constraints, rejected options, and residual risks that `\u002Fsp.plan` must preserve\n   - Update `references.md`:\n     - add external sources and reusable insights\n\n12. **Run an artifact review gate**:\n    - Review `deep-research.md`, `alignment.md`, and `context.md` for:\n      - unproven capability chains presented as facts\n      - demos with no pass condition\n      - source claims without source attribution\n      - subagent findings copied without coordinator synthesis\n      - missing or vague research orchestration strategy when multiple tracks were available\n      - missing `Planning Handoff` decisions for capabilities that affect plan structure\n      - production-code edits from the research phase\n      - feasibility risks not reflected in the Planning Gate Recommendation\n    - If issues remain, revise the artifacts before handoff.\n\n12b. **Run reverse coverage validation**:\n    - Prove every CAP has at least one PH-ID.\n    - Prove every PH-ID traces back to at least one evidence item (`EVD-###`, `SPK-###`, or live repository path).\n    - Prove every `proven` CAP has no remaining unresolved unknown links.\n    - Prove every `blocked` CAP has a concrete block reason and next action.\n    - Prove every accepted evidence packet was consumed by at least one PH or explicitly deferred.\n    - If any check fails, refuse handoff and write gaps back to `workflow-state.md`.\n\n    ```markdown\n    ## Reverse Coverage Validation\n\n    | CAP ID | Has PH? | PH IDs | Has Evidence? | Evidence IDs | Proven \u002F Clean? |\n    |--------|---------|--------|---------------|-------------|-----------------|\n    | CAP-001 | PASS | PH-001, PH-002 | PASS | EVD-001, SPK-001 | PASS |\n    | CAP-002 | FAIL | — | — | — | FAIL: No PH assigned |\n\n    **Decision**: [PASS \u002F FAIL — if FAIL, refuse handoff]\n    ```\n\n13. **Write or update `WORKFLOW_STATE_FILE`**:\n    - Record:\n      - `active_command: sp-deep-research`\n      - `phase_mode: research-only`\n      - current authoritative files\n      - exit criteria for feasibility completion\n      - next action required before handoff\n      - `next_command` as `\u002Fsp.plan`, `\u002Fsp.clarify`, or `\u002Fsp.deep-research`\n\n14. **Report completion**:\n    - branch or feature directory\n    - deep-research artifact path\n    - spike paths and command results, if any\n    - research tracks and subagent evidence packet summary, if any\n    - proven capabilities\n    - constrained or blocked capabilities\n    - Planning Handoff summary for `\u002Fsp.plan`\n    - updated alignment\u002Fcontext\u002Freference paths\n    - recommended next command\n    - whether the feature is ready for `\u002Fsp.plan`\n    - [AGENT] before final completion text, if auto-capture did not preserve a reusable `workflow_gap`, `project_constraint`, or `decision_debt`, use the manual `learning capture` helper surface.\n      Required options: `--command`, `--type`, `--summary`, `--evidence`\n    - Use the user's current language for explanatory text while preserving literal command names, file paths, and fixed status values exactly as written.\n\n## Readiness Refusal Rules\n\nBefore writing final `deep-research.md` and recommending `\u002Fsp.plan`, run every\ncheck below. If **any** check fails, refuse handoff, produce a gap report, and\nset `next_command` to `\u002Fsp.clarify` or mark the phase as blocked.\n\n- [ ] Every CAP has at least one PH-ID assigned\n- [ ] Every PH-ID traces to at least one evidence ID (`EVD-###`, `SPK-###`, or live repository path)\n- [ ] No CAP remains `blocked` without an explicit user force-accept recorded in `alignment.md`\n- [ ] No `proven` CAP still has unresolved unknown links in its implementation chain\n- [ ] Every dispatched subagent returned an accepted evidence packet; rejected packets were retried or escalated\n- [ ] `dispatch_shape: subagent-blocked` is recorded with a concrete block reason and escalation path\n- [ ] Every spike with a defined hypothesis was run and has a captured pass\u002Ffail result\n\nWhen refusal happens, output a gap report inline before the refusal decision:\n\n```markdown\n## Readiness Refusal Report\n\n| Check | Status | Affected IDs | Missing \u002F Reason |\n|-------|--------|-------------|-------------------|\n| All CAPs have PH | FAIL | CAP-003 | No PH assigned |\n| All PHs trace to evidence | FAIL | PH-005 | No EVD\u002FSPK\u002Frepo path |\n| ... | PASS | — | — |\n\n**Decision**: Handoff refused. Next command: `\u002Fsp.clarify`\n```\n\n## Rules\n\n- Use this command to produce research evidence and a planning handoff, not to design the full architecture.\n- Prefer a small, runnable proof over broad speculative prose when the question is \"can this work?\"\n- Disposable demos, research spikes, and proof artifacts validate feasibility for the user's intended capability. They are not a replacement product scope and must not be reframed as the delivered product unless the user explicitly confirms that reduced scope.\n- Do not require this command for existing capability tweaks where the repository already shows the path.\n- Do not advance to `\u002Fsp.plan` when a required capability is still `blocked` or `not viable` unless the user explicitly accepts a redesign or force-proceed risk.\n- Keep all prototype work isolated under `FEATURE_DIR\u002Fresearch-spikes\u002F`.\n- Do not edit source code, tests, migrations, or production config from this command.\n- Do not hand off to `\u002Fsp.plan` with only raw research notes; synthesize findings into `Planning Handoff`, constraints, rejected options, and residual risks.\n- If this workflow makes actual source\u002Fruntime\u002Ftemplate\u002Fconfig\u002Ftest\u002Fgenerated-asset changes in the current run, follow the shared inline closeout contract:\n\n### Inline Project Cognition Update\n\nWorkflow-owned mutation closeout is not an external map-maintenance handoff and is not external map maintenance. It is the workflow-local form of `\u002Fsp-map-update`. If this workflow changed project-related source, runtime, templates, generated assets, config, tests, state contracts, shared surfaces, or behavior-bearing docs, closeout MUST run inline project cognition update for the workflow-owned changed paths and affected surfaces before claiming clean completion.\n\nCall the planner first:\n\n```text\nproject-cognition closeout-plan --workflow \"$ACTIVE_WORKFLOW\" --format json\n```\n\nWhen `DELTA_SESSION_ID` exists, pass it into the planner:\n\n```text\nproject-cognition closeout-plan --workflow \"$ACTIVE_WORKFLOW\" --delta-session \"$DELTA_SESSION_ID\" --format json\n```\n\nConsume `workflow_canonical`, `update_mode`, `payload_draft`, `required_agent_fields`, `unknown_paths`, `unknown_path_dispositions`, `delta_append_draft`, display-only `delta_append_command`, `update_argv`, display-only `update_command`, and `recommended_next_command`.\n\nBefore running `update`, fill the fields listed in `required_agent_fields` from live evidence from this workflow. Supported agent-owned evidence fields include:\n\n- `verification`\n- `behavior_surfaces`\n- `generated_surfaces`\n- `state_contracts`\n- `known_unknowns`\n- `confidence_notes`\n- `user_decisions`\n- `boundary`\n\nIf a field appears in `required_agent_fields`, provide live-evidence-backed content for it. Fields not listed by `required_agent_fields`, such as `known_unknowns` and `boundary`, are populated only when live evidence supports them; do not invent them to satisfy the shape.\nUse `known_unknowns` only for blockers that make the cognition update unsafe to trust. If the working tree contains unrelated dirty\u002Funtracked paths and the workflow uses explicit workflow-owned paths, record that as `confidence_notes` or `boundary.initial_dirty_paths`, not as a blocking `known_unknowns` item.\n\nFor each `unknown_path_dispositions[]` item, set `agent_disposition` to exactly one allowed value:\n\n- `adoptable`: verified new path inside this workflow-owned scope; it may be recorded in changed\u002Fscope paths and verified adoptable paths do not become blocking `known_unknowns`.\n- `review_only`: path informed review but is not adopted into changed coverage.\n- `ignored`: path remains excluded and must not enter payloads, records, route indexes, evidence, aliases, or minimal live reads.\n- `blocking_known_unknown`: record it as a known unknown and report partial or blocked cognition closeout.\n\n`agent_disposition=adoptable` is an agent accounting decision, not proof that runtime indexing already succeeded. Runtime adoption still requires a usable active project-cognition DB, at least one passing verification evidence item, and no blocking `known_unknowns`. After `update_argv` runs, inspect `result_state`, `adopted_paths`, `review_paths`, `minimal_live_reads`, and `partial_refresh_reasons`; do not explain a remaining `partial_refresh` as \"path_index missing\" until those fields show which adoption gate failed.\n\nIf `update_mode=delta_session`, complete `delta_append_draft.argv_prefix` with agent-owned repeatable flags such as `--behavior-surface`, `--generated-surface`, `--verification`, and accepted `--known-unknown` values from `delta_append_draft.argv_placeholders`. Then append the delta event and run `update_argv`. `delta_append_command` and `update_command` are display-only placeholders, not execution strings.\n\nIf `update_mode=payload_file`, write the completed `payload_draft` to the planner's `payload_path`. Then run `update_argv`. `update_command` is a display-only placeholder, not an execution string.\n\nCompleted payload drafts preserve the planner-owned `changed_paths` and `scope_paths` and add agent-owned evidence fields before recording.\n\nStructured `update` invalidates related claims and returns their stable IDs in `affected_graph_claims`. This is separate from update readiness: generic workflow verification and `result_state=ready` must not re-promote stale or contradicted graph claims. Only when this workflow already has decisive claim-specific bounded live evidence for an exact returned claim ID may it submit semantic reconciliation intent and run:\n\n```text\nproject-cognition claim-reconcile prepare --input \u003Cintent.json> --format json\nproject-cognition claim-reconcile apply --input \u003Cprepared_packet_path> --format json\n```\n\nProvide only reconciliation intent: workflow, stable `claim_id`, reason, and evidence containing repository-relative `source_path`, bounded line `span`, and `supporting` or `contradicting` role. Add verification only when it is claim-specific. The runtime owns the contract version, active generation, expected state and revision, UTC observation and expiry, source kind, content hashes, repository snapshot, IDs, and prepared packet path. Do not author or edit those integrity fields; execute the returned `apply_argv` exactly. If no such evidence exists, leave the claim stale. If reconciliation returns ready, rerun Compass once so later routing consumes the current evidence basis; partial or blocked reconciliation remains withheld and follows `recommended_next_action`.\n\nFor compatibility with worker handoffs and delta packets, the runtime also accepts `verification_evidence` as an alias for `verification` and `generated_surface_notes` as an alias for `generated_surfaces`. Verification evidence may be an array of objects (`command`, `result`, `artifact`) or an array of command-result strings, but clean closeout still requires passing verification evidence; failed verification cannot produce a clean `ready` closeout.\n\nClean closeout keys on `result_state`, not `status=ok`, `update_id`, `last_update_id`, or freshness alone:\n\n- `ready` or `no_op`: project cognition closeout may be clean when ordinary verification also passed.\n- `partial_refresh`: useful update data was written, but the final workflow state must report partial cognition closeout, `partial_refresh_reasons`, and the returned `minimal_live_reads`. If `partial_refresh_reasons` includes `missing_passing_verification_result`, repair the payload or delta evidence and rerun `update_argv` before final closeout; do not route that to `sp-map-update`. If verified workflow-owned paths still remain in `review_paths` after the update, report implementation completion separately from project-cognition maintenance and name `\u002Fsp-map-update` as follow-up repair.\n- `needs_rebuild`: report the exact rebuild condition and route to `\u002Fsp-map-scan`, then `\u002Fsp-map-build`.\n- `blocked`: report the runtime or validation blocker and the exact recovery command.\n- `recorded`: legacy recorded-only output; treat it as partial or blocked, never as clean completion.\n\nNever run the `complete-refresh` or `clear-dirty` helper after `result_state=partial_refresh`, `needs_rebuild`, `blocked`, or legacy `recorded`; those helpers are only for states that the runtime and validation prove ready.\n\nDirty fallback command shape: `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe mark-dirty --reason \\\"\u003Creason>\\\" --format json`.\nUse `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe mark-dirty --reason \\\"workflow-closeout-failed\\\" --format json` only when inline update cannot complete: when the planner or update command is unavailable, cannot record useful update data, cannot identify workflow-owned scope, or cannot be trusted because verification\u002Fworkflow completion is not trustworthy. Dirty only when inline update cannot complete.\n\nsp-map-update is for manual\u002Fexternal maintenance and follow-up repair. `\u002Fsp-map-update` remains the external\u002Fmanual workflow for user edits, interrupted workflow repair, explicit map maintenance, and follow-up repair. It is not routine cleanup for changes this workflow just made. If `sp-map-update` already ran `project-cognition update --reason map-update` for the same changed paths, do not run a second `workflow-finalize` closeout update for those paths.\n\n## Post-Execution Checks\n\n**Check for extension hooks (after deep research)**:\n- Check if `.specify\u002Fextensions.yml` exists in the project root.\n- If it exists, read it and look for entries under the `hooks.after_deep_research` key.\n- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally.\n- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.\n- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:\n  - If the hook has no `condition` field, or it is null\u002Fempty, treat the hook as executable.\n  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation.\n- For each executable hook, output the following based on its `optional` flag:\n  - **Optional hook** (`optional: true`):\n    ```\n    ## Extension Hooks\n\n    **Optional Hook**: {extension}\n    Command: `\u002F{command}`\n    Description: {description}\n\n    Prompt: {prompt}\n    To execute: `\u002F{command}`\n    ```\n  - **Mandatory hook** (`optional: false`):\n    ```\n    ## Extension Hooks\n\n    **Automatic Hook**: {extension}\n    Executing: `\u002F{command}`\n    EXECUTE_COMMAND: {command}\n    ```\n- If no hooks are registered or `.specify\u002Fextensions.yml` does not exist, skip silently.\n\n## Claude Code Subagent Capability Discovery\n\n- Execution model: preserve the workflow's existing `subagent-mandatory`, `subagents-first`, `adaptive`, or `subagent-assisted` policy.\n- Dispatch shape: preserve the workflow's existing dispatch shape; use `subagent-blocked` only after the discovery step below fails or is unsafe.\n- Execution surface: prefer `native-subagents` when the current runtime supports it; use `none` only after recording the unavailable or unsafe surface.\n- Native subagent capability discovery: Before recording `subagent-blocked`, check the active tool surface for the integration-native subagent or task-dispatch entrypoint and record the exact missing surface if unavailable.\n- Do not record `subagent-blocked` until this capability discovery step is complete and the exact unavailable or unsafe surface is recorded.\n- Native subagent dispatch: Dispatch subagents through the integration's native subagent support using the shared prompt contract.\n- Join behavior: Use the integration-native join point, then integrate results back on the leader path.\n- Preserve this workflow's existing packet, handoff, artifact, and result schema; this section only governs capability discovery before dispatch or blocked-state recording.\n\n## Claude Code Structured Question Preference\n\n- If this command was routed by `sp-auto` with `auto_default_recommendation: true`, evaluate the automatic recommended\u002Fdefault continuation gate before any question path.\n- When that gate has one safe recommended\u002Fdefault answer, you must auto-resolve the question or confirmation, record the accepted recommendation in the workflow state or summary, continue the workflow, and do not invoke the native structured question tool only to ask for that approval.\n- If the automatic gate is not safe, write the blocker and self-unblock recommendation before using the normal question path.\n- If the runtime's native structured question tool is available for the current turn and the `sp-auto` automatic gate did not resolve the question, you must use it.\n- Do not render the textual fallback block when the native tool is available.\n- Do not self-authorize textual fallback because the question seems simple, short, or easy to phrase manually.\n- Treat the template's textual question format as fallback-only guidance; use it to shape the question content, but do not render the textual block unless the native tool is unavailable in the current runtime or the tool call fails.\n- Keep native-tool availability, runtime mode, and fallback mechanics backstage. Do not tell the user that a structured question tool is unavailable, that the current runtime\u002Fmode lacks a tool, or that a fallback is being used; ask the user-facing question directly when a question is genuinely required.\n- Ask only the minimum number of questions required by this workflow's existing contract.\n- Keep the user-visible question text in the user's current language and keep option labels short.\n- Do not emit both a native tool question and the textual fallback block in the same turn. The user should see the active question exactly once.\n- If the native tool is unavailable in the current runtime or the tool call fails, ask one concise plain-text question about the missing feasibility or research-track decision, then continue with the existing research workflow.\n- In `deep-research`, use this preference for:\n  - whether the feasibility question is actually a requirement gap\n  - minimum research tracks needed before planning\n  - manual confirmation before force-proceeding with unresolved feasibility risk\n- Native tool target: `AskUserQuestion`\n- When this native tool target is listed for the integration and the runtime does not signal otherwise, assume it is available by default in normal interactive sessions.\n- Question count: 1-4 questions per call\n- Option count: 2-4 options per question\n- Required question fields: `question`, `header`, `options`, `multiSelect`\n- Option fields: `label`, `description`, `preview (optional)`\n- Use `multiSelect: false` unless the workflow explicitly needs multiple selections.\n- Use `metadata` only when tracking or analytics context adds value; otherwise keep the call minimal.\n","## Invocation Syntax\n\n- In this integration, invoke workflow skills with `\u002Fsp-plan`-style syntax.\n- References such as `\u002Fsp.plan`, `\u002Fsp.tasks`, or `next_command: \u002Fsp.plan` are canonical workflow-state identifiers and handoff values.\n- Preserve those canonical state tokens exactly in artifacts and workflow state; do not rewrite them to this integration's invocation syntax.\n\n\n\n## Workflow Contract Summary\n\n- **When to use**: The current spec package exists, but one or more capabilities do not yet have a credible implementation chain.\n- **Primary objective**: Coordinate focused research and isolated prototype evidence, synthesize implementation-chain decisions, and produce a planning handoff before \u002Fsp-plan.\n- **Primary outputs**: `FEATURE_DIR\u002Fdeep-research.md` with `Planning Handoff`, optional `FEATURE_DIR\u002Fresearch-spikes\u002F`, updated `alignment.md`, `context.md`, `references.md`, and `workflow-state.md`.\n- **Default handoff**: \u002Fsp-plan when feasibility is proven or explicitly accepted; otherwise \u002Fsp-clarify for requirement gaps or stop with blocked research risks.\n- **Execution note**: This summary is routing metadata only. Follow the full contract below end-to-end rather than inferring behavior from the description alone.\n\n## Blocked Exit Contract\n\nIf blocked after safe recovery, read and follow\n`.specify\u002Ftemplates\u002Fworkflow-blocker-template.md` and its JSON schema. Never\nreturn only an error or “ask a human”; preserve state and keep agent-capable\nrepair agent-owned. Set `human_action_required: true` only for authority,\ncredentials, protected systems, human decisions\u002Freviews, or physical access.\nTailor steps, expected results, failure paths, evidence, and resume action to\nCI, visual review, or product decisions. Never claim completion.\n\n## User Input\n\n```text\n$ARGUMENTS\n```\n\nYou **MUST** consider the user input before proceeding (if not empty).\n\n## Objective\n\nProduce a planning-ready research packet before implementation planning starts:\nprove or retire planning-critical feasibility questions, synthesize external and\nrepository evidence, validate uncertain links with disposable demo spikes when\nneeded, and hand `\u002Fsp.plan` the constraints and recommended implementation\ndirection it must preserve.\n\n## Context\n\n- Primary inputs: the current spec package, unresolved feasibility risks,\n  external references, repository evidence, research-agent findings, and any\n  disposable prototype evidence created in this command.\n- The active working set is `spec.md`, `alignment.md`, `context.md`,\n  `references.md`, `deep-research.md`, `research-spikes\u002F`, and\n  `workflow-state.md` inside the current `FEATURE_DIR`.\n- This command is research-only. It is not permission to implement production\n  behavior.\n\n## Process\n\n- Decide whether a feasibility and research handoff gate is actually needed.\n- Decompose unknown implementation chains by capability and independent\n  research track.\n- Dispatch subagents when independent research tracks can run in parallel and\n  produce evidence packets without conflicting writes.\n- Research external APIs, libraries, algorithms, platform constraints, and\n  repository patterns only where those facts change planning.\n- Build the smallest disposable demo or spike when research alone cannot prove\n  the chain.\n- Synthesize research-agent findings and spike results into planning decisions,\n  rejected options, risks, and a concrete `\u002Fsp.plan` handoff.\n- Run reverse coverage validation before handoff: every CAP → PH → Evidence chain must close.\n- Run readiness refusal checks; refuse handoff with a gap report when checks fail.\n- Run the Planning Handoff Readiness Checklist; do not recommend `\u002Fsp.plan` until all items pass.\n\n## Output Contract\n\n- Write or update `deep-research.md`.\n- Optionally write isolated scratch assets under `research-spikes\u002F`.\n- Update `alignment.md`, `context.md`, `references.md`, and `workflow-state.md`\n  when feasibility evidence changes planning readiness.\n- If this gate is not needed, still write a lightweight `deep-research.md`\n  with `**Status**: Not needed`, `Feasibility Decision`, `Planning Handoff`,\n  and `Next Command`; do not invent `CAP\u002FTRK\u002FEVD\u002FPH` IDs for already-proven\n  work.\n- Include a `Planning Handoff` section that `\u002Fsp.plan` can consume directly for\n  recommended approach, module boundaries, API\u002Flibrary choices, demo artifacts,\n  constraints, rejected options, and residual risks.\n- Use stable traceability IDs (`CAP-###`, `TRK-###`, `EVD-###`, `SPK-###`,\n  `PH-###`) plus an evidence quality rubric so `\u002Fsp.plan` can cite exactly which\n  research finding or spike supports each design decision.\n- Use `.specify\u002Ftemplates\u002Fexamples\u002Fdeep-research\u002F` as the output-shape\n  reference when available: `not-needed.md`, `docs-only-evidence.md`, and\n  `spike-required.md`.\n- Report which capabilities are proven, constrained, blocked, or no longer worth\n  planning.\n- Persist accepted evidence packets as `FEATURE_DIR\u002Fresearch-evidence\u002F\u003CEVD-###>.json`.\n\n## Guardrails\n\n- Do not edit production source files, tests, migrations, release config, or\n  implementation artifacts from `sp-deep-research`.\n- Keep demos disposable and isolated under `FEATURE_DIR\u002Fresearch-spikes\u002F` unless\n  the user explicitly asks to preserve a prototype elsewhere in a later\n  implementation workflow.\n- Skip this command when the change is a minor adjustment to an existing,\n  already-proven capability.\n- Do not let research subagents edit production files; they must either\n  return evidence packets or write only to their assigned disposable spike\n  directory.\n- A research pass without runnable evidence (spike result or repo path trace) is a failed pass.\n- Coordinator-only execution without subagent dispatch justification and recorded `subagent-blocked` reason is a failed pass.\n- Feasibility claims based only on documentation citations without live repository path reads are not sufficient for planning.\n- Subagent evidence packets without `paths_read` must be rejected; do not accept or synthesize them.\n- A structural-only refresh (reformatting findings without new evidence) is a failed pass.\n- Treat `context.md` Locked Decisions as immutable constraints during research.\n  Do not research alternatives that contradict a locked decision unless the\n  research explicitly proves the locked decision is infeasible, in which case\n  mark the affected CAP as `blocked` and escalate; do not silently replace the\n  locked decision.\n\n## Senior Consequence Analysis Gate\n\nRun this gate whenever the request, artifact set, defect, or planned change can affect lifecycle operations, running objects, concurrent work, destructive behavior, shared state, downstream consumers, compatibility, security-sensitive behavior, or multiple plausible product behaviors.\n\nProject cognition first. Use the project cognition runtime to identify ownership, consumers, state surfaces, change-propagation facts, verification routes, conflicts, known unknowns, and coverage gaps. Senior consequence analysis second. Turn those facts into explicit product and implementation obligations instead of treating the graph as the decision-maker.\n\nProject cognition readiness provides routing advice. If readiness is `query_ready`, read top-level `minimal_live_reads` first, then use lane-level `first_pass_paths` reasons. If readiness is `review`, inspect the returned `minimal_live_reads` before continuing and treat `coverage_diagnostics` as confidence and closeout signals. If readiness is `needs_rebuild`, continue with live repository evidence and recommend `\u002Fsp-map-scan -> \u002Fsp-map-build` only for brownfield first\u002Fmissing\u002Funusable baseline, schema failure, schema v1 or old broad-schema rebuild-required readiness, zero active-generation `path_index` rows outside `greenfield_empty`, missing or invalid `alias_index`, `explicit_rebuild_requested`, or `baseline_identity_invalid`. If readiness is `blocked`, report the blocked state and continue with live repository evidence unless the user's actual request is to fix cognition runtime state. If readiness is `unsupported_runtime`, continue with live evidence and record that compass intake was unavailable. If `baseline_kind=greenfield_empty`, continue with workflow artifacts and live requirements; do not recommend map-scan -> map-build solely because the graph has no paths. Carry relevant project cognition facts, returned `minimal_live_reads`, inference notes, and coverage gaps into the workflow's artifacts or durable state, but back consequence claims with live code, tests, scripts, configuration, or authoritative docs. Mutation closeout is separate from entry routing: entry stale may continue, but that does not allow source\u002Fruntime mutation workflows to defer closeout. Workflow-owned mutation closeout is not an external map-maintenance handoff; after changing project-related files or behavior, the workflow must run inline project cognition update from its changed paths, affected surfaces, and verification evidence, with `project-cognition mark-dirty` only as fallback when inline update cannot complete. `sp-map-update` is for manual\u002Fexternal maintenance and follow-up repair; it is external map maintenance, not routine closeout for this workflow's own changes. In shared routing summaries, sp-map-update is for manual\u002Fexternal maintenance and ordinary existing-baseline gaps.\n\nRequired output when the gate triggers:\n\n- **Affected Object Map**: name each object, record, worker, queue, artifact, command, API, file surface, user-visible state, or downstream consumer that can be affected.\n- **State-Behavior Matrix**: describe behavior for each important lifecycle state, including created, queued, running, paused, failed, cancelled, completed, resumed, archived, missing, stale, or partially refreshed states when relevant.\n- **Dependency Impact Table**: map direct dependencies, indirect consumers, shared state, compatibility surfaces, validation routes, and adjacent workflows that can break if semantics change.\n- **Recovery And Validation Contract**: state rollback, retry, idempotency, cleanup, migration, observability, and validation evidence required before handoff or completion.\n- **Coverage Gaps**: list what project cognition or live evidence cannot prove, who must resolve each gap, the latest safe resolve phase, the stop-and-reopen condition, and the routing decision: current workflow may continue with an assumption, must ask the user, must route to clarification or deep research, or must request map maintenance.\n- **Consequence Obligations**: assign stable `CA-###` IDs to every obligation that must survive downstream handoff, task generation, worker packets, verification, or debug closeout. Each `CA-###` must include claim, affected objects, owner workflow, latest resolve phase, status, and stop-and-reopen condition.\n\nStand down only for docs-only wording changes, trivial isolated fixes, or local refactors that cannot affect lifecycle operations, running state, destructive operations, shared state, downstream consumers, compatibility, security, or multiple behavior choices. Record the no-trigger reason or stand-down reason in the workflow's durable artifact or closeout before skipping the required outputs.\n\nIf the gate triggers and the current workflow cannot preserve the required outputs, stop and route to the workflow that can. Do not mark ready, resolved, handoff-ready, planning-ready, or complete while triggered consequence obligations remain unresolved, unmapped, or unsupported by validation evidence.\n\n[AGENT] For project-cognition-backed semantic intake, routing, audit, resume, or final-claim gates, read `references\u002Fsemantic-work-contract.md`.\n\n## Detailed References\n\nRead [Reference index](references\u002FINDEX.md) before applying shared semantic contracts.\n\n- [semantic work contract](references\u002Fsemantic-work-contract.md)\n\n## Mandatory Subagent Execution\n\nAll substantive tasks in ordinary `sp-*` workflows default to and must use subagents.\n\nThe leader orchestrates: route, split tasks, prepare task contracts, dispatch subagents, wait for structured handoffs, integrate results, verify, and update state.\n\nBefore dispatch, every subagent lane needs a task contract with objective, authoritative inputs, allowed read\u002Fwrite scope, forbidden paths, acceptance checks, verification evidence, and structured handoff format.\n\nUse `execution_model: subagent-mandatory`.\nUse `dispatch_shape: one-subagent | parallel-subagents`.\nUse `execution_surface: native-subagents`.\n\n\n## Pre-Execution Checks\n\n**Check for extension hooks (before deep research)**:\n- Check if `.specify\u002Fextensions.yml` exists in the project root.\n- If it exists, read it and look for entries under the `hooks.before_deep_research` key.\n- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally.\n- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.\n- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:\n  - If the hook has no `condition` field, or it is null\u002Fempty, treat the hook as executable.\n  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation.\n- For each executable hook, output the following based on its `optional` flag:\n  - **Optional hook** (`optional: true`):\n    ```\n    ## Extension Hooks\n\n    **Optional Pre-Hook**: {extension}\n    Command: `\u002F{command}`\n    Description: {description}\n\n    Prompt: {prompt}\n    To execute: `\u002F{command}`\n    ```\n  - **Mandatory hook** (`optional: false`):\n    ```\n    ## Extension Hooks\n\n    **Automatic Pre-Hook**: {extension}\n    Executing: `\u002F{command}`\n    EXECUTE_COMMAND: {command}\n\n    Wait for the result of the hook command before proceeding to the Outline.\n    ```\n- If no hooks are registered or `.specify\u002Fextensions.yml` does not exist, skip silently.\n\n**Maintain workflow quality without hook choreography**:\n- Confirm project cognition freshness and valid workflow entry before deeper research begins.\n- Keep `workflow-state.md` current as the durable source of truth for phase, allowed artifact writes, next action, and exit criteria.\n- Verify the final `deep-research.md` and `workflow-state.md` outputs before handoff instead of relying on chat narration.\n- Update durable state before compaction-risk transitions, prototype-evidence synthesis handoffs, or any stop where resume will depend on more than the visible conversation.\n\n## Project Learning\n\nThe CLI is the only agent-facing Learning read surface:\n\n1. Run `uvx --from git+https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Fspec-kit-plus.git@4a631657f75460886dbd12ebe48b14fc11cfe0bf specify learning start --command \u003Cclassic-command-name> --format json` before deeper non-trivial work.\n2. Select summaries by applicability and triggers; use `uvx --from git+https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Fspec-kit-plus.git@4a631657f75460886dbd12ebe48b14fc11cfe0bf specify learning list --command \u003Cclassic-command-name> --format json` only to filter or page.\n3. Execute one matching card's `show_argv`. Do not parse Learning storage.\n\n`start`, `list`, and `show` are read-only. Current repository evidence,\n`.specify\u002Fmemory\u002Fconstitution.md`, and explicit user direction override stale or\ncandidate Learning.\n\nAt closeout, corrections, retries, route changes, recovery, false leads, hidden\ndependencies, validation\u002Ftooling\u002Fstate\u002Fcognition gaps, constraints, and near\nmisses are capture signals. Prefer `uvx --from git+https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Fspec-kit-plus.git@4a631657f75460886dbd12ebe48b14fc11cfe0bf specify learning capture-auto`\nfrom owning state; manual capture includes summary, problem, action, triggers,\nsuccess criteria, avoid items, exceptions, and evidence.\n\n- `fast`: skip unless the task escalates.\n- `accept`, `analyze`, `ask`, `auto`, `constitution`, `explain`,\n  `implement-teams`, `taskstoissues`, and `team`: consume-only; do not violate\n  their write boundaries to capture.\n- Other non-trivial workflows: consume before deeper work; capture reusable\n  signals at closeout or record a no-learning decision.\n\nThe `policy` returned by the CLI is authoritative when prompt wording drifts.\n\n## Workflow Phase Lock\n\n- [AGENT] Create or resume `WORKFLOW_STATE_FILE` before substantial research.\n- Read `.specify\u002Ftemplates\u002Fworkflow-state-template.md`.\n- If `WORKFLOW_STATE_FILE` already exists, read it first and preserve still-valid `next_action`, `exit_criteria`, and `next_command` details instead of relying on chat memory alone.\n- Treat `WORKFLOW_STATE_FILE` as the stage-state source of truth on resume after compaction for the current command, allowed artifact writes, forbidden actions, authoritative files, next action, and exit criteria.\n- Set or update the state for this run with at least:\n  - `active_command: sp-deep-research`\n  - `phase_mode: research-only`\n  - `allowed_artifact_writes: deep-research.md, research-spikes\u002F, alignment.md, context.md, references.md, workflow-state.md`\n  - `forbidden_actions: edit production source code, edit tests, fix build\u002Ftooling, implement behavior, commit prototype code as production`\n  - `authoritative_files: spec.md, alignment.md, context.md, references.md, deep-research.md`\n  - `track_exit_states`: per TRK-### exit state\n  - `evidence_packet_acceptance`: accepted and rejected packet lists with reasons\n  - `failed_readiness_checks`: list of check IDs that failed\n  - `open_gaps`: gap ID, description, severity, and linked CAP\u002FTRK IDs\n  - `entry_source`: `sp-specify` | `sp-clarify` (which command routed here)\n  - `research_mode`: `full-research` | `supplement-research`\n- Do not edit production code, production tests, migrations, release config, or implementation artifacts from `sp-deep-research`.\n- When resuming after compaction, re-read `WORKFLOW_STATE_FILE` before proceeding.\n\n## Multi-Agent Research Orchestration\n\n- [AGENT] Treat the current session as the research coordinator. The coordinator owns scope control, join points, conflict resolution, and the final `deep-research.md` synthesis.\n- [AGENT] Before delegating, split the feasibility problem into independent research tracks only when the tracks can run in parallel without sharing write targets. Good tracks include:\n  - repository implementation-pattern evidence\n  - external API\u002Flibrary\u002Fplatform feasibility\n  - data shape, migration, permission, performance, or integration constraints\n  - alternative approach comparison\n  - disposable demo\u002Fspike validation\n- [AGENT] Dispatch subagents when independent tracks can run in parallel and that materially improves evidence quality or speed. When the next coordinator decision is blocked on a single tightly coupled fact, either create one safe packetized evidence lane for that fact or stop for escalation\u002Frecovery with the blocker recorded.\n- [AGENT] Give each subagent one bounded track, one expected output shape, and one write scope. Research-only subagents should return evidence packets in their final response. Demo\u002Fspike subagents may write only under `FEATURE_DIR\u002Fresearch-spikes\u002F\u003Ctrack-slug>\u002F`.\n- [AGENT] Do not duplicate work across subagents. If two tracks overlap, assign one owner and ask the other to focus on a distinct risk or alternative.\n- [AGENT] Require every subagent to return an evidence packet with:\n  - `track`\n  - `question`\n  - `sources_or_repo_evidence`\n  - `finding`\n  - `confidence: high | medium | low`\n  - `planning_implications`\n  - `constraints_for_sp_plan`\n  - `rejected_options`\n  - `residual_risks`\n  - `spike_artifacts` when applicable\n- [AGENT] After each subagent returns, apply the evidence packet acceptance protocol:\n  - **ACCEPT** when: `paths_read` is non-empty, `finding` is specific and evidence-backed, core question is answered, and no production files were edited.\n  - **REJECT** when: `paths_read` is empty or missing, `finding` is empty or only speculative, core question is unanswered, or the subagent edited production source files.\n  - Record every acceptance and rejection in `workflow-state.md`.\n  - For rejected packets: retry once with clarified instructions. If the retry also fails, mark the track as `blocked`, record `subagent-blocked` with the rejection reason, and escalate.\n  - Do not silently ignore or synthesize rejected evidence packets.\n\n  ```markdown\n  ## Evidence Packet Acceptance\n\n  | Track | Subagent | Status | Reason if Rejected | Action |\n  |-------|----------|--------|--------------------|--------|\n  | TRK-001 | agent-1 | ACCEPTED | — | — |\n  | TRK-002 | agent-2 | REJECTED | No paths_read | Retry once |\n  | TRK-003 | agent-3 | REJECTED | Edited source file | BLOCKED, escalate |\n  ```\n- [AGENT] Join all subagent results before writing final conclusions. Resolve contradictions by preferring runnable spike evidence, current repository evidence, primary documentation, then secondary sources in that order. Mark conflicts that remain unresolved instead of hiding them.\n- [AGENT] The coordinator must convert subagent packets into `Research Agent Findings`, `Synthesis Decisions`, and `Planning Handoff`; do not paste raw subagent output as the final artifact.\n- [AGENT] After accepting a subagent evidence packet, persist it as\n  `FEATURE_DIR\u002Fresearch-evidence\u002F\u003CEVD-###>.json` with the full evidence packet\n  fields plus the evidence quality rubric. This enables:\n  - independent audit without re-parsing `deep-research.md`\n  - direct citation by `\u002Fsp.plan` via evidence ID\n  - safe context-compaction recovery\n- [AGENT] If subagent dispatch is unavailable or unsafe, record the decision as `subagent-blocked` with the concrete reason, preserve the decomposed tracks as blocked work, and stop for escalation or recovery instead of continuing as coordinator-only execution.\n\n## Traceability and Evidence Quality Contract\n\n- Assign stable IDs before running research so later planning can cite specific evidence instead of paraphrasing it:\n  - capability IDs: `CAP-001`, `CAP-002`, ...\n  - research track IDs: `TRK-001`, `TRK-002`, ...\n  - evidence IDs: `EVD-001`, `EVD-002`, ...\n  - spike IDs: `SPK-001`, `SPK-002`, ...\n  - Planning Handoff item IDs: `PH-001`, `PH-002`, ...\n- Use the IDs consistently across `Capability Feasibility Matrix`, `Research Agent Findings`, `Implementation Chain Evidence`, `Demo \u002F Spike Evidence`, `Synthesis Decisions`, and `Planning Handoff`.\n- Every handoff item must trace back to at least one evidence ID, spike ID, repository path, or source reference.\n- Grade each evidence item using this rubric:\n  - **Source tier**: `repo-evidence | runnable-spike | primary-docs | official-example | standard | secondary-source | inference`\n  - **Reproduced locally**: `yes | no | not applicable`\n  - **Recency**: [date, version, or `not time-sensitive`]\n  - **Confidence**: `high | medium | low`\n  - **Plan impact**: `blocking | constraining | informative`\n  - **Limitations**: [what the evidence does not prove]\n- Stop each research track when it reaches one of these exit states:\n  - `enough-to-plan`\n  - `constrained-but-plannable`\n  - `blocked`\n  - `not-viable`\n  - `user-decision-required`\n  - `stale-needs-revalidation` — prior evidence may no longer be valid due to dependency or platform changes\n- Do not continue researching a track once it has enough evidence to support a planning decision. Convert the result into a handoff item and move on.\n- For every spike, record the reproducibility contract:\n  - hypothesis\n  - setup\u002Fenv\n  - command\n  - expected result\n  - actual result\n  - cleanup note\n  - what this does not prove\n\n## Outline\n\n1. **Setup**: Run `.specify\u002Fscripts\u002Fpowershell\u002Fcheck-prerequisites.ps1 -Json -PathsOnly` from repo root once (`--json --paths-only` \u002F `-Json -PathsOnly`). Parse:\n   - If `FEATURE_DIR` is not already explicit, prefer `uvx --from git+https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Fspec-kit-plus.git@4a631657f75460886dbd12ebe48b14fc11cfe0bf specify lane resolve --command deep-research --ensure-worktree` before guessing from branch-only context.\n   - When lane resolution returns a materialized lane worktree, continue research from that isolated worktree context instead of assuming the leader workspace already matches the active feature lane.\n   - `FEATURE_DIR`\n   - `FEATURE_SPEC`\n   - optional downstream paths if returned\n   - If JSON parsing fails, abort and instruct the user to verify the feature branch environment.\n   - Set `ALIGNMENT_FILE` to `FEATURE_DIR\u002Falignment.md`.\n   - Set `CONTEXT_FILE` to `FEATURE_DIR\u002Fcontext.md`.\n   - Set `REFERENCES_FILE` to `FEATURE_DIR\u002Freferences.md`.\n   - Set `DEEP_RESEARCH_FILE` to `FEATURE_DIR\u002Fdeep-research.md`.\n   - Set `SPIKES_DIR` to `FEATURE_DIR\u002Fresearch-spikes`.\n   - Set `WORKFLOW_STATE_FILE` to `FEATURE_DIR\u002Fworkflow-state.md`.\n\n2. **Create or resume the workflow state**:\n   - Read `.specify\u002Ftemplates\u002Fworkflow-state-template.md`.\n   - If `WORKFLOW_STATE_FILE` already exists, read it first and preserve still-valid `next_action`, `exit_criteria`, and `next_command` details instead of relying on chat memory alone.\n   - Determine entry source:\n     - If the prior `active_command` in `workflow-state.md` was `sp-specify` →\n       `entry_source: sp-specify`, `research_mode: full-research`\n     - If the prior `active_command` was `sp-clarify` →\n       `entry_source: sp-clarify`, `research_mode: supplement-research`\n     - If undetermined → default to `full-research`\n   - In `supplement-research` mode, preserve existing evidence and only research\n     newly added or changed capabilities.\n   - Record entry source and research mode in `deep-research.md` Research\n     Orchestration section.\n   - Persist at least:\n     - `active_command: sp-deep-research`\n     - `phase_mode: research-only`\n     - `allowed_artifact_writes: deep-research.md, research-spikes\u002F, alignment.md, context.md, references.md, workflow-state.md`\n     - `forbidden_actions: edit production source code, edit tests, fix build\u002Ftooling, implement behavior, commit prototype code as production`\n     - `authoritative_files: spec.md, alignment.md, context.md, references.md, deep-research.md`\n\n3. **Load current spec package and repository context**:\n   - `FEATURE_SPEC`\n   - `FEATURE_DIR\u002Falignment.md`\n   - `FEATURE_DIR\u002Fcontext.md`\n   - `FEATURE_DIR\u002Freferences.md` if present\n   - `FEATURE_DIR\u002Fdeep-research.md` if present\n   - `.specify\u002Fmemory\u002Fconstitution.md` if present\n   - `.specify\u002Fmemory\u002Fproject-rules.md` if present\n   - compact `learning start --command deep-research` results and only selected `learning show` records\n   - **Project cognition gate:** query the active project's runtime before broad\n     repository reads.\n\n     Run or emulate:\n\n     ```text\n     C:\\Users\\11034\\.specify\\bin\\project-cognition.exe compass --intent research --query=\\\"$ARGUMENTS\\\" --format json\n     ```\n\n     After the default compass packet, run the advanced `lexicon -> semantic_intake -> query` path only when `compass_state`, coverage diagnostics, localization, or live evidence requires explicit concept decisions. In that escalation, use `project-cognition lexicon --mode catalog` as the alias catalog, write agent-authored `semantic_intake` and `concept_decisions`, then run `project-cognition query --query-plan \"\u003Cquery_plan_json>\"`; include `query_plan`, `semantic_intake`, `concept_decisions`, `covered_facets`, `missing_facets`, `match_sources`, `lexicon_generation_id`, `repository_search_terms`, project-language search terms, and facet coverage; do not search only the raw user words before source search. Agent-owned semantic normalization remains mandatory: `agent_normalization` and raw lexicon ranking are bootstrap signals only; if `agent_normalization` is omitted, treat it as `required=false`; use `write_semantic_intake_from_alias_catalog` when needed. Raw lexicon ranking is only a bootstrap; CJK or mixed CJK\u002FASCII input still requires agent-owned normalization even when positive raw lexical matches exist. The agent still owns translation. Readiness values are `query_ready`, `review`, `needs_rebuild`, `blocked`, and `unsupported_runtime`.\n\n     Use the returned readiness:\n\n     - `query_ready`: read top-level `minimal_live_reads` first, then use lane-level `first_pass_paths` reasons.\n     - `review`: perform only the returned `minimal_live_reads` before continuing and inspect `coverage_diagnostics`.\n     - `blocked`: report the blocking runtime issue and continue with live evidence only where this workflow allows degraded navigation.\n     - **CARRY FORWARD**: Treat project-cognition results as repository-grounded\n       starting context. Preserve cited capabilities, constraints, affected\n       surfaces, and verification routes in `deep-research.md`, and distinguish\n       repository facts from external research findings.\n   - From `FEATURE_DIR\u002Falignment.md`, extract:\n     - `Feasibility \u002F Deep Research Gate` status per capability\n     - `Planning Gate Recommendation`\n     - Capabilities marked `Needed before plan` → these are the research targets\n     - Capabilities marked `Not needed` or `Completed` → skip, do not research\n     - Capabilities marked `Blocked` → preserve blocker, record reason, do not research unless unblocked\n   - targeted live files only when the project cognition runtime cannot prove the current implementation pattern\n   - external docs, API references, release notes, examples, or research material when they materially affect feasibility\n\n3b. **Detect staleness and prior evidence**:\n    - If `FEATURE_DIR\u002Fdeep-research.md` already exists from a prior run, compare\n      new findings against prior conclusions.\n    - For each CAP with prior evidence, check whether dependencies (library\n      versions, API endpoints, platform behavior) have changed since the last\n      research pass.\n    - Mark CAPs with potentially stale evidence as `stale-needs-revalidation`\n      and prioritize their research tracks.\n    - Record staleness triggers (version bumps, deprecation notices, etc.) in\n      the track description.\n\n    ```markdown\n    ## Differential Evidence Analysis\n\n    | CAP ID | Previous Conclusion | Previous Evidence | New Evidence | Status Change |\n    |--------|--------------------|--------------------|--------------|---------------|\n    | CAP-001 | proven | EVD-001 | EVD-005 confirms | Unchanged |\n    | CAP-002 | constrained | EVD-002 | SPK-003 disproves | **OVERTURNED** → blocked |\n    | CAP-003 | proven (2026-03) | EVD-004 | lib X v3→v4 | **STALE** → revalidate |\n    ```\n\n4. **Decide whether this gate is needed**:\n   - Skip deep research and recommend `\u002Fsp.plan` when all target capabilities already have a known implementation path in the repository or the work is only a minor adjustment to existing behavior.\n   - When skipping, still write a lightweight `deep-research.md` using `**Status**: Not needed`, `Feasibility Decision`, `Planning Handoff`, and `Next Command`; do not invent `CAP\u002FTRK\u002FEVD\u002FPH` IDs for work that is already proven.\n   - Continue when any capability depends on an unproven API, library, algorithm, platform behavior, data volume, permission boundary, external integration, performance envelope, generated-code workflow, native\u002Fplugin bridge, or other path where planning would otherwise guess.\n   - If the uncertainty is a requirement gap rather than feasibility risk, recommend `\u002Fsp.clarify` and update `workflow-state.md` with that route reason.\n\n5. **Build a capability feasibility matrix from the spec's capability decomposition**:\n   - Start from the capability list in `spec.md`. Each spec capability maps to one CAP-###.\n   - Do not invent new capability names; use the spec's decomposition as the source of truth.\n   - If a spec capability is too broad for focused research, split it into sub-capabilities (CAP-001a, CAP-001b) and note the split in `alignment.md`.\n   - For each capability, read its feasibility status from `alignment.md` and take action:\n\n   | Alignment Status | Action |\n   |-----------------|--------|\n   | `Needed before plan` | Create research track, assign TRK-### |\n   | `Not needed` | Mark `proven` or `not needed`, skip |\n   | `Completed` | Preserve existing evidence, skip |\n   | `Blocked` | Record blocker, do not research |\n\n5b. **Consequence-Sensitive Research Tracks**:\n   - If the Senior Consequence Analysis Gate is triggered or upstream artifacts carry `CA-###` consequence obligations, create research tracks for any unproven affected object, state-behavior matrix entry, dependency impact, recovery behavior, validation route, or coverage gap that planning would otherwise guess.\n   - Each consequence-sensitive `TRK-###` must name the linked `CA-###` obligation, the stop-and-reopen condition it can clear or confirm, the evidence needed, and the downstream workflow that must consume the result.\n   - Research outputs must not drop `CA-###` consequence obligations; carry them into `Planning Handoff`, `Synthesis Decisions`, `Validation implications`, and residual risks until they are resolved or explicitly deferred.\n   - If evidence disproves an upstream consequence assumption, preserve the obligation as blocked, record the stop-and-reopen condition, and route back to `\u002Fsp.clarify` instead of handing ambiguous semantics to `\u002Fsp.plan`.\n   - When a consequence obligation is proven enough for planning, record the evidence ID, affected objects, lifecycle states covered, dependency impact, recovery and validation contract, remaining coverage gaps, and whether the obligation is still open.\n\n   For each capability or module slice, record:\n   - stable capability ID (`CAP-###`) — mapped from spec capability name\n   - capability name (from spec.md)\n   - desired outcome (from spec.md)\n   - current evidence from the repository\n   - unknown implementation-chain link\n   - research questions\n   - independent research track owner when delegation is useful\n   - whether a disposable demo is required\n   - proof target: what evidence would be enough to plan safely\n   - result status: `proven`, `constrained`, `not viable`, `blocked`, or `not needed`\n\n   Before finalizing the matrix, check each CAP against the preset research dimensions.\n   At minimum, confirm or mark \"not applicable\" for:\n   - permissions \u002F auth boundary\n   - data volume \u002F performance envelope\n   - error \u002F exception \u002F rollback flow\n   - concurrency \u002F consistency\n   - logging \u002F observability\n   - migration \u002F compatibility\n   - external dependency SLO \u002F failure mode\n   - template \u002F generated-code propagation\n   - minimum verifiable test path\n\n6. **Select the research dispatch shape**:\n   - [AGENT] Before research fan-out begins, assess workload shape and the current agent capability snapshot, then apply the shared policy contract: `choose_subagent_dispatch(command_name=\"deep-research\", snapshot, workload_shape)`.\n   - Persist the decision fields exactly: `execution_model: subagent-mandatory`, `dispatch_shape: one-subagent | parallel-subagents`, `execution_surface: native-subagents`.\n   - Decision order is fixed:\n     - One safe validated track -> `one-subagent` on `native-subagents` when available.\n     - Two or more safe isolated tracks -> `parallel-subagents` on `native-subagents` when available.\n     - No safe lane, overlapping write scopes, missing contract, or unavailable delegation -> `subagent-blocked` with a recorded reason.\n   - For `deep-research`, safe fan-out means at least two independent research tracks with disjoint write scopes. Research-only tracks return evidence packets; demo tracks write only under their assigned `FEATURE_DIR\u002Fresearch-spikes\u002F\u003Ctrack-slug>\u002F`.\n   - Required join points:\n     - before final conflict resolution\n     - before writing `Synthesis Decisions`\n     - before writing `Planning Handoff`\n   - Record the chosen strategy, reason, any `subagent-blocked` condition, selected research tracks, write scopes, and join points in `deep-research.md`.\n   - Keep the shared workflow language integration-neutral. Do not present Codex-only runtime surface wording in this shared template.\n\n7. **Plan and run coordinated research**:\n   - Create research tracks from the capability matrix before searching broadly.\n   - For each track, assign a stable track ID (`TRK-###`) and define the exact question, evidence target, likely sources, whether a spike is needed, and how the result will affect `\u002Fsp.plan`.\n   - If two or more tracks are independent and subagent dispatch is available, dispatch bounded subagents according to the Multi-Agent Research Orchestration contract.\n   - If subagent dispatch is unavailable or low-confidence, record `subagent-blocked`, capture which tracks could not be dispatched, and stop before substantive research until the block is resolved or explicitly escalated.\n   - Search and read only sources that answer a named feasibility question.\n   - Prefer primary docs, official examples, standards, changelogs, release notes, library docs, code examples from the dependency itself, and current repository evidence.\n   - Cite external sources in `references.md` and summarize how each source affects the implementation chain.\n   - Separate facts from inference. If one source is weak or unverified, say so.\n   - Preserve rejected alternatives with explicit reasons when they matter to planning.\n   - Convert every completed track into an evidence packet with stable evidence IDs (`EVD-###`), evidence quality ratings, limitations, and a track exit state.\n\n8. **Run isolated demo validation when needed**:\n   - Assign a stable spike ID (`SPK-###`) and create the smallest runnable spike under `SPIKES_DIR` when docs and repository evidence cannot prove feasibility.\n   - Keep the spike intentionally disposable: no production imports unless read-only, no edits outside `FEATURE_DIR\u002Fresearch-spikes\u002F`, no migration or test-suite changes.\n   - Define the spike before writing it:\n     - hypothesis\n     - inputs \u002F fixture data\n     - setup\u002Fenv\n     - expected pass condition\n     - commands to run\n     - actual result capture format\n     - cleanup or non-persistence note\n     - what this does not prove\n   - Run the spike command if the local environment supports it.\n   - Capture command, exit status, relevant output summary, and evidence path in `deep-research.md`.\n   - If the environment cannot run the spike, record exactly what is missing and whether planning can still proceed with a manual-risk note.\n\n9. **Synthesize research into planning decisions**:\n   - Compare evidence packets across tracks.\n   - Resolve conflicts and record why one source or demo result won over another.\n   - Record every conflict and its resolution in the `Contradiction Resolution Log`.\n   - Unresolved conflicts must be marked `BLOCKED` and escalated; do not hide them.\n   - Identify the recommended approach, rejected approaches, and constraints `\u002Fsp.plan` must preserve.\n   - Translate demo observations into planning implications rather than leaving them as raw logs.\n   - Identify module boundaries, API\u002Flibrary choices, data flow notes, operational constraints, and validation implications that planning must account for.\n   - Assign stable Planning Handoff IDs (`PH-###`) to each decision or constraint that `\u002Fsp.plan` must consume.\n\n10. **Write `deep-research.md`**:\n   Use `.specify\u002Ftemplates\u002Fexamples\u002Fdeep-research\u002F` as the output-shape reference when available:\n   - `not-needed.md` for `**Status**: Not needed`\n   - `docs-only-evidence.md` when repository evidence and primary documentation are enough\n   - `spike-required.md` when a disposable demo proves the implementation chain\n\n   Use the lightweight structure below only when the gate is not needed:\n\n   ```markdown\n   # Deep Research: [FEATURE NAME]\n\n   **Feature Branch**: `[###-feature-name]`\n   **Created**: [DATE]\n   **Status**: Not needed\n\n   ## Feasibility Decision\n\n   - **Recommendation**: Proceed to `\u002Fsp.plan`\n   - **Reason**: [Why repository evidence already proves the implementation chain]\n   - **Planning handoff readiness**: Not needed\n\n   ## Planning Handoff\n\n   - **Handoff IDs**: Not needed\n   - **Status**: All capabilities have proven implementation chains in repository\n   - **Recommended approach**: [Existing implementation path `\u002Fsp.plan` should use]\n   - **Constraints `\u002Fsp.plan` must preserve**: [Existing boundary, behavior, or constraint]\n   - **PH items**: None (all capabilities proven — no research-generated handoff items)\n\n   ## Planning Handoff Readiness Checklist\n\n   - [ ] All capabilities have proven implementation chains in repository\n   - [ ] `alignment.md` updated with `Not needed` feasibility status\n   - [ ] `context.md` updated\n   - [ ] `workflow-state.md` updated with `next_command: \u002Fsp.plan`\n\n   ## Next Command\n\n   - `\u002Fsp.plan`\n   ```\n\n   Use the full structure below when any capability needed research, evidence, or a disposable spike:\n\n   ```markdown\n   # Deep Research: [FEATURE NAME]\n\n   **Feature Branch**: `[###-feature-name]`\n   **Created**: [DATE]\n   **Status**: [Ready for plan | Ready for plan with constraints | Blocked | Not needed]\n\n   ## Feasibility Decision\n\n   - **Recommendation**: [Proceed to `\u002Fsp.plan` | Proceed with constraints | Run `\u002Fsp.clarify` | Stop \u002F redesign]\n   - **Reason**: [Short evidence-based rationale]\n   - **Planning handoff readiness**: [Complete | Complete with constraints | Incomplete]\n\n   ## Capability Feasibility Matrix\n\n   | Capability ID | Capability | Unknown Link | Evidence Needed | Proof Method | Result |\n   | --- | --- | --- | --- | --- | --- |\n   | CAP-001 | [Name] | [What was uncertain] | [Proof target] | [docs \u002F repo evidence \u002F demo] | [proven \u002F constrained \u002F blocked \u002F not needed] |\n\n   ## Research Orchestration\n\n   - **Execution model**: subagent-mandatory\n   - **Dispatch shape**: [one-subagent | parallel-subagents | subagent-blocked]\n   - **Execution surface**: native-subagents\n   - **Reason**: [safe-one-subagent | safe-parallel-subagents | native-subagents-supported | no-safe-delegated-lane | unsafe-write-sets | packet-not-ready | runtime-no-subagents | low-delegation-confidence]\n   - **Selected tracks**:\n     - [track] -> [research-only evidence packet | demo spike write scope]\n   - **Join points**:\n     - before final conflict resolution\n     - before writing `Synthesis Decisions`\n     - before writing `Planning Handoff`\n\n   ## Research Agent Findings\n\n   | Track ID | Agent \u002F Mode | Question | Evidence IDs | Confidence | Exit State | Planning Implication |\n   | --- | --- | --- | --- | --- | --- | --- |\n   | TRK-001 | [child agent name or subagent-blocked status] | [Question] | EVD-001, SPK-001 | [high \u002F medium \u002F low] | [enough-to-plan \u002F constrained-but-plannable \u002F blocked \u002F not-viable \u002F user-decision-required] | [What `\u002Fsp.plan` must use] |\n\n   ## Evidence Quality Rubric\n\n   | Evidence ID | Supports | Source Tier | Source \u002F Path | Reproduced Locally | Recency \u002F Version | Confidence | Plan Impact | Limitations | Persisted |\n   | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n   | EVD-001 | CAP-001 \u002F PH-001 | [repo-evidence \u002F runnable-spike \u002F primary-docs \u002F official-example \u002F standard \u002F secondary-source \u002F inference] | [URL, file path, or spike path] | [yes \u002F no \u002F not applicable] | [date\u002Fversion\u002Fnot time-sensitive] | [high \u002F medium \u002F low] | [blocking \u002F constraining \u002F informative] | [what this does not prove] | research-evidence\u002FEVD-001.json |\n\n   ## Implementation Chain Evidence\n\n   ### [Capability Name]\n\n   - **Capability ID**: CAP-001\n   - **Chain**: [trigger\u002Finput -> module\u002FAPI\u002Flibrary -> state\u002Foutput -> validation]\n   - **Repository evidence**: [EVD IDs, files, patterns, existing behavior]\n   - **External evidence**: [EVD IDs, source links or references.md entries]\n   - **Demo evidence**: [SPK IDs, spike path and command result, or not needed]\n   - **Planning constraints**: [rules `\u002Fsp.plan` must preserve]\n   - **Residual risk**: [remaining uncertainty]\n\n   ## Demo \u002F Spike Evidence\n\n   - **Spike ID**: SPK-001\n   - **Spike**: [name]\n   - **Hypothesis**: [what it proves]\n   - **Path**: `research-spikes\u002F[name]`\n   - **Setup \u002F env**: [runtime, dependency, fixture, credentials placeholder, or not required]\n   - **Command**: `[command]`\n   - **Expected result**: [observable pass condition]\n   - **Actual result**: [passed \u002F failed \u002F not run, with summary]\n   - **Evidence summary**: [short result]\n   - **Cleanup note**: [what remains disposable or how to remove it]\n   - **What this does not prove**: [limits of the spike]\n   - **Planning implication**: [what design or validation decision follows]\n\n   ## Spike Log\n\n   - **Spike**: [name]\n   - **Hypothesis**: [what it proves]\n   - **Path**: `research-spikes\u002F[name]`\n   - **Command**: `[command]`\n   - **Result**: [passed \u002F failed \u002F not run]\n   - **Evidence summary**: [short result]\n\n   ## Synthesis Decisions\n\n   - **Recommended approach**: [PH-001 -> approach and why]\n   - **Rejected options**:\n     - [option] -> [evidence-based reason and evidence IDs]\n   - **Conflict resolution**:\n     - [conflict] -> [resolution and evidence priority]\n   - **Plan constraints**:\n     - PH-### -> [constraint `\u002Fsp.plan` must preserve]\n\n   ## Contradiction Resolution Log\n\n   When two or more evidence items produce conflicting findings, record the\n   resolution. Unresolved contradictions must be marked `BLOCKED` and escalated.\n\n   | Conflict | Evidence A | Evidence B | Resolution | Priority Basis | Suppressed Reason |\n   |----------|-----------|-----------|------------|----------------|-------------------|\n   | [e.g. API version] | EVD-002: v3 | EVD-005: v2 | v3 accepted | spike > docs | EVD-005 was outdated |\n   | [unresolved] | EVD-007: pattern A | SPK-003: pattern B | **BLOCKED** | — | Contradictory runnable evidence |\n\n   ## Planning Handoff\n\n   - **Handoff IDs**: PH-001, PH-002, ...\n   - **Recommended approach**: PH-001 -> [implementation direction `\u002Fsp.plan` should start from; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Architecture implications**: PH-002 -> [components, layering, boundaries, sequencing; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Module boundaries**: PH-003 -> [owners and interfaces to preserve; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **API \u002F library choices**: PH-004 -> [selected APIs\u002Flibraries and why; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Data flow notes**: PH-005 -> [inputs, state, outputs, side effects; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Demo artifacts to reference**: PH-006 -> [`research-spikes\u002F...` and command result; trace to SPK IDs]\n   - **Constraints `\u002Fsp.plan` must preserve**:\n     - PH-### -> [constraint; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Validation implications**: PH-### -> [tests\u002Fchecks the plan should include later; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Residual risks requiring design mitigation**:\n     - PH-### -> [risk; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n   - **Decisions already proven by research**:\n     - PH-### -> [decision; trace to CAP\u002FTRK\u002FEVD\u002FSPK IDs]\n\n   - **PH consumption contract**:\n     - `mandatory` — `\u002Fsp.plan` must consume this PH; omitting it is a plan error.\n     - `optional` — `\u002Fsp.plan` may defer if the plan does not need it.\n     - `user-decision` — `\u002Fsp.plan` must ask the user before consuming or deferring.\n\n     Each PH item in the Traceability Index must carry its consumption contract in\n     the `Mandatory?` column.\n\n   ## Capability Cards\n\n   For each high-value or planning-critical capability, emit a capability card:\n\n   ### CAP-001: [Capability Name]\n\n   | Field | Detail |\n   |-------|--------|\n   | **Purpose** | [What this capability achieves] |\n   | **Owner** | [Owning module \u002F service \u002F surface] |\n   | **Truth lives** | [Code path, data table, config, or external service] |\n   | **Entry points** | [CLI command, API route, event handler, hook] |\n   | **Downstream consumers** | [What depends on this capability] |\n   | **Extend here** | [Safe extension points] |\n   | **Do not extend here** | [Fragile or contract-locked areas] |\n   | **Key contracts** | [Input shape, output shape, side effects, invariants] |\n   | **Change propagation** | [What breaks when this changes] |\n   | **Minimum verification** | [Command or check that proves this works] |\n   | **Failure modes** | [Known ways this can fail] |\n   | **Confidence** | [Verified \u002F Inferred \u002F Unknown-Stale] |\n\n   ## Research Exclusions\n\n   Areas, surfaces, or dimensions intentionally not researched in this pass.\n\n   | Excluded Area | Reason | Revisit Condition | Recorded By |\n   |---------------|--------|-------------------|-------------|\n   | [e.g. performance profiling] | [Not in feature scope] | [Before production deploy] | [Coordinator \u002F TRK-###] |\n\n   Every unverified dimension from the preset research checklist that was marked\n   \"not applicable\" or \"deferred\" must appear here with a revisit condition.\n\n   ## Planning Traceability Index\n\n   | PH ID | CAP ID | TRK ID | Evidence IDs | Evidence Quality | Plan Consumer | Required Plan Action | Mandatory? |\n   |-------|--------|--------|-------------|-------------------|---------------|----------------------|------------|\n   | PH-001 | CAP-001 | TRK-001 | EVD-001, SPK-001 | HIGH \u002F blocking | architecture | Use pattern X | mandatory |\n   | PH-002 | CAP-001 | TRK-002 | EVD-003 | MEDIUM \u002F constraining | data-model | Consider limit Y | optional |\n\n   ## Sources\n\n   - [Source title](URL) -> [why it matters]\n\n   ## Planning Handoff Readiness Checklist\n\n   - [ ] All CAPs have explicit exit status (`proven` \u002F `constrained` \u002F `blocked` \u002F `not-viable`)\n   - [ ] All PH items trace to evidence (EVD\u002FSPK\u002Frepo path)\n   - [ ] All spike results recorded with pass\u002Ffail outcome\n   - [ ] All residual risks explicitly linked to evidence IDs\n   - [ ] All research exclusions have revisit conditions\n   - [ ] `alignment.md` updated with feasibility result and Planning Gate Recommendation\n   - [ ] `context.md` updated with implementation-chain evidence, constraints, rejected options\n   - [ ] `references.md` updated with external sources\n   - [ ] `workflow-state.md` updated with exit criteria and `next_command`\n   - [ ] Reverse Coverage Validation passed (all CAP→PH→Evidence chains closed)\n   - [ ] Readiness Refusal Rules all PASS\n\n   ## Next Command\n\n   - [`\u002Fsp.plan` | `\u002Fsp.clarify` | stop with blocker]\n   ```\n\n11. **Update upstream artifacts when research changes planning readiness**:\n   - Update `alignment.md`:\n     - add feasibility result, capability status, implementation-chain confidence, Planning Handoff readiness, and Planning Gate Recommendation\n     - recommend `\u002Fsp.deep-research` only when more feasibility work remains\n     - recommend `\u002Fsp.plan` only when every planning-critical capability is proven, constrained enough, not needed, or explicitly force-accepted\n   - Update `context.md`:\n     - add implementation-chain evidence, Planning Handoff summary, spike paths, external constraints, rejected options, and residual risks that `\u002Fsp.plan` must preserve\n   - Update `references.md`:\n     - add external sources and reusable insights\n\n12. **Run an artifact review gate**:\n    - Review `deep-research.md`, `alignment.md`, and `context.md` for:\n      - unproven capability chains presented as facts\n      - demos with no pass condition\n      - source claims without source attribution\n      - subagent findings copied without coordinator synthesis\n      - missing or vague research orchestration strategy when multiple tracks were available\n      - missing `Planning Handoff` decisions for capabilities that affect plan structure\n      - production-code edits from the research phase\n      - feasibility risks not reflected in the Planning Gate Recommendation\n    - If issues remain, revise the artifacts before handoff.\n\n12b. **Run reverse coverage validation**:\n    - Prove every CAP has at least one PH-ID.\n    - Prove every PH-ID traces back to at least one evidence item (`EVD-###`, `SPK-###`, or live repository path).\n    - Prove every `proven` CAP has no remaining unresolved unknown links.\n    - Prove every `blocked` CAP has a concrete block reason and next action.\n    - Prove every accepted evidence packet was consumed by at least one PH or explicitly deferred.\n    - If any check fails, refuse handoff and write gaps back to `workflow-state.md`.\n\n    ```markdown\n    ## Reverse Coverage Validation\n\n    | CAP ID | Has PH? | PH IDs | Has Evidence? | Evidence IDs | Proven \u002F Clean? |\n    |--------|---------|--------|---------------|-------------|-----------------|\n    | CAP-001 | PASS | PH-001, PH-002 | PASS | EVD-001, SPK-001 | PASS |\n    | CAP-002 | FAIL | — | — | — | FAIL: No PH assigned |\n\n    **Decision**: [PASS \u002F FAIL — if FAIL, refuse handoff]\n    ```\n\n13. **Write or update `WORKFLOW_STATE_FILE`**:\n    - Record:\n      - `active_command: sp-deep-research`\n      - `phase_mode: research-only`\n      - current authoritative files\n      - exit criteria for feasibility completion\n      - next action required before handoff\n      - `next_command` as `\u002Fsp.plan`, `\u002Fsp.clarify`, or `\u002Fsp.deep-research`\n\n14. **Report completion**:\n    - branch or feature directory\n    - deep-research artifact path\n    - spike paths and command results, if any\n    - research tracks and subagent evidence packet summary, if any\n    - proven capabilities\n    - constrained or blocked capabilities\n    - Planning Handoff summary for `\u002Fsp.plan`\n    - updated alignment\u002Fcontext\u002Freference paths\n    - recommended next command\n    - whether the feature is ready for `\u002Fsp.plan`\n    - [AGENT] before final completion text, if auto-capture did not preserve a reusable `workflow_gap`, `project_constraint`, or `decision_debt`, use the manual `learning capture` helper surface.\n      Required options: `--command`, `--type`, `--summary`, `--evidence`\n    - Use the user's current language for explanatory text while preserving literal command names, file paths, and fixed status values exactly as written.\n\n## Readiness Refusal Rules\n\nBefore writing final `deep-research.md` and recommending `\u002Fsp.plan`, run every\ncheck below. If **any** check fails, refuse handoff, produce a gap report, and\nset `next_command` to `\u002Fsp.clarify` or mark the phase as blocked.\n\n- [ ] Every CAP has at least one PH-ID assigned\n- [ ] Every PH-ID traces to at least one evidence ID (`EVD-###`, `SPK-###`, or live repository path)\n- [ ] No CAP remains `blocked` without an explicit user force-accept recorded in `alignment.md`\n- [ ] No `proven` CAP still has unresolved unknown links in its implementation chain\n- [ ] Every dispatched subagent returned an accepted evidence packet; rejected packets were retried or escalated\n- [ ] `dispatch_shape: subagent-blocked` is recorded with a concrete block reason and escalation path\n- [ ] Every spike with a defined hypothesis was run and has a captured pass\u002Ffail result\n\nWhen refusal happens, output a gap report inline before the refusal decision:\n\n```markdown\n## Readiness Refusal Report\n\n| Check | Status | Affected IDs | Missing \u002F Reason |\n|-------|--------|-------------|-------------------|\n| All CAPs have PH | FAIL | CAP-003 | No PH assigned |\n| All PHs trace to evidence | FAIL | PH-005 | No EVD\u002FSPK\u002Frepo path |\n| ... | PASS | — | — |\n\n**Decision**: Handoff refused. Next command: `\u002Fsp.clarify`\n```\n\n## Rules\n\n- Use this command to produce research evidence and a planning handoff, not to design the full architecture.\n- Prefer a small, runnable proof over broad speculative prose when the question is \"can this work?\"\n- Disposable demos, research spikes, and proof artifacts validate feasibility for the user's intended capability. They are not a replacement product scope and must not be reframed as the delivered product unless the user explicitly confirms that reduced scope.\n- Do not require this command for existing capability tweaks where the repository already shows the path.\n- Do not advance to `\u002Fsp.plan` when a required capability is still `blocked` or `not viable` unless the user explicitly accepts a redesign or force-proceed risk.\n- Keep all prototype work isolated under `FEATURE_DIR\u002Fresearch-spikes\u002F`.\n- Do not edit source code, tests, migrations, or production config from this command.\n- Do not hand off to `\u002Fsp.plan` with only raw research notes; synthesize findings into `Planning Handoff`, constraints, rejected options, and residual risks.\n- If this workflow makes actual source\u002Fruntime\u002Ftemplate\u002Fconfig\u002Ftest\u002Fgenerated-asset changes in the current run, follow the shared inline closeout contract:\n\n### Inline Project Cognition Update\n\nWorkflow-owned mutation closeout is not an external map-maintenance handoff and is not external map maintenance. It is the workflow-local form of `\u002Fsp-map-update`. If this workflow changed project-related source, runtime, templates, generated assets, config, tests, state contracts, shared surfaces, or behavior-bearing docs, closeout MUST run inline project cognition update for the workflow-owned changed paths and affected surfaces before claiming clean completion.\n\nCall the planner first:\n\n```text\nproject-cognition closeout-plan --workflow \"$ACTIVE_WORKFLOW\" --format json\n```\n\nWhen `DELTA_SESSION_ID` exists, pass it into the planner:\n\n```text\nproject-cognition closeout-plan --workflow \"$ACTIVE_WORKFLOW\" --delta-session \"$DELTA_SESSION_ID\" --format json\n```\n\nConsume `workflow_canonical`, `update_mode`, `payload_draft`, `required_agent_fields`, `unknown_paths`, `unknown_path_dispositions`, `delta_append_draft`, display-only `delta_append_command`, `update_argv`, display-only `update_command`, and `recommended_next_command`.\n\nBefore running `update`, fill the fields listed in `required_agent_fields` from live evidence from this workflow. Supported agent-owned evidence fields include:\n\n- `verification`\n- `behavior_surfaces`\n- `generated_surfaces`\n- `state_contracts`\n- `known_unknowns`\n- `confidence_notes`\n- `user_decisions`\n- `boundary`\n\nIf a field appears in `required_agent_fields`, provide live-evidence-backed content for it. Fields not listed by `required_agent_fields`, such as `known_unknowns` and `boundary`, are populated only when live evidence supports them; do not invent them to satisfy the shape.\nUse `known_unknowns` only for blockers that make the cognition update unsafe to trust. If the working tree contains unrelated dirty\u002Funtracked paths and the workflow uses explicit workflow-owned paths, record that as `confidence_notes` or `boundary.initial_dirty_paths`, not as a blocking `known_unknowns` item.\n\nFor each `unknown_path_dispositions[]` item, set `agent_disposition` to exactly one allowed value:\n\n- `adoptable`: verified new path inside this workflow-owned scope; it may be recorded in changed\u002Fscope paths and verified adoptable paths do not become blocking `known_unknowns`.\n- `review_only`: path informed review but is not adopted into changed coverage.\n- `ignored`: path remains excluded and must not enter payloads, records, route indexes, evidence, aliases, or minimal live reads.\n- `blocking_known_unknown`: record it as a known unknown and report partial or blocked cognition closeout.\n\n`agent_disposition=adoptable` is an agent accounting decision, not proof that runtime indexing already succeeded. Runtime adoption still requires a usable active project-cognition DB, at least one passing verification evidence item, and no blocking `known_unknowns`. After `update_argv` runs, inspect `result_state`, `adopted_paths`, `review_paths`, `minimal_live_reads`, and `partial_refresh_reasons`; do not explain a remaining `partial_refresh` as \"path_index missing\" until those fields show which adoption gate failed.\n\nIf `update_mode=delta_session`, complete `delta_append_draft.argv_prefix` with agent-owned repeatable flags such as `--behavior-surface`, `--generated-surface`, `--verification`, and accepted `--known-unknown` values from `delta_append_draft.argv_placeholders`. Then append the delta event and run `update_argv`. `delta_append_command` and `update_command` are display-only placeholders, not execution strings.\n\nIf `update_mode=payload_file`, write the completed `payload_draft` to the planner's `payload_path`. Then run `update_argv`. `update_command` is a display-only placeholder, not an execution string.\n\nCompleted payload drafts preserve the planner-owned `changed_paths` and `scope_paths` and add agent-owned evidence fields before recording.\n\nStructured `update` invalidates related claims and returns their stable IDs in `affected_graph_claims`. This is separate from update readiness: generic workflow verification and `result_state=ready` must not re-promote stale or contradicted graph claims. Only when this workflow already has decisive claim-specific bounded live evidence for an exact returned claim ID may it submit semantic reconciliation intent and run:\n\n```text\nproject-cognition claim-reconcile prepare --input \u003Cintent.json> --format json\nproject-cognition claim-reconcile apply --input \u003Cprepared_packet_path> --format json\n```\n\nProvide only reconciliation intent: workflow, stable `claim_id`, reason, and evidence containing repository-relative `source_path`, bounded line `span`, and `supporting` or `contradicting` role. Add verification only when it is claim-specific. The runtime owns the contract version, active generation, expected state and revision, UTC observation and expiry, source kind, content hashes, repository snapshot, IDs, and prepared packet path. Do not author or edit those integrity fields; execute the returned `apply_argv` exactly. If no such evidence exists, leave the claim stale. If reconciliation returns ready, rerun Compass once so later routing consumes the current evidence basis; partial or blocked reconciliation remains withheld and follows `recommended_next_action`.\n\nFor compatibility with worker handoffs and delta packets, the runtime also accepts `verification_evidence` as an alias for `verification` and `generated_surface_notes` as an alias for `generated_surfaces`. Verification evidence may be an array of objects (`command`, `result`, `artifact`) or an array of command-result strings, but clean closeout still requires passing verification evidence; failed verification cannot produce a clean `ready` closeout.\n\nClean closeout keys on `result_state`, not `status=ok`, `update_id`, `last_update_id`, or freshness alone:\n\n- `ready` or `no_op`: project cognition closeout may be clean when ordinary verification also passed.\n- `partial_refresh`: useful update data was written, but the final workflow state must report partial cognition closeout, `partial_refresh_reasons`, and the returned `minimal_live_reads`. If `partial_refresh_reasons` includes `missing_passing_verification_result`, repair the payload or delta evidence and rerun `update_argv` before final closeout; do not route that to `sp-map-update`. If verified workflow-owned paths still remain in `review_paths` after the update, report implementation completion separately from project-cognition maintenance and name `\u002Fsp-map-update` as follow-up repair.\n- `needs_rebuild`: report the exact rebuild condition and route to `\u002Fsp-map-scan`, then `\u002Fsp-map-build`.\n- `blocked`: report the runtime or validation blocker and the exact recovery command.\n- `recorded`: legacy recorded-only output; treat it as partial or blocked, never as clean completion.\n\nNever run the `complete-refresh` or `clear-dirty` helper after `result_state=partial_refresh`, `needs_rebuild`, `blocked`, or legacy `recorded`; those helpers are only for states that the runtime and validation prove ready.\n\nDirty fallback command shape: `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe mark-dirty --reason \\\"\u003Creason>\\\" --format json`.\nUse `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe mark-dirty --reason \\\"workflow-closeout-failed\\\" --format json` only when inline update cannot complete: when the planner or update command is unavailable, cannot record useful update data, cannot identify workflow-owned scope, or cannot be trusted because verification\u002Fworkflow completion is not trustworthy. Dirty only when inline update cannot complete.\n\nsp-map-update is for manual\u002Fexternal maintenance and follow-up repair. `\u002Fsp-map-update` remains the external\u002Fmanual workflow for user edits, interrupted workflow repair, explicit map maintenance, and follow-up repair. It is not routine cleanup for changes this workflow just made. If `sp-map-update` already ran `project-cognition update --reason map-update` for the same changed paths, do not run a second `workflow-finalize` closeout update for those paths.\n\n## Post-Execution Checks\n\n**Check for extension hooks (after deep research)**:\n- Check if `.specify\u002Fextensions.yml` exists in the project root.\n- If it exists, read it and look for entries under the `hooks.after_deep_research` key.\n- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally.\n- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.\n- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:\n  - If the hook has no `condition` field, or it is null\u002Fempty, treat the hook as executable.\n  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation.\n- For each executable hook, output the following based on its `optional` flag:\n  - **Optional hook** (`optional: true`):\n    ```\n    ## Extension Hooks\n\n    **Optional Hook**: {extension}\n    Command: `\u002F{command}`\n    Description: {description}\n\n    Prompt: {prompt}\n    To execute: `\u002F{command}`\n    ```\n  - **Mandatory hook** (`optional: false`):\n    ```\n    ## Extension Hooks\n\n    **Automatic Hook**: {extension}\n    Executing: `\u002F{command}`\n    EXECUTE_COMMAND: {command}\n    ```\n- If no hooks are registered or `.specify\u002Fextensions.yml` does not exist, skip silently.\n\n## Claude Code Subagent Capability Discovery\n\n- Execution model: preserve the workflow's existing `subagent-mandatory`, `subagents-first`, `adaptive`, or `subagent-assisted` policy.\n- Dispatch shape: preserve the workflow's existing dispatch shape; use `subagent-blocked` only after the discovery step below fails or is unsafe.\n- Execution surface: prefer `native-subagents` when the current runtime supports it; use `none` only after recording the unavailable or unsafe surface.\n- Native subagent capability discovery: Before recording `subagent-blocked`, check the active tool surface for the integration-native subagent or task-dispatch entrypoint and record the exact missing surface if unavailable.\n- Do not record `subagent-blocked` until this capability discovery step is complete and the exact unavailable or unsafe surface is recorded.\n- Native subagent dispatch: Dispatch subagents through the integration's native subagent support using the shared prompt contract.\n- Join behavior: Use the integration-native join point, then integrate results back on the leader path.\n- Preserve this workflow's existing packet, handoff, artifact, and result schema; this section only governs capability discovery before dispatch or blocked-state recording.\n\n## Claude Code Structured Question Preference\n\n- If this command was routed by `sp-auto` with `auto_default_recommendation: true`, evaluate the automatic recommended\u002Fdefault continuation gate before any question path.\n- When that gate has one safe recommended\u002Fdefault answer, you must auto-resolve the question or confirmation, record the accepted recommendation in the workflow state or summary, continue the workflow, and do not invoke the native structured question tool only to ask for that approval.\n- If the automatic gate is not safe, write the blocker and self-unblock recommendation before using the normal question path.\n- If the runtime's native structured question tool is available for the current turn and the `sp-auto` automatic gate did not resolve the question, you must use it.\n- Do not render the textual fallback block when the native tool is available.\n- Do not self-authorize textual fallback because the question seems simple, short, or easy to phrase manually.\n- Treat the template's textual question format as fallback-only guidance; use it to shape the question content, but do not render the textual block unless the native tool is unavailable in the current runtime or the tool call fails.\n- Keep native-tool availability, runtime mode, and fallback mechanics backstage. Do not tell the user that a structured question tool is unavailable, that the current runtime\u002Fmode lacks a tool, or that a fallback is being used; ask the user-facing question directly when a question is genuinely required.\n- Ask only the minimum number of questions required by this workflow's existing contract.\n- Keep the user-visible question text in the user's current language and keep option labels short.\n- Do not emit both a native tool question and the textual fallback block in the same turn. The user should see the active question exactly once.\n- If the native tool is unavailable in the current runtime or the tool call fails, ask one concise plain-text question about the missing feasibility or research-track decision, then continue with the existing research workflow.\n- In `deep-research`, use this preference for:\n  - whether the feasibility question is actually a requirement gap\n  - minimum research tracks needed before planning\n  - manual confirmation before force-proceeding with unresolved feasibility risk\n- Native tool target: `AskUserQuestion`\n- When this native tool target is listed for the integration and the runtime does not signal otherwise, assume it is available by default in normal interactive sessions.\n- Question count: 1-4 questions per call\n- Option count: 2-4 options per question\n- Required question fields: `question`, `header`, `options`, `multiSelect`\n- Option fields: `label`, `description`, `preview (optional)`\n- Use `multiSelect: false` unless the workflow explicitly needs multiple selections.\n- Use `metadata` only when tracking or analytics context adds value; otherwise keep the call minimal.\n",{"name":5,"metadata":24,"description":7,"argument-hint":27,"compatibility":28,"user-invocable":29},{"author":25,"source":26},"github-spec-kit","templates\u002Fcommands\u002Fdeep-research.md","Describe the feasibility question, research tracks, or demo proof needed before planning handoff","Requires spec-kit project structure with .specify\u002F directory",true,"main","021f5cbe02157229460a577e9a585f2da6d78cb0",".claude\u002Fskills\u002Fsp-deep-research","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck","https:\u002F\u002Fgithub.com\u002Fchenziyang110","2026-08-07 18:10:54",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":29},[38,41,44],{"tool":39,"command":40},"npx","npx skills add chenziyang110\u002Flaunchdeck --skill sp-deep-research",{"tool":42,"command":43},"bunx","bunx skills add chenziyang110\u002Flaunchdeck --skill sp-deep-research",{"tool":45,"command":46},"pnpm","pnpm dlx skills add chenziyang110\u002Flaunchdeck --skill sp-deep-research","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsp-deep-research\u002FSKILL.md",[49,55],{"path":50,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":53,"sourceHtmlUrl":54},"references\u002FINDEX.md","REFERENCE","参考文档",616,"https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsp-deep-research\u002Freferences\u002FINDEX.md",{"path":56,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":57,"sourceHtmlUrl":58},"references\u002Fsemantic-work-contract.md",32225,"https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsp-deep-research\u002Freferences\u002Fsemantic-work-contract.md",[60,67,73,79,86,95],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M7875F3HQ1GF5F6BR36KY3JE","launchdeck-agent","Codex host adapter contract fixture for Launchdeck.","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fagent-hosts\u002Fcodex\u002Fskill\u002FSKILL.md",[],[],{"skillNo":68,"name":62,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M7875DV2DQR33K1NFJHKAMZP","Claude host adapter contract fixture for Launchdeck.","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fagent-hosts\u002Fclaude\u002Fskill\u002FSKILL.md",[],[],{"skillNo":74,"name":62,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M78759JQ7A6FQ8KDQTNYS3X9","Use this skill aggressively for local project lifecycle operations even when the user does not mention Launchdeck: start this project, run the dev server, dev, build, test, restart service, stop service, show logs, inspect ports, port is occupied, clean cache; and when the user explicitly asks to configure this local project for Launchdeck or create or generate a project-adapted `.launchdeck.yml`, including 为这个项目生成 Launchdeck 配置. Do not use for ordinary code edits, docs-only work, general explanations, API design discussion, or production deployment unless the user also asks to operate or configure a local project or service.","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002Fagent\u002Finstaller-payload\u002Fskill\u002Flaunchdeck-agent\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M78753ZJQ7G2CZT1W1G8WRJV","zig-testing","Use ONLY when user explicitly requests Zig test code, built-in test runner configuration,\ntest failure diagnosis, or coverage for Zig projects.\n\nTriggers: \"write test zig\", \"zig test\", \"testing.allocator\", \"zig coverage\",\n\"comptime test\", \"zig expectError\", \"zig snapshot test\", \"zig fuzz\".\n\nDo NOT activate for: general Zig coding without test context, build.zig configuration\nfor non-test targets, Zig compiler errors, or Zig build system setup.","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.specify\u002Ftemplates\u002Fpassive-skills\u002Fzig-testing\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":90,"licenseFileUrl":91,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M78750JXY4Z5D5W1EX3PQ31Z","webapp-testing","Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.specify\u002Ftemplates\u002Fpassive-skills\u002Fwebapp-testing\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.specify\u002Ftemplates\u002Fpassive-skills\u002Fwebapp-testing\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":19},"01M7874X2T83EQQFRCEY5SJJVC","verification-before-completion","Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.specify\u002Ftemplates\u002Fpassive-skills\u002Fverification-before-completion\u002FSKILL.md",[],[]]