From 48cc32ff9e280ac3a69b617a252c5839941fe721 Mon Sep 17 00:00:00 2001 From: magebyte-zero Date: Fri, 23 Oct 2026 17:49:10 +0800 Subject: [PATCH] refactor: separate legacy recovery from v2 skill paths --- AGENTS.md | 74 +----- CHANGELOG.md | 4 + README.md | 2 +- docs/README_en.md | 2 + docs/legacy-workflow.md | 227 ++++++++++++++++++ scripts/lib/cmd-runtime.mjs | 1 + skills/bug-investigator/SKILL.md | 61 +---- skills/build-executor/SKILL.md | 35 +-- skills/need-explorer/SKILL.md | 47 +--- skills/release-archivist/SKILL.md | 33 +-- skills/spec-writer/SKILL.md | 86 +------ skills/workflow-start/SKILL.md | 12 +- tests/lib/closing-terminal-semantics.test.mjs | 2 +- tests/lib/execution-control-plane.test.mjs | 27 +-- tests/lib/legacy-skill-routing.test.mjs | 54 +++++ .../platform-runtime-distribution.test.mjs | 8 +- tests/lib/token-rules.test.mjs | 9 +- tests/lib/windows-skill-commands.test.mjs | 10 +- .../workflow-start-recommendation.test.mjs | 8 +- 19 files changed, 387 insertions(+), 315 deletions(-) create mode 100644 docs/legacy-workflow.md create mode 100644 tests/lib/legacy-skill-routing.test.mjs diff --git a/AGENTS.md b/AGENTS.md index 460abdaf..16816664 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ This file provides guidance to Codex (codex.ai) when working with code in this r ## Current default (new changes) -Use only when the user opts into spec-superflow. New tasks have direct and planned entry points (`workflow start`), not a five-path questionnaire. Planned work uses proposal.md + tasks.md and one concrete approval; specs/design are optional. No handwritten execution-contract or recommendation receipt is required. Native/final is default, delegation and worktrees are explicit. Ordinary debugging stays in executing. `workflow complete` runs final checks and records verified or explicit accepted-risk delivery; failure is never rewritten as pass. The eight-state and DP descriptions below are legacy compatibility, not additional steps for new changes. User instructions always take precedence. +Use only when the user opts into spec-superflow. New tasks have direct and planned entry points (`workflow start`), not a five-path questionnaire. Planned work uses proposal.md + tasks.md and one concrete approval; specs/design are optional. No handwritten execution-contract or recommendation receipt is required. Native/final is default, delegation and worktrees are explicit. Ordinary debugging stays in executing. `workflow complete` runs final checks and records verified or explicit accepted-risk delivery; failure is never rewritten as pass. User instructions always take precedence. ## What This Is @@ -43,75 +43,19 @@ TypeScript interfaces + regex-based parsers. Compiles to `dist/` (ES2022 + NodeN - **proposal.md**: `## Why` ≥ 50 characters, `## What Changes` cannot be empty - `Validator` returns `ValidationReport` with `{valid, issues: [{level, path, message}], summary}`. Strict mode treats warnings as errors. -### Skills (`skills/`) +### Skills and workflow -9 skills, one per directory. Each contains a `SKILL.md` that Codex loads as an instruction set: +New changes use direct or planned. Read `skills/workflow-start/SKILL.md` when explicitly enabling the workflow. Planned work has proposal.md + tasks.md, optional behavior specs/design, one concrete approval, current-session execution and final review. Ordinary debugging stays in executing. Complete with `workflow complete`; merge and release remain separately authorized operations. -| Skill | Phase | Purpose | -|-------|-------|---------| -| `workflow-start` | Entry | Content-level state detection, 8-state routing, blocks illegal transitions | -| `need-explorer` | Exploring | One-question-at-a-time elicitation, 2-3 approach comparison with recommendation | -| `spec-writer` | Specifying | Generate planning artifacts + Schema engine validation | -| `contract-builder` | Bridging | Parsing engine auto-extracts 4 planning artifacts → compresses into `execution-contract.md` | -| `build-executor` | Executing | TDD Iron Law + SDD subagent-driven development + Review Gates | -| `bug-investigator` | Debugging | 4-phase root cause analysis. 3+ fix failures → question architecture → escalate | -| `code-reviewer` | Review | Structured review with 3 severity levels (Critical/Important/Minor) | -| `release-archivist` | Closing | Verification-before-completion Iron Law, archiving, risk summary | -| `spec-merger` | Sync | Delta Spec → intelligent merge into main specs, conflict detection | +For an existing change, identify the current path using recorded state and evidence: direct requires a valid schema-3 workflow-selection receipt; planned requires a schema-2 execution plan. Schema-1/2 direct receipts and legacy plans use [legacy recovery](docs/legacy-workflow.md), retaining original approvals and receipt obligations. A direct variant alone is insufficient, and internal `workflow: full` also occurs in v2 planned changes. Missing or corrupt evidence requires investigation rather than initialization or downgrade. Do not migrate active legacy changes automatically. -### Skill Sub-Prompts +Load only the skill needed for the current action: need-explorer for uncertain scope, spec-writer for a concrete plan, build-executor for implementation, bug-investigator for diagnosis, code-reviewer for review, spec-merger for actual delta specs, release-archivist for verification/closure. Contract-builder is only for existing legacy contracts. -- `skills/build-executor/implementer-prompt.md` — Subagent implementation template with TDD evidence + self-review requirements -- `skills/build-executor/task-reviewer-prompt.md` — Dual-verdict review (spec compliance + code quality) -- `skills/code-reviewer/code-reviewer-prompt.md` — Structured code review template with 3 severity levels +### Runtime and supporting assets -### State Machine +`scripts/spec-superflow.mjs` is the bundled CLI. Source skills use `SSF` as a placeholder for this runtime, never an arbitrary binary from PATH. Runtime references are read through its allowlisted `runtime asset read` command. Preserve this access path when moving guidance: installers must carry both skills and referenced assets. -8 states: `exploring`, `specifying`, `bridging`, `approved-for-build`, `executing`, `debugging`, `closing`, `abandoned`. - -``` -exploring → specifying → bridging → approved-for-build → executing → closing - ↑ ↑ | ↑ | - | | v | | - | | debugging ────────────┘ | - | | | - +--------------+------------------------------------+ - (scope change → re-specify) (contract drift → re-bridge) -``` - -`workflow-start` is the single entry point. It reads artifact content (not just file existence) to determine current state. - -### Hard Constraints - -- No `execution-contract.md` or no user approval → implementation is **blocked** -- Requirements change mid-execution → forced rewind to `specifying` or `bridging` -- Bug encountered → must enter `debugging` state; no "just try random fixes" -- Contract scope drift detected (proposal intent lock ≠ contract intent) → re-bridge - -### Helper Scripts (`scripts/`) - -- `spec-superflow.mjs` — CLI entrypoint for `ssf` / `spec-superflow` commands. -- `lib/` — CLI subcommand modules (`cmd-validate.mjs`, `cmd-doctor.mjs`, `cmd-state.mjs`, etc.), config loader, hash utilities. -- `validate-artifacts` — Reads a change directory, validates proposal.md + all specs/*/spec.md, prints a report. - -### Hooks (`hooks/`) - -- `hooks/session-start` — Emits a short resume pointer only when the current project/change directory contains `.spec-superflow.yaml`; inactive sessions receive no injected context. -- `hooks/hooks.json` — Claude Code hook config (SessionStart). -- `hooks/hooks-cursor.json` — Cursor equivalent. - -### Key Files - -- `templates/*.md` — Templates for the 5 artifacts (proposal, spec, design, tasks, execution-contract) -- `docs/examples/` — Two complete change sets (`add-dark-mode`, `refactor-auth-boundary`) used by tests as real input data -- `docs/state-machine.md` — Formal state machine documentation -- `docs/artifact-contract.md` — Artifact roles and mapping from planning to execution -- `docs/decision-points.md` — Standard decision-point protocol - -### Fast Paths (v0.6.0+) - -- **hotfix** — ≤2 files, no new modules; skips full exploration and specification. -- **tweak** — ≤4 files, config/docs only; skips exploration, specification, and bridging. +`templates/` supplies artifact formats; `docs/examples/` contains legacy fixtures used by tests. State-machine, decision-point and execution-contract documents describe compatibility rules, not additional steps for new changes. Hooks only supply recovery pointers for active changes; ordinary coding does not opt into the workflow automatically. ## Design Decisions @@ -138,6 +82,6 @@ Test data lives in `docs/examples/` — real proposal/spec/design artifacts from Refer to `docs/release-checklist.md` before publishing. Key items: - Keep `README.md`, `docs/README_en.md`, `INSTALL.md`, `CHANGELOG.md`, and all plugin manifests/installers in sync. Use `ssf version `. -- Verify all examples are complete (proposal + specs + design + tasks + execution-contract + README) +- Validate examples according to their workflow variant; legacy contract fixtures retain their existing artifacts. - No stray `TODO` or `TBD` markers - `package.json` version matches `.claude-plugin/plugin.json` version diff --git a/CHANGELOG.md b/CHANGELOG.md index a77dc1ca..8d078637 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ The format loosely follows Keep a Changelog. ## [Unreleased] +### Changed + +- Separate legacy recovery instructions from default workflow skills; route existing changes by recorded workflow variant and ship the compatibility reference with the bundled runtime. + ## [2.0.1] - 2026-09-22 ### Fixed diff --git a/README.md b/README.md index e5cc54cd..c1885942 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ v2 删除新任务的模式问卷和手写 `execution-contract.md`，一份执 | 调试切换独立状态 | 普通诊断留在 `executing` | | 多处缓存可阻塞计划 | 已批准的 schema v2 执行计划是唯一判断依据 | -已有变更继续按原来的状态、审批记录和审查结果恢复，不会被自动迁移或重置。 +已有变更继续按原来的状态、审批记录和审查结果恢复，不会被自动迁移或重置。默认 Skill 只保留 v2 流程；识别到旧版收据或执行计划时，才按需读取[旧流程恢复规则](docs/legacy-workflow.md)。 ## 快速开始 diff --git a/docs/README_en.md b/docs/README_en.md index c9e2ccca..46c3adf6 100644 --- a/docs/README_en.md +++ b/docs/README_en.md @@ -22,6 +22,8 @@ The defaults minimize overhead: execute in the current session, review once at t Marketplace and platform installers upgrade each skill together with its same-version CLI runtime. Skills invoke only the runtime bundled with that installation, never an unrelated older `ssf` found on `PATH`. +Default skills describe v2 direct/planned execution. Existing changes with legacy receipts or execution plans load [legacy recovery](legacy-workflow.md) only when needed; their approvals and receipts are preserved. + ## Why v2 The old flow classified work into several modes and copied state across planning, contracts, execution, and reviews. It could constrain complex work, but charged the same fixed cost to ordinary changes and could bounce between phases when receipts were stale or damaged. diff --git a/docs/legacy-workflow.md b/docs/legacy-workflow.md new file mode 100644 index 00000000..d0f6847a --- /dev/null +++ b/docs/legacy-workflow.md @@ -0,0 +1,227 @@ +# Legacy workflow recovery + +Load this reference for existing legacy plans or workflow-selection receipts with schema 1/2, including Quick/Hotfix/Lightweight records with `workflow_variant: direct`. Current v2 direct requires a valid receipt `schema_version: 3`; current planned requires `workflow_variant: planned` and an execution plan `schema_version: 2`. New requests use the primary skills. Variant or internal `workflow: full` alone cannot identify a legacy change. Missing or corrupt evidence must be recovered, never treated as permission to downgrade. + +Run the bundled CLI as defined in the invoking skill: replace `SSF` with `node "/scripts/spec-superflow.mjs"`. Preserve recorded state, approvals, receipts and isolation. Missing or corrupt recovery evidence requires diagnosis, not reinitialization or automatic migration. Read only the section matching the current skill; these rules do not add gates to v2 changes. + +## workflow-start + +Do not convert an active legacy change or discard its receipts automatically. Resume its recorded obligations: Full/legacy Hotfix may still need contract-builder and old approval/review gates; old Quick/Tweak/Lightweight/direct Hotfix use their existing receipts. Read docs/decision-points.md only for the applicable old decision, not for every task. Use `SSF runtime asset read docs/state-machine.md` only when a legacy transition is unclear. Legacy `SSF state init` precedes `SSF workflow recommend`; a nonrecommended choice requires acknowledgment. Legacy Quick/direct Hotfix use `workflow accept --verification` and persist `test_result: pass` before closing; use `SSF state set dp_0_timestamp now` for portable timestamps. + +Missing/stale Full plans block implementation, not investigation. Valid short paths and Tweak do not require plans. + +## need-explorer + +Use need-explorer's scope exploration and self-checks, then apply this recorded approval gate. + +After user confirms the summary: +```bash +SSF state set dp_1_result "confirmed: " +SSF state set dp_1_timestamp now +``` +DP-1 confirms scope, non-goals, and success criteria before artifact creation. + +#### 7. Hand Off + +Once DP-1 is recorded, hand off to `spec-writer`. + +## spec-writer + +Read `.spec-superflow.yaml` (especially `dp_0_decisions`, `dp_0_confirmed`) and any existing planning artifacts. If `dp_0_confirmed` is not `true`, stop and route back to `workflow-start` for DP-0. + +### Config Check + +Run: `SSF runtime config --get artifacts.order` — generate in configured order (default: proposal → specs → design → tasks). Run with `artifacts.skip` — skip any listed artifacts. + +### Artifact Roles + +- `proposal.md`: why and scope +- `specs/`: required behavior (testable) +- `design.md`: architecture decisions and trade-offs (not line-by-line) +- `tasks.md`: dependency-aware implementation steps + +### Working Rules + +**Honor DP-0**: Read `dp_0_decisions`, respect confirmed constraints, don't silently expand scope. Pause on unconfirmed decisions. + +#### proposal.md +Must state: observed problem, what changes, in/out scope, impact areas, and proof of completion. Prefer concrete facts over empty adjectives such as “better”, “robust”, or “efficient”. + +#### specs/ +Every requirement must be testable. Use SHALL or MUST. Every requirement must have at least one `#### Scenario:` with WHEN/THEN. Group under ADDED/MODIFIED/REMOVED Requirements headers. + +#### design.md +Must have: relevant facts and constraints, goals and non-goals, decisions (Choice + Rationale + Alternatives + Consequences), and risks with verification evidence. Do not invent stakeholders, migration steps, or open questions when they do not affect the decision. + +#### tasks.md +Must include a delivery/proof map and dependency-aware tasks. Each task names the affected path or bounded area, the observable outcome, and the evidence command. Keep RED/GREEN details, review receipts, and dispatch mechanics in the execution contract/task brief; do not inflate reader-facing tasks into five ritual substeps. + +### Artifact Generation + +Enter `specifying` before creating or editing planning artifacts: run `SSF state transition specifying` only if not already there. On resume, continue incomplete artifacts; do not self-transition. Full planning may omit specs only for explicitly unchanged behavior, and may omit design by configuration. Full cannot skip tasks: correct this configuration before generating the pack. + +When DP-0 has made the scope clear, generate the configured planning pack (proposal, delta specs from `templates/spec.md`, design, and tasks) in order without pausing between individual artifacts. Validate the pack, then request one DP-2 review. Pause earlier only when the missing decision can change user-visible behavior, compatibility, security, delivery scope, or the selected design; or when artifacts state incompatible scope. + +### Validation Checklist + +#### proposal.md +- `## Why` > 50 chars, `## What Changes`, `## Scope` (In/Out), `## Impact`, no TBD/TODO; claims name an observed problem and a completion proof + +#### specs/ +- SHALL/MUST for required behavior, `#### Scenario:` with WHEN/THEN per requirement, grouped under delta headers, no contradictions + +#### design.md +- facts/constraints, goals/non-goals, `## Decisions` (≥1, with Choice+Rationale+Alternatives+Consequences), risks and verification + +#### tasks.md +- delivery/proof map, numbered tasks, affected paths or bounded areas, observable outcomes, no placeholders, every requirement mapped, explicit dependencies +- Must use the template checkbox format (one `- [ ]` per task on its own line); the guard enforces this format when entering execution + +**If any artifact fails validation, fix before handing off to contract-builder.** + +### DP-2: Artifact Review Gate + +Present a concise summary of the configured artifacts. Self-check five questions once: problem, command boundary, invalidation boundary, continuation boundary, and document flow. Do not dispatch a blind-reader subagent unless the user explicitly requested delegation. Reuse approval already covering these artifacts; ask one consolidated question only for a new material decision or missing artifact approval. Do not add a separate continuation question. After approval: +```bash +SSF state set dp_2_result "approved: " +SSF state set dp_2_timestamp now +``` + +After DP-2 is recorded, remain in `specifying` and continue to contract-builder. + +### Handoff Rule + +Do not start implementation after writing planning artifacts. Once stable, validated, and DP-2 is recorded, hand off to `contract-builder`. + +### Exception Handling + +- **Parse failures**: Report specific file/error; don't generate from corrupted templates +- **Missing templates**: Fall back to artifact structure defined in this skill +- **User interruption**: Artifacts on disk are the recovery checkpoint; resume from first missing/incomplete one +- **Validation failure**: Fix before handoff — do not hand off broken artifacts + +## build-executor + +Full/legacy Hotfix read the approved execution contract and linked requirements for the current task. Quick/direct Hotfix/Tweak read their bounded request and verification strategy; Lightweight follows its receipt's focused review requirements. + +Legacy Full/Hotfix run `SSF isolate ` before edits and use the returned absolute checkout path for every command. The default is a feature branch in the current checkout; create a worktree only when the user explicitly selects `--worktree`. Failure blocks edits in protected branches; preserve an existing isolation and diagnose initialization failures. Direct paths do not require isolation or physical finish. + +For legacy Full, honor DP-3 approval. When the record is missing but the user explicitly approved this exact contract in the conversation, persist that existing decision and continue. Never infer approval of unseen or changed behavior, or request the same unchanged approval again. Enter `executing` only with a current plan and passing guard; skip the transition if already executing. + +### Native first + +Native means the current agent implements continuously; persisted mode is `inline`. Task count, file count and number of waves do not justify delegation. `batch-inline` remains compatible serial execution. Select SDD only when the user explicitly chooses delegation for this change and independently scoped work has a concrete benefit. Tool availability, many tasks, a long context, or generic implementation approval never authorize subagents. This includes reviewer and exploratory subagents. + +For legacy Full/Hotfix paths requiring a plan only: + +```bash +SSF execution recommend --wave :serial:[:] --json +SSF execution plan --mode inline --review-policy final --confirm --reason "" --wave :serial:[:] +``` + +Reuse the user's existing mode choice. For a nonrecommended choice add `--acknowledge-recommendation`. New Native plans default to `final` review; SDD defaults to `wave`. `--review-policy wave` is available for explicit risk boundaries. Old plans with no policy retain wave review obligations. Mode and review granularity are separate. + +Use `SSF execution show --json` to resolve uncertainty, interruptions and repair status, not as a ritual before every edit. A Native wave's dependencies are completed tasks; checked tasks never substitute for the final whole-range review. + +### One bounded preflight + +Before the first edit, inspect only shared producer/consumer interfaces and the test entry points the approved tasks depend on. Check that named symbols, payload fields and acceptance tests can be located. Record mismatches in the existing progress entry; resolve implementation details within approved behavior. Ask only when resolving a mismatch changes behavior, scope, permissions or external effects. Do not dispatch an exploration agent or create another planning pack for this check. + +### Implementation loop + +1. Implement tasks in dependency order. Full/legacy Hotfix use a failing behavioral regression, confirm RED, make the minimal fix, then confirm GREEN. Documentation changes use format/link/build checks instead of invented unit tests. +2. Run affected tests per task, integration tests at meaningful boundaries, and the required complete checks once at the final code snapshot. Reuse a result only when code, environment and command match; changes invalidate affected evidence. +3. Mark completed tasks and append a brief progress entry: outcome, files/commit, verification, next action, unresolved risk. Do not create a task book, delivery report and checkpoint for every small task. Save `SSF checkpoint save` when interruption or long-running work needs recovery. +4. Continue without requesting permission between authorized tasks. A pending task or review is not a reason to end the controller turn. Reuse existing authorizations; never ask “continue?” for the next authorized task. Give concise progress commentary; do not promise autonomous background execution. + +Legacy changes may enter `debugging` and use bug-investigator. Expected RED is test evidence, not an unexpected defect. Scope changes rewind Full to specifying; contract drift to bridging. Short paths refresh their risk receipt instead of inventing a contract. + +Read `SSF runtime asset read skills/build-executor/writing-good-tests.md` when selecting uncertain test evidence. + +### Reviews + +For Native `final`, the current executor performs one whole-range review after implementation and required tests, covering spec compliance and code quality. Do not start a reviewer subagent. Commit the code and bind the report to its actual Git range. Record through: + +```bash +SSF execution review --wave final --base --head --report .superpowers/sdd/reviews/final.md --verdict +``` + +For `wave`, review once per planned wave, using its ID instead of `final`; dependencies require a current passing receipt. SDD may use one reviewer subagent per wave because the user authorized delegation. Do not add per-task and final duplicates. Critical/Important findings require fail → focused repair → one focused re-review → pass. + +Read the CLI repair status before a retry. Never edit repair-state files. In new plans, record a stable `--issue ` on failed reviews and keep that ID for the same unresolved defect. Three failures for that issue require human adjudication; different findings do not share the budget. Legacy plans retain their recorded aggregate budget; `SSF execution adjudicate --wave --decision allow-review --confirm --reason ` authorizes one further review, never a pass. Preserve the prior review head so repair ranges remain continuous. For a final review, re-review the original complete range plus fixes when needed to certify the final snapshot. + +### Optional SDD + +Only load dispatch material when SDD is selected. Load the reviewer prompt only when a wave reaches review: + +- `SSF runtime asset read skills/build-executor/implementer-prompt.md` +- `SSF runtime asset read skills/code-reviewer/code-reviewer-prompt.md` + +Send only the task's objective, bounded files, interfaces, relevant requirement IDs and test command. Reuse an implementer for its focused repair; no nested delegation or repeated full planning packs. Batch closely related small tasks. Dispatch concurrently only for independent work with platform support; otherwise report the limitation and execute serially. + +Profiles: `mechanical`, `standard`, `strong`, `review`. Resolve `SSF runtime config --resolve-model ` once per role. Pass the configured model if supported. With `configured: false`, inherit the host model; do not invent a model or block execution. Retry blocked work only with new evidence, context or strategy; after three unresolved attempts use DP-5. + +### Plan correction and completion + +Nonsemantic planning corrections use `SSF execution resync --confirm --reason `, including during an open repair chain; history and failure counts remain binding. Semantic scope changes require reapproval and `execution revise`. Revisions may retain or change the authorized mode. Old receipts remain history and do not automatically certify changed scope or a new final snapshot. + +Before completion, satisfy contract obligations, tests and the plan's review policy. Record `batches_completed` when useful. Route to release-archivist for the recorded legacy closure path. Merge, push or publication require their own existing authorization. + +Quick/direct Hotfix persist `test_result: pass` after bounded verification; Hotfix must demonstrate the original symptom is fixed. Tweak verifies file integrity. They do not require DP-4, execution plans, wave receipts, DP-6 or DP-7. Lightweight additionally persists the focused review and passing command required by its receipt. + +Quick follows the verification strategy persisted in its receipt. Tweak skips TDD. Full and legacy Hotfix use RED → GREEN → REFACTOR. + +## bug-investigator + +Use the four investigation phases in bug-investigator, then apply the recorded debugging state and ledger requirements below. + +3+ failed fixes = architectural problem. Each fix revealing new problems elsewhere = wrong architecture. + +After every failed fix, preserve its failure output in a physical file inside the change directory, then record the distinct attempt: + +Full and legacy Hotfix require a current, valid execution plan before this command; establish one with `SSF execution recommend` and `SSF execution plan` if needed. Quick, Tweak, lightweight, and direct Hotfix keep their planless contract: their valid workflow receipt authorizes debugging, and the ledger binds attempts to that receipt plus the current workflow, artifact, and contract hashes. The debug command rejects a missing or replaced receipt or a stale required plan. + +```bash +SSF debug attempt record \ + --id \ + --summary "" \ + --evidence +``` + +Use `SSF debug attempt show --json` to present the complete attempt ledger. Wave Review repair failures are separate evidence and never count as debugging attempts. + +After at least three distinct evidence-backed attempts, stop and discuss the architectural decision with the user. Only after the user explicitly chooses may DP-5 be recorded: + +```bash +SSF debug escalate \ + --decision \ + --reason "" \ + --confirm +``` + +Never write `dp_5_*` through raw `SSF state set`; those fields are guarded by the debug ledger. If the user chooses `abandon`, transition to `abandoned` only after the guarded DP-5 receipt is recorded. + +## release-archivist + +Quick/direct Hotfix/Tweak record changed files, focused command and result, persist `test_result: pass`, then transition to closing. Hotfix must prove the original symptom fixed. Lightweight also needs its receipt's focused review and passing verification evidence. These paths require no contract, execution plan, wave reviews, audit, DP-6/DP-7 or `SSF finish`. + +### Full / legacy Hotfix + +1. Verify the final code snapshot with required build/test/validation commands. Reuse fresh results only when the code, environment and command are identical; don't rerun the same full suite just because the skill changed. +2. Check contract coverage, design consistency, scope and unresolved findings against the actual diff. Cite commands/results; do not infer success from edits or unchecked claims. +3. Require the current plan's review policy: one final whole-range review for Native `final`, or the required wave receipts for `wave`/legacy plans. Do not request a duplicate review of unchanged evidence. +4. Synchronize actual delta specs using spec-merger while executing. If specs were explicitly omitted and no delta exists, don't recreate them. +5. Run `SSF audit ` and record verification outcome (`dp_6_result`, timestamp and `test_result`). Record DP-7 only with the user's archive authorization already obtained or explicitly requested. Do not fabricate missing decisions. +6. With blockers resolved, run `SSF state transition closing`. This is logical closure; it does not claim merge or cleanup succeeded. + +Report only the outcome, key verification, unresolved risks and next action. Preserve the approved contract and implementation evidence; don't copy all planning files into a second summary. + +### Physical finish + +For authorized Full/legacy Hotfix integration, run `SSF finish [--test-cmd ]`. It uses recorded target checkout/branch, merges if necessary, verifies the target, and safely removes isolation. It verifies an archive of ignored change artifacts and preserves the previous target before cleanup. It never force-removes uncommitted work. Branch-only isolation never deletes the checkout. + +Verification failure preserves isolation. For recorded `verify-pending`, recovery offers the guarded `closing -> debugging` transition; diagnose, repair within approved scope, reverify and review before closing again. Completed finish and abandoned changes cannot reopen. Cleanup failure remains cleanup-pending. Resume performs the remaining steps; each unfinished finish retry verifies once again because ignored dependencies, local configuration and external services may have changed even at the same HEAD. Completed finish does not rerun verification. Completed finish is idempotent. A missing or ambiguous target is a real blocker: recover provenance before merging, never guess the target from the current directory. + +If the user requested branch delivery without merging, leave the branch/worktree intact and report that status. Do not treat logical closure as permission to merge, push or release. + +Use `SSF state set dp_6_timestamp now` and `SSF state set dp_7_timestamp now` when recording those decisions. diff --git a/scripts/lib/cmd-runtime.mjs b/scripts/lib/cmd-runtime.mjs index 21002962..8a9d91fb 100644 --- a/scripts/lib/cmd-runtime.mjs +++ b/scripts/lib/cmd-runtime.mjs @@ -11,6 +11,7 @@ const ASSETS = new Set([ 'docs/artifact-contract.md', 'docs/decision-points.md', 'docs/state-machine.md', + 'docs/legacy-workflow.md', 'skills/build-executor/implementer-prompt.md', 'skills/build-executor/task-reviewer-prompt.md', 'skills/build-executor/re-review-prompt.md', diff --git a/skills/bug-investigator/SKILL.md b/skills/bug-investigator/SKILL.md index 54d90236..39b2ad39 100644 --- a/skills/bug-investigator/SKILL.md +++ b/skills/bug-investigator/SKILL.md @@ -9,11 +9,15 @@ description: Use when encountering any bug, test failure, or unexpected behavior Before executing a CLI line below, replace its leading `SSF` with `node "/scripts/spec-superflow.mjs"`; `` is the absolute directory two levels above this file. Never run `SSF` literally or call an `ssf` from `PATH`. +## Workflow routing + +A new request follows this file without loading legacy instructions. For an existing change, inspect the recorded state and receipt/plan (available through `SSF workflow show --json` and `SSF execution show --json` when needed). Current paths are `workflow_variant: direct` with a valid workflow-selection receipt `schema_version: 3`, or `workflow_variant: planned` with an execution plan `schema_version: 2`. Older receipts (schema 1/2), legacy plans and other recorded variants use the matching section of `SSF runtime asset read docs/legacy-workflow.md`; follow that section for this change. A direct variant alone is insufficient: legacy Quick/Hotfix/Lightweight can also record it. The internal `workflow: full` value alone is not a legacy signal. Missing or corrupt state, receipt or a required plan is a recovery problem; preserve evidence rather than reinitialize or downgrade the change. + **Core principle:** Find root cause before attempting fixes. Symptom fixes are failure. ## New direct/planned changes -Investigate in executing without a phase transition or a separate debug ledger: reproduce, trace the root cause, make one focused repair and verify. Keep useful failure evidence in the existing progress entry. Three failures for the same unresolved issue warrant a decision; unrelated findings do not accumulate a shared budget. No task book or subagent is required. The detailed legacy protocol below is for an existing debugging state or an investigation that needs it. +Investigate in executing without a phase transition or a separate debug ledger: reproduce, trace the root cause, make one focused repair and verify. Keep useful failure evidence in the existing progress entry. Three failures for the same unresolved issue warrant a decision; unrelated findings do not accumulate a shared budget. No task book or subagent is required. ## The Iron Law @@ -53,57 +57,8 @@ Scientific method: form a single hypothesis ("I think X is the root cause becaus 1. **Create failing test case** — simplest reproduction, automated if possible. Follow TDD rules from build-executor 2. **Implement single fix** — address root cause, one change at a time, no "while I'm here" improvements 3. **Verify fix** — test passes? no regressions? issue resolved? -4. **If fix doesn't work**: count attempts. < 3 → return to Phase 1. **≥ 3 → STOP and question architecture (DP-5)** - -### DP-5: Debug Escalation (3+ Failures) - -3+ failed fixes = architectural problem. Each fix revealing new problems elsewhere = wrong architecture. - -After every failed fix, preserve its failure output in a physical file inside the change directory, then record the distinct attempt: - -Full and legacy Hotfix require a current, valid execution plan before this command; establish one with `SSF execution recommend` and `SSF execution plan` if needed. Quick, Tweak, lightweight, and direct Hotfix keep their planless contract: their valid workflow receipt authorizes debugging, and the ledger binds attempts to that receipt plus the current workflow, artifact, and contract hashes. The debug command rejects a missing or replaced receipt or a stale required plan. - -```bash -SSF debug attempt record \ - --id \ - --summary "" \ - --evidence -``` - -Use `SSF debug attempt show --json` to present the complete attempt ledger. Wave Review repair failures are separate evidence and never count as debugging attempts. - -After at least three distinct evidence-backed attempts, stop and discuss the architectural decision with the user. Only after the user explicitly chooses may DP-5 be recorded: - -```bash -SSF debug escalate \ - --decision \ - --reason "" \ - --confirm -``` - -Never write `dp_5_*` through raw `SSF state set`; those fields are guarded by the debug ledger. If the user chooses `abandon`, transition to `abandoned` only after the guarded DP-5 receipt is recorded. - -## Red Flags — Return to Phase 1 - -"Quick fix, investigate later" / "Just try changing X" / "Skip the test, I'll verify manually" / "It's probably X, let me fix that" / "I don't fully understand but this might work" / "One more fix attempt" (after 2+) / Proposing solutions before tracing data flow. - -**All of these mean: STOP. Return to Phase 1.** If 3+ fixes failed, question the architecture. - -## Quick Reference - -| Phase | Key Activities | Success Criteria | -|-------|---------------|------------------| -| 1. Root Cause | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY | -| 2. Pattern | Find working examples, compare | Identify differences | -| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis | -| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass | - -## When No Root Cause Found - -If truly environmental/timing-dependent/external: document what you investigated, implement appropriate handling (retry, timeout, error message), add monitoring. But 95% of "no root cause" cases are incomplete investigation. +4. **If the fix fails**: preserve the evidence, return to Phase 1 and form a new hypothesis. Repeated failures of the same unresolved issue require a concrete decision; unrelated issues do not share an attempt budget. -## Exception Handling +## Completion -- **Parse failures**: Report raw output, ask for clarification — don't guess -- **Missing files**: Escalate immediately — not a normal debugging scenario -- **User interruption**: Re-read investigation report on resume, continue from last completed phase +Verify the regression and affected checks, record the outcome in the existing progress entry, then return to build-executor in executing. If evidence points to an environmental or external cause, state what is known and what remains unverified. Resume from that evidence after interruption. diff --git a/skills/build-executor/SKILL.md b/skills/build-executor/SKILL.md index 78739a6f..5f4e740d 100644 --- a/skills/build-executor/SKILL.md +++ b/skills/build-executor/SKILL.md @@ -9,26 +9,17 @@ description: Execute an active direct request or approved planned change. Native Before executing a CLI line below, replace its leading `SSF` with `node "/scripts/spec-superflow.mjs"`; `` is the absolute directory two levels above this file. Never run `SSF` literally or call an `ssf` from `PATH`. -For workflow_variant planned, read the generated execution plan and current task only; approval is already in the plan. Run `SSF isolate ` before code edits, defaulting to a feature branch. No contract, recommendation or DP-4 is required. For other paths read the workflow receipt first. Full/legacy Hotfix require the approved execution contract; read linked requirements/design only for the current task. Quick/direct Hotfix/Tweak use their bounded request and verification strategy. Lightweight follows its receipt's focused review and verification requirements. +## Workflow routing -## Preflight +A new request follows this file without loading legacy instructions. For an existing change, inspect the recorded state and receipt/plan (available through `SSF workflow show --json` and `SSF execution show --json` when needed). Current paths are `workflow_variant: direct` with a valid workflow-selection receipt `schema_version: 3`, or `workflow_variant: planned` with an execution plan `schema_version: 2`. Older receipts (schema 1/2), legacy plans and other recorded variants use the matching section of `SSF runtime asset read docs/legacy-workflow.md`; follow that section for this change. A direct variant alone is insufficient: legacy Quick/Hotfix/Lightweight can also record it. The internal `workflow: full` value alone is not a legacy signal. Missing or corrupt state, receipt or a required plan is a recovery problem; preserve evidence rather than reinitialize or downgrade the change. -Legacy Full/Hotfix run `SSF isolate ` before edits and use the returned absolute checkout path for every command. The default is a feature branch in the current checkout; create a worktree only when the user explicitly selects `--worktree`. Failure blocks edits in protected branches; preserve an existing isolation and diagnose initialization failures. Direct paths do not require isolation or physical finish. - -For legacy Full, honor DP-3 approval. When the record is missing but the user explicitly approved this exact contract in the conversation, persist that existing decision and continue. Never infer approval of unseen or changed behavior, or request the same unchanged approval again. Enter `executing` only with a current plan and passing guard; skip the transition if already executing. +For planned execution, read the generated execution plan and current task; approval is already in the plan. Run `SSF isolate ` before code edits, defaulting to a feature branch, and use its returned checkout path. Preserve existing isolation; diagnose failures before editing a protected branch. Create a worktree only when explicitly selected. Direct execution reads its bounded request receipt and does not require a plan or isolation. ## Native first Native means the current agent implements continuously; persisted mode is `inline`. Task count, file count and number of waves do not justify delegation. `batch-inline` remains compatible serial execution. Select SDD only when the user explicitly chooses delegation for this change and independently scoped work has a concrete benefit. Tool availability, many tasks, a long context, or generic implementation approval never authorize subagents. This includes reviewer and exploratory subagents. -For legacy plans only (new planned changes already have their plan): - -```bash -SSF execution recommend --wave :serial:[:] --json -SSF execution plan --mode inline --review-policy final --confirm --reason "" --wave :serial:[:] -``` - -Reuse the user's existing mode choice. For a nonrecommended choice add `--acknowledge-recommendation`. New Native plans default to `final` review; SDD defaults to `wave`. `--review-policy wave` is available for explicit risk boundaries. Old plans with no policy retain wave review obligations. Mode and review granularity are separate. +Reuse the user's existing mode choice. New Native plans default to `final` review; SDD defaults to `wave`. `--review-policy wave` is available for explicit risk boundaries. Mode and review granularity are separate. Use `SSF execution show --json` to resolve uncertainty, interruptions and repair status, not as a ritual before every edit. A Native wave's dependencies are completed tasks; checked tasks never substitute for the final whole-range review. @@ -38,17 +29,19 @@ Before the first edit, inspect only shared producer/consumer interfaces and the ## Implementation loop -1. Implement tasks in dependency order. Full/legacy Hotfix use a failing behavioral regression, confirm RED, make the minimal fix, then confirm GREEN. Documentation changes use format/link/build checks instead of invented unit tests. +1. Implement tasks in dependency order. Use a failing behavioral regression for behavior changes, confirm RED, make the minimal fix, then confirm GREEN. Documentation changes use format/link/build checks instead of invented unit tests. 2. Run affected tests per task, integration tests at meaningful boundaries, and the required complete checks once at the final code snapshot. Reuse a result only when code, environment and command match; changes invalidate affected evidence. 3. Mark completed tasks and append a brief progress entry: outcome, files/commit, verification, next action, unresolved risk. Do not create a task book, delivery report and checkpoint for every small task. Save `SSF checkpoint save` when interruption or long-running work needs recovery. 4. Continue without requesting permission between authorized tasks. A pending task or review is not a reason to end the controller turn. Reuse existing authorizations; never ask “continue?” for the next authorized task. Give concise progress commentary; do not promise autonomous background execution. -For new direct/planned changes, diagnose an ordinary defect in executing: reproduce, trace the cause, repair and verify. Do not create another state transition, task report or debug ledger. Escalate only when the same issue remains unresolved without a new useful approach. Existing legacy changes may enter `debugging` and use bug-investigator. Expected RED is test evidence, not an unexpected defect. Scope changes rewind Full to specifying; contract drift to bridging. Short paths refresh their risk receipt instead of inventing a contract. +For new direct/planned changes, diagnose an ordinary defect in executing: reproduce, trace the cause, repair and verify. Do not create another state transition, task report or debug ledger. Escalate only when the same issue remains unresolved without a new useful approach. Expected RED is test evidence, not an unexpected defect. Scope changes update the plan and require approval of the changed scope through workflow-start; ordinary repair stays in executing. Read `SSF runtime asset read skills/build-executor/writing-good-tests.md` when selecting uncertain test evidence. ## Reviews +Direct changes use their receipt's bounded checks and proceed to release-archivist without a plan or review receipt. The review policies below apply to planned execution. + For Native `final`, the current executor performs one whole-range review after implementation and required tests, covering spec compliance and code quality. Do not start a reviewer subagent. Commit the code and bind the report to its actual Git range. Record through: ```bash @@ -57,7 +50,7 @@ SSF execution review --wave final --base --head --re For `wave`, review once per planned wave, using its ID instead of `final`; dependencies require a current passing receipt. SDD may use one reviewer subagent per wave because the user authorized delegation. Do not add per-task and final duplicates. Critical/Important findings require fail → focused repair → one focused re-review → pass. -Read the CLI repair status before a retry. Never edit repair-state files. In new plans, record a stable `--issue ` on failed reviews and keep that ID for the same unresolved defect. Three failures for that issue require human adjudication; different findings do not share the budget. Legacy plans retain their recorded aggregate budget; `SSF execution adjudicate --wave --decision allow-review --confirm --reason ` authorizes one further review, never a pass. Preserve the prior review head so repair ranges remain continuous. For a final review, re-review the original complete range plus fixes when needed to certify the final snapshot. +Read the CLI repair status before a retry. Never edit repair-state files. In new plans, record a stable `--issue ` on failed reviews and keep that ID for the same unresolved defect. Three failures for that issue require human adjudication; different findings do not share the budget. After adjudication, `SSF execution adjudicate --wave --decision allow-review --confirm --reason ` records permission for one further review, never a pass. Preserve the prior review head so repair ranges remain continuous. For a final review, re-review the original complete range plus fixes when needed to certify the final snapshot. ## Optional SDD @@ -68,14 +61,10 @@ Only load dispatch material when SDD is selected. Load the reviewer prompt only Send only the task's objective, bounded files, interfaces, relevant requirement IDs and test command. Reuse an implementer for its focused repair; no nested delegation or repeated full planning packs. Batch closely related small tasks. Dispatch concurrently only for independent work with platform support; otherwise report the limitation and execute serially. -Profiles: `mechanical`, `standard`, `strong`, `review`. Resolve `SSF runtime config --resolve-model ` once per role. Pass the configured model if supported. With `configured: false`, inherit the host model; do not invent a model or block execution. Retry blocked work only with new evidence, context or strategy; after three unresolved attempts use DP-5. +Profiles: `mechanical`, `standard`, `strong`, `review`. Resolve `SSF runtime config --resolve-model ` once per role. Pass the configured model if supported. With `configured: false`, inherit the host model; do not invent a model or block execution. Retry blocked work only with new evidence, context or strategy; escalate when the same issue remains unresolved without a new useful approach. ## Plan correction and completion -Nonsemantic planning corrections use `SSF execution resync --confirm --reason `, including during an open repair chain; history and failure counts remain binding. Semantic scope changes require reapproval and `execution revise`. Revisions may retain or change the authorized mode. Old receipts remain history and do not automatically certify changed scope or a new final snapshot. - -Before completion, satisfy contract obligations, tests and the plan's review policy. Record `batches_completed` when useful. For new direct/planned changes use workflow complete with the final verification command; for legacy changes route to release-archivist. Merge, push or publication require their own existing authorization. - -Quick/direct Hotfix persist `test_result: pass` after bounded verification; Hotfix must demonstrate the original symptom is fixed. Tweak verifies file integrity. They do not require DP-4, execution plans, wave receipts, DP-6 or DP-7. Lightweight additionally persists the focused review and passing command required by its receipt. +Nonsemantic planning corrections use `SSF execution resync --confirm --reason `, retaining review and failure history. Semantic changes return to workflow-start for approval of the concrete revised plan; never infer approval from changed files. -Quick follows the verification strategy persisted in its receipt. Tweak skips TDD. Full and legacy Hotfix use RED → GREEN → REFACTOR. +Before completion, satisfy tasks, the current review policy and any delta-spec synchronization. Use workflow complete with the final verification command through release-archivist. Merge, push or publication require their own existing authorization. diff --git a/skills/need-explorer/SKILL.md b/skills/need-explorer/SKILL.md index b3792776..efb7afe5 100644 --- a/skills/need-explorer/SKILL.md +++ b/skills/need-explorer/SKILL.md @@ -9,6 +9,10 @@ description: Clarify intent, scope, constraints, and success criteria before art Before executing a CLI line below, replace its leading `SSF` with `node "/scripts/spec-superflow.mjs"`; `` is the absolute directory two levels above this file. Never run `SSF` literally or call an `ssf` from `PATH`. +## Workflow routing + +A new request follows this file without loading legacy instructions. For an existing change, inspect the recorded state and receipt/plan (available through `SSF workflow show --json` and `SSF execution show --json` when needed). Current paths are `workflow_variant: direct` with a valid workflow-selection receipt `schema_version: 3`, or `workflow_variant: planned` with an execution plan `schema_version: 2`. Older receipts (schema 1/2), legacy plans and other recorded variants use the matching section of `SSF runtime asset read docs/legacy-workflow.md`; follow that section for this change. A direct variant alone is insufficient: legacy Quick/Hotfix/Lightweight can also record it. The internal `workflow: full` value alone is not a legacy signal. Missing or corrupt state, receipt or a required plan is a recovery problem; preserve evidence rather than reinitialize or downgrade the change. + Turn a rough idea into a stable change definition before writing artifacts. ## Primary Goal @@ -33,45 +37,10 @@ Present 2-3 options when reasonable answers are finite. This reduces cognitive l For each approach: what it is, upside, downside, best-for. Then **recommend one** and explain why. Never present a single path — always name at least one alternative. -### 5. Validate Before Concluding - -Restate what you heard: "Here's what I'm hearing: [problem, scope, non-goals, success criteria]. Does this match?" Incorporate corrections and re-validate. - -### 6. DP-1: Requirement Confirmation Gate - -After user confirms the summary: -```bash -SSF state set dp_1_result "confirmed: " -SSF state set dp_1_timestamp now -``` -DP-1 confirms scope, non-goals, and success criteria before artifact creation. - -### 7. Hand Off - -Once DP-1 is recorded, hand off to `spec-writer`. - -## Anti-Patterns - -- **Skipping exploration**: "Simple" changes have scope too. Five minutes of exploration prevents two hours of rework. -- **Proposing solutions before clarifying**: If the user says "add caching," first ask what problem caching solves. -- **Exploring indefinitely**: Stop when change name, problem statement, scope, non-goals, success criteria, and decomposition decision are all clear. - -## Exploration Standard - -You must leave exploration with: a usable change name, a crisp problem statement, scope boundaries, non-goals, success criteria, and a decomposition decision (one change or split). - -## Strong Rule - -Do not produce implementation code. This skill stabilizes intent, not builds. - -## Self-Review Before Handoff +### 5. Finish with a concrete scope -1. **Placeholder scan**: No "probably", "maybe", "TBD", or "we'll figure it out later" -2. **Contradiction check**: No scope items conflicting with non-goals or constraints -3. **Scope check**: Can a developer draw a bright line between in and out? +Summarize the problem, scope, non-goals, success criteria and decomposition decision for spec-writer. Reuse decisions already supplied by the user. Resolve missing material decisions, then hand off to spec-writer to draft proposal.md and tasks.md together; the concrete plan has one approval, handled by workflow-start. Exploration does not create a separate approval receipt. -## Exception Handling +## Completion -- **Parse failures**: Report the specific file, proceed with available information -- **Missing files**: Note absent essential files as constraints, continue -- **User interruption**: Exploration is stateless — on resume, re-ask the current question +Leave a usable change name, problem statement, scope, non-goals, success criteria and decomposition decision. Self-check contradictions and placeholders. Do not implement code during exploration. On interruption, resume from existing decisions and the unanswered question. diff --git a/skills/release-archivist/SKILL.md b/skills/release-archivist/SKILL.md index ce273501..43f8c6d6 100644 --- a/skills/release-archivist/SKILL.md +++ b/skills/release-archivist/SKILL.md @@ -9,35 +9,20 @@ description: Close out a spec-superflow change with verification, summary, and a Before executing a CLI line below, replace its leading `SSF` with `node "/scripts/spec-superflow.mjs"`; `` is the absolute directory two levels above this file. Never run `SSF` literally or call an `ssf` from `PATH`. -Read `SSF resume --json`. In `executing`, complete verification and logical closure. In `closing`, perform only recorded pending physical finish, if merging is authorized. `abandoned` or a completed finish requires no work. Other states route through workflow-start. - -## New direct/planned changes - -Use `SSF workflow complete --verification-command ""`. It runs final verification once; do not run the identical full suite immediately before invoking it. Planned execution additionally checks completed tasks, current full-range/wave review and any delta-spec publication. Direct execution needs no plan or review receipt. Ordinary failures stay in executing for focused repair. Do not add DP-6/DP-7 or another approval to authorized code delivery. - -If the user explicitly accepts unfinished work or failed verification, use `SSF workflow complete --accept-risk --confirm --reason ""`. Preserve every failure and report accepted-risk, not verified success. This ends code delivery without merging or deleting the branch. A plain closing transition cannot bypass failed checks. For verified work, physical integration remains a separate authorized operation. The remaining closure steps are legacy compatibility. +## Workflow routing -## Bounded paths +A new request follows this file without loading legacy instructions. For an existing change, inspect the recorded state and receipt/plan (available through `SSF workflow show --json` and `SSF execution show --json` when needed). Current paths are `workflow_variant: direct` with a valid workflow-selection receipt `schema_version: 3`, or `workflow_variant: planned` with an execution plan `schema_version: 2`. Older receipts (schema 1/2), legacy plans and other recorded variants use the matching section of `SSF runtime asset read docs/legacy-workflow.md`; follow that section for this change. A direct variant alone is insufficient: legacy Quick/Hotfix/Lightweight can also record it. The internal `workflow: full` value alone is not a legacy signal. Missing or corrupt state, receipt or a required plan is a recovery problem; preserve evidence rather than reinitialize or downgrade the change. -Quick/direct Hotfix/Tweak record changed files, focused command and result, persist `test_result: pass`, then transition to closing. Hotfix must prove the original symptom fixed. Lightweight also needs its receipt's focused review and passing verification evidence. These paths require no contract, execution plan, wave reviews, audit, DP-6/DP-7 or `SSF finish`. - -## Full / legacy Hotfix - -1. Verify the final code snapshot with required build/test/validation commands. Reuse fresh results only when the code, environment and command are identical; don't rerun the same full suite just because the skill changed. -2. Check contract coverage, design consistency, scope and unresolved findings against the actual diff. Cite commands/results; do not infer success from edits or unchecked claims. -3. Require the current plan's review policy: one final whole-range review for Native `final`, or the required wave receipts for `wave`/legacy plans. Do not request a duplicate review of unchanged evidence. -4. Synchronize actual delta specs using spec-merger while executing. If specs were explicitly omitted and no delta exists, don't recreate them. -5. Run `SSF audit ` and record verification outcome (`dp_6_result`, timestamp and `test_result`). Record DP-7 only with the user's archive authorization already obtained or explicitly requested. Do not fabricate missing decisions. -6. With blockers resolved, run `SSF state transition closing`. This is logical closure; it does not claim merge or cleanup succeeded. +Read `SSF resume --json`. In `executing`, complete verification and logical closure. In `closing`, perform only recorded pending physical finish, if merging is authorized. `abandoned` or a completed finish requires no work. Other states route through workflow-start. -Report only the outcome, key verification, unresolved risks and next action. Preserve the approved contract and implementation evidence; don't copy all planning files into a second summary. +## New direct/planned changes -## Physical finish +Use `SSF workflow complete --verification-command ""`. It runs final verification once; do not run the identical full suite immediately before invoking it. Planned execution additionally checks completed tasks, current full-range/wave review and any delta-spec publication. Direct execution needs no plan or review receipt. Ordinary failures stay in executing for focused repair. Reuse authorization already covering code delivery. -For authorized Full/legacy Hotfix integration, run `SSF finish [--test-cmd ]`. It uses recorded target checkout/branch, merges if necessary, verifies the target, and safely removes isolation. It verifies an archive of ignored change artifacts and preserves the previous target before cleanup. It never force-removes uncommitted work. Branch-only isolation never deletes the checkout. +If the user explicitly accepts unfinished work or failed verification, use `SSF workflow complete --accept-risk --confirm --reason ""`. Preserve every failure and report accepted-risk, not verified success. This ends code delivery without merging or deleting the branch. A plain closing transition cannot bypass failed checks. For verified work, physical integration remains a separate authorized operation. -Verification failure preserves isolation. For recorded `verify-pending`, recovery offers the guarded `closing -> debugging` transition; diagnose, repair within approved scope, reverify and review before closing again. Completed finish and abandoned changes cannot reopen. Cleanup failure remains cleanup-pending. Resume performs the remaining steps; each unfinished finish retry verifies once again because ignored dependencies, local configuration and external services may have changed even at the same HEAD. Completed finish does not rerun verification. Completed finish is idempotent. A missing or ambiguous target is a real blocker: recover provenance before merging, never guess the target from the current directory. +## Physical finish and delivery -If the user requested branch delivery without merging, leave the branch/worktree intact and report that status. Do not treat logical closure as permission to merge, push or release. +Logical closure does not claim merge or cleanup succeeded. For verified changes with recorded isolation and authorized integration, use `SSF finish [--test-cmd ]`. It verifies the recorded target and preserves isolation on failure. Cleanup failure remains cleanup-pending. Resume only the recorded pending operation; do not guess the target or reopen completed work. -Use `SSF state set dp_6_timestamp now` and `SSF state set dp_7_timestamp now` when recording those decisions. +For branch delivery, leave the branch/worktree intact. Report outcome, key verification, unresolved risks and integration status. Logical closure does not authorize merge, push or release; accepted-risk delivery is not eligible for physical integration. diff --git a/skills/spec-writer/SKILL.md b/skills/spec-writer/SKILL.md index 74d3e8a9..364cd319 100644 --- a/skills/spec-writer/SKILL.md +++ b/skills/spec-writer/SKILL.md @@ -9,85 +9,23 @@ description: Create or refine spec-superflow planning artifacts. Invoke when the Before executing a CLI line below, replace its leading `SSF` with `node "/scripts/spec-superflow.mjs"`; `` is the absolute directory two levels above this file. Never run `SSF` literally or call an `ssf` from `PATH`. -Create or refine planning artifacts when the change has moved beyond exploration. - -## New planned changes - -For a new request (no state or workflow auto), or workflow_variant planned, write proposal.md and tasks.md together without pausing between individual artifacts. Proposal holds the goal, in/out scope, acceptance and risks; tasks holds ordered deliverables and proof commands. Add specs only for behavior needing durable scenarios and design only for unresolved architectural decisions. Do not create execution-contract.md or duplicate the task list in another plan. - -Check shared interfaces against the real source once, then self-check the problem, scope, dependencies and proof. Present one approval request only if this concrete plan lacks approval. After approval run `SSF workflow start --path planned --confirm --reason ""` and continue implementation. No intermediate planning/bridging transitions or independent reader agent. A semantic revision uses the same command after approval; a nonsemantic correction uses execution resync and retains failed-review history. The remaining sections apply only to existing legacy changes. - -## Required Inputs - -Read `.spec-superflow.yaml` (especially `dp_0_decisions`, `dp_0_confirmed`) and any existing planning artifacts. If `dp_0_confirmed` is not `true`, stop and route back to `workflow-start` for DP-0. - -## Config Check - -Run: `SSF runtime config --get artifacts.order` — generate in configured order (default: proposal → specs → design → tasks). Run with `artifacts.skip` — skip any listed artifacts. - -## Artifact Roles - -- `proposal.md`: why and scope -- `specs/`: required behavior (testable) -- `design.md`: architecture decisions and trade-offs (not line-by-line) -- `tasks.md`: dependency-aware implementation steps - -## Working Rules - -**Honor DP-0**: Read `dp_0_decisions`, respect confirmed constraints, don't silently expand scope. Pause on unconfirmed decisions. - -### proposal.md -Must state: observed problem, what changes, in/out scope, impact areas, and proof of completion. Prefer concrete facts over empty adjectives such as “better”, “robust”, or “efficient”. +## Workflow routing -### specs/ -Every requirement must be testable. Use SHALL or MUST. Every requirement must have at least one `#### Scenario:` with WHEN/THEN. Group under ADDED/MODIFIED/REMOVED Requirements headers. +A new request follows this file without loading legacy instructions. For an existing change, inspect the recorded state and receipt/plan (available through `SSF workflow show --json` and `SSF execution show --json` when needed). Current paths are `workflow_variant: direct` with a valid workflow-selection receipt `schema_version: 3`, or `workflow_variant: planned` with an execution plan `schema_version: 2`. Older receipts (schema 1/2), legacy plans and other recorded variants use the matching section of `SSF runtime asset read docs/legacy-workflow.md`; follow that section for this change. A direct variant alone is insufficient: legacy Quick/Hotfix/Lightweight can also record it. The internal `workflow: full` value alone is not a legacy signal. Missing or corrupt state, receipt or a required plan is a recovery problem; preserve evidence rather than reinitialize or downgrade the change. -### design.md -Must have: relevant facts and constraints, goals and non-goals, decisions (Choice + Rationale + Alternatives + Consequences), and risks with verification evidence. Do not invent stakeholders, migration steps, or open questions when they do not affect the decision. - -### tasks.md -Must include a delivery/proof map and dependency-aware tasks. Each task names the affected path or bounded area, the observable outcome, and the evidence command. Keep RED/GREEN details, review receipts, and dispatch mechanics in the execution contract/task brief; do not inflate reader-facing tasks into five ritual substeps. - -## Artifact Generation - -Enter `specifying` before creating or editing planning artifacts: run `SSF state transition specifying` only if not already there. On resume, continue incomplete artifacts; do not self-transition. Full planning may omit specs only for explicitly unchanged behavior, and may omit design by configuration. Full cannot skip tasks: correct this configuration before generating the pack. - -When DP-0 has made the scope clear, generate the configured planning pack (proposal, delta specs from `templates/spec.md`, design, and tasks) in order without pausing between individual artifacts. Validate the pack, then request one DP-2 review. Pause earlier only when the missing decision can change user-visible behavior, compatibility, security, delivery scope, or the selected design; or when artifacts state incompatible scope. - -## Validation Checklist - -### proposal.md -- `## Why` > 50 chars, `## What Changes`, `## Scope` (In/Out), `## Impact`, no TBD/TODO; claims name an observed problem and a completion proof - -### specs/ -- SHALL/MUST for required behavior, `#### Scenario:` with WHEN/THEN per requirement, grouped under delta headers, no contradictions - -### design.md -- facts/constraints, goals/non-goals, `## Decisions` (≥1, with Choice+Rationale+Alternatives+Consequences), risks and verification - -### tasks.md -- delivery/proof map, numbered tasks, affected paths or bounded areas, observable outcomes, no placeholders, every requirement mapped, explicit dependencies -- Must use the template checkbox format (one `- [ ]` per task on its own line); the guard enforces this format when entering execution - -**If any artifact fails validation, fix before handing off to contract-builder.** - -## DP-2: Artifact Review Gate +Create or refine planning artifacts when the change has moved beyond exploration. -Present a concise summary of the configured artifacts. Self-check five questions once: problem, command boundary, invalidation boundary, continuation boundary, and document flow. Do not dispatch a blind-reader subagent unless the user explicitly requested delegation. Reuse approval already covering these artifacts; ask one consolidated question only for a new material decision or missing artifact approval. Do not add a separate continuation question. After approval: -```bash -SSF state set dp_2_result "approved: " -SSF state set dp_2_timestamp now -``` +## New planned changes -After DP-2 is recorded, remain in `specifying` and continue to contract-builder. +For a new request, an expanding direct change, or workflow_variant planned, write proposal.md and tasks.md together without pausing between individual artifacts. Proposal holds the goal, in/out scope, acceptance and risks; tasks holds ordered deliverables and proof commands. Add specs only for behavior needing durable scenarios and design only for unresolved architectural decisions. Do not create execution-contract.md or duplicate the task list in another plan. -## Handoff Rule +Check shared interfaces against the real source once, then self-check the problem, scope, dependencies and proof. Present one approval request only if this concrete plan lacks approval. After approval run `SSF workflow start --path planned --confirm --reason ""` and continue implementation. No intermediate planning/bridging transitions or independent reader agent. A semantic revision uses the same command after approval; a nonsemantic correction uses execution resync and retains failed-review history. -Do not start implementation after writing planning artifacts. Once stable, validated, and DP-2 is recorded, hand off to `contract-builder`. +## Artifact checks -## Exception Handling +- proposal.md records the problem, in/out scope, acceptance, impact and risks. +- tasks.md is the only task list: unique numbered checkboxes, dependency order, affected paths or bounded areas, observable outcomes and proof commands. Keep test-cycle details in execution notes rather than repeating the plan. +- Add specs/ for durable behavior scenarios: each requirement uses SHALL/MUST and a `#### Scenario:` with WHEN/THEN, grouped under the applicable delta headers. +- Add design.md for real technical decisions: choice, rationale, alternatives, consequences and risks. Reference existing architecture instead of copying it. -- **Parse failures**: Report specific file/error; don't generate from corrupted templates -- **Missing templates**: Fall back to artifact structure defined in this skill -- **User interruption**: Artifacts on disk are the recovery checkpoint; resume from first missing/incomplete one -- **Validation failure**: Fix before handoff — do not hand off broken artifacts +Self-check five questions once: problem, command boundary, invalidation boundary, continuation boundary and document flow. Fix contradictions and missing acceptance evidence before presenting the one concrete plan for approval. Keep existing approval when it still covers that exact plan. After workflow-start records approval, continue to build-executor. diff --git a/skills/workflow-start/SKILL.md b/skills/workflow-start/SKILL.md index 7080eade..01d4a566 100644 --- a/skills/workflow-start/SKILL.md +++ b/skills/workflow-start/SKILL.md @@ -9,6 +9,10 @@ description: Primary entry point for the spec-superflow state-machine workflow. Before executing a CLI line below, replace its leading `SSF` with `node "/scripts/spec-superflow.mjs"`; `` is the absolute directory two levels above this file. Never run `SSF` literally or call an `ssf` from `PATH`. +## Workflow routing + +A new request follows this file without loading legacy instructions. For an existing change, inspect the recorded state and receipt/plan (available through `SSF workflow show --json` and `SSF execution show --json` when needed). Current paths are `workflow_variant: direct` with a valid workflow-selection receipt `schema_version: 3`, or `workflow_variant: planned` with an execution plan `schema_version: 2`. Older receipts (schema 1/2), legacy plans and other recorded variants use the matching section of `SSF runtime asset read docs/legacy-workflow.md`; follow that section for this change. A direct variant alone is insufficient: legacy Quick/Hotfix/Lightweight can also record it. The internal `workflow: full` value alone is not a legacy signal. Missing or corrupt state, receipt or a required plan is a recovery problem; preserve evidence rather than reinitialize or downgrade the change. + Use only for an explicit spec-superflow request or an existing change. Ordinary coding does not require a spec workflow. ## Resume @@ -19,7 +23,7 @@ Run `SSF resume --json` once. It combines state, handoffs, checkpoi - `closing`: logical completion. If a recorded isolation still has physical finish pending, route to release-archivist for that remaining action, subject to existing merge authorization. Otherwise stop. - `abandoned`: stop. - A ready handoff needs review through `SSF handoff resolve`; an active handoff is non-blocking. Stale checkpoints are history, not current evidence. -- Missing/stale Full plans block implementation, not investigation. Valid short paths and Tweak do not require plans. +- A missing/stale planned execution plan blocks implementation, not investigation. Direct changes do not require a plan. Update checks are optional (`SSF runtime check-update`), cached and non-blocking. Never make network access a recovery prerequisite. @@ -30,14 +34,10 @@ Infer scope and risks from the request and repository; do not turn CLI fields in Offer only two paths, without a mode-selection interview: - **Direct**: clear requested change with a bounded proof. In the same turn run `SSF workflow start --path direct --scope ""`. No planning pack, recommendation receipt or execution plan is needed. Use affected tests or checks; `--verification` can record tdd/new-test/bounded when relevant. Task/file counts are advisory, not hard limits. -- **Planned**: uncertain behavior, architecture or a user-requested plan. Draft proposal.md (scope, acceptance, risks) and tasks.md (ordered tasks and proof) together. Add specs/design only when their information is needed. Check shared interfaces against actual code once. Present one concrete plan for approval, reusing approval already covering it. Then run `SSF workflow start --path planned --confirm --reason ""`. The CLI derives the execution plan and enters executing; no contract-builder, handwritten contract, DP-0..DP-4 sequence or execution recommend is required. Native + final is the default; add `--mode sdd` only for explicit delegation. +- **Planned**: uncertain behavior, architecture or a user-requested plan. Draft proposal.md (scope, acceptance, risks) and tasks.md (ordered tasks and proof) together. Add specs/design only when their information is needed. Check shared interfaces against actual code once. Present one concrete plan for approval, reusing approval already covering it. Then run `SSF workflow start --path planned --confirm --reason ""`. The CLI derives the execution plan and enters executing; no handwritten contract or intermediate approval sequence is required. Native + final is the default; add `--mode sdd` only for explicit delegation. Continue to build-executor without another question. Ordinary debugging stays in executing. Scope changes update the affected planning sections and repeat planned start once with actual reapproval; do not traverse intermediate states. Nonsemantic corrections can use execution resync with a recorded reason, retaining review history. Completion uses `SSF workflow complete --verification-command ""`. It runs the check once and preserves failures. Planned work also requires its current review and completed tasks; existing delta specs require synchronization. A user can explicitly accept known risks with `workflow complete --accept-risk --confirm --reason ""`; this records accepted-risk, never pass, and does not authorize integration. -## Legacy changes - -Do not convert an active legacy change or discard its receipts automatically. Resume its recorded obligations: Full/legacy Hotfix may still need contract-builder and old approval/review gates; old Quick/Tweak/Lightweight/direct Hotfix use their existing receipts. Read docs/decision-points.md only for the applicable old decision, not for every task. Use `SSF runtime asset read docs/state-machine.md` only when a legacy transition is unclear. Legacy `SSF state init` precedes `SSF workflow recommend`; a nonrecommended choice requires acknowledgment. Legacy Quick/direct Hotfix use `workflow accept --verification` and persist `test_result: pass` before closing; use `SSF state set dp_0_timestamp now` for portable timestamps. - Continue authorized internal work without phase-by-phase handoff questions. For all paths, read only the current task's source and evidence. Progress updates use one short paragraph; ask only for a new material decision, never “continue?” for authorized work. diff --git a/tests/lib/closing-terminal-semantics.test.mjs b/tests/lib/closing-terminal-semantics.test.mjs index 0d444ccd..73326b58 100644 --- a/tests/lib/closing-terminal-semantics.test.mjs +++ b/tests/lib/closing-terminal-semantics.test.mjs @@ -29,7 +29,7 @@ describe('closing terminal lifecycle', () => { }); it('keeps spec synchronization and audit before logical closure', () => { - const release = read('skills/release-archivist/SKILL.md'); + const release = read('docs/legacy-workflow.md').split('## release-archivist')[1]; assert.ok(release.indexOf('Synchronize actual delta') < release.indexOf(`${RUNTIME_PREFIX} state transition`)); assert.ok(release.indexOf(`${RUNTIME_PREFIX} audit`) < release.indexOf(`${RUNTIME_PREFIX} state transition`)); const merger = section(read('skills/spec-merger/SKILL.md'), '## Execution-State Guard'); diff --git a/tests/lib/execution-control-plane.test.mjs b/tests/lib/execution-control-plane.test.mjs index cf73ae52..b6f76c96 100644 --- a/tests/lib/execution-control-plane.test.mjs +++ b/tests/lib/execution-control-plane.test.mjs @@ -49,18 +49,15 @@ describe('execution control plane instructions', () => { } }); - it('limits planning and review receipts to Full and legacy Hotfix', () => { - for (const path of [ - 'skills/workflow-start/SKILL.md', - 'skills/build-executor/SKILL.md', - 'skills/contract-builder/SKILL.md', - 'skills/release-archivist/SKILL.md', - ]) { - const content = read(path); - assert.match(content, /Quick.*direct|direct.*Quick/is, `${path} publishes Quick direct execution`); - assert.match(content, /legacy Hotfix/is, `${path} distinguishes legacy Hotfix`); - assert.match(content, /test_result.*pass/is, `${path} requires a persisted short-path verification result`); + it('keeps legacy receipt obligations in the compatibility reference', () => { + const legacy = read('docs/legacy-workflow.md'); + assert.match(legacy, /Quick.*direct|direct.*Quick/is); + assert.match(legacy, /legacy Hotfix/is); + assert.match(legacy, /test_result.*pass/is); + for (const name of ['workflow-start', 'build-executor', 'release-archivist']) { + assert.match(read(`skills/${name}/SKILL.md`), /runtime asset read docs\/legacy-workflow\.md/); } + assert.match(read('skills/contract-builder/SKILL.md'), /Legacy compatibility only/i); }); it('documents receipt-bound planless debugging for every direct workflow path', () => { @@ -254,9 +251,11 @@ describe('execution control plane instructions', () => { const inject = read('scripts/lib/cmd-inject.mjs'); assert.match(workflowStart, /SSF resume --json/); - assert.match(buildExecutor, /execution recommend/i); - assert.match(buildExecutor, /review-policy final/); - assert.match(buildExecutor, /Old plans with no policy retain wave/i); + assert.match(read('docs/legacy-workflow.md'), /execution recommend/i); + assert.doesNotMatch(buildExecutor, /SSF execution recommend/); + assert.match(read('docs/legacy-workflow.md'), /review-policy final/); + assert.match(buildExecutor, /Native plans default to `final`/); + assert.match(read('docs/legacy-workflow.md'), /Old plans with no policy retain wave/i); assert.match(buildExecutor, /platform support.*otherwise report/is); assert.match(buildExecutor, /Critical\/Important.*fail.*repair.*pass/is); assert.match(codeReviewer, /execution review .*--verdict /s); diff --git a/tests/lib/legacy-skill-routing.test.mjs b/tests/lib/legacy-skill-routing.test.mjs new file mode 100644 index 00000000..0cfd5a46 --- /dev/null +++ b/tests/lib/legacy-skill-routing.test.mjs @@ -0,0 +1,54 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs'; +import { readState } from '../../scripts/lib/state-loader.mjs'; +import { execFileSync } from 'node:child_process'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; + +const root = process.cwd(); +const read = path => readFileSync(join(root, path), 'utf8'); +const primary = ['workflow-start', 'need-explorer', 'spec-writer', 'build-executor', 'bug-investigator', 'release-archivist']; + +test('default skill paths disclose legacy recovery only behind recorded-state routing', () => { + for (const name of primary) { + const content = read(`skills/${name}/SKILL.md`); + assert.match(content, /workflow_variant/); + assert.match(content, /receipt `schema_version: 3`/); + assert.match(content, /plan `schema_version: 2`/); + assert.match(content, /legacy Quick\/Hotfix\/Lightweight can also record it/); + assert.match(content, /Missing or corrupt.*recovery problem/); + assert.match(content, /runtime asset read docs\/legacy-workflow\.md/); + assert.doesNotMatch(content, /SSF (?:state (?:set|transition|init)|workflow (?:recommend|accept)|debug (?:attempt|escalate)|audit)\b/, `${name} leaks legacy commands into the default path`); + } + assert.doesNotMatch(read('AGENTS.md'), /No `execution-contract.md` or no user approval|Bug encountered → must enter|≤[24] files/); +}); + +test('legacy instructions remain available through the bundled runtime outside the repository', () => { + const content = execFileSync(process.execPath, [join(root, 'scripts/spec-superflow.mjs'), 'runtime', 'asset', 'read', 'docs/legacy-workflow.md'], { cwd: tmpdir(), encoding: 'utf8' }); + assert.equal(content, read('docs/legacy-workflow.md')); + for (const name of primary) assert.ok(content.includes(`## ${name}`), `missing ${name} legacy recipe`); + assert.match(content, /dp_3|contract-builder/); + assert.match(content, /debug attempt record/); + assert.match(content, /workflow accept.*--verification/); + assert.match(content, /Cleanup failure remains cleanup-pending/); +}); + +test('a real legacy direct receipt keeps its generation visible without migrating state', t => { + const dir = mkdtempSync(join(tmpdir(), 'ssf-legacy-routing-')); + t.after(() => rmSync(dir, { recursive: true, force: true })); + writeFileSync(join(dir, '.spec-superflow.yaml'), 'state: exploring\nworkflow: auto\n'); + const cli = (...args) => execFileSync(process.execPath, [join(root, 'scripts/spec-superflow.mjs'), ...args], { encoding: 'utf8' }); + cli('workflow', 'recommend', dir, '--task-count', '2', '--file-count', '2', '--config-doc-only', 'no', + '--schema-api-change', 'no', '--new-module', 'no', '--behavioral-constraint-change', 'no', + '--cross-module-change', 'no', '--uncertainty', 'low', '--json'); + cli('workflow', 'accept', dir, '--source', 'direct-request', '--verification', 'bounded', '--json'); + assert.equal(readState(dir).workflow_variant, 'direct'); + const before = readFileSync(join(dir, '.spec-superflow.yaml'), 'utf8'); + const shown = JSON.parse(cli('workflow', 'show', dir, '--json')); + assert.ok([1, 2].includes(shown.record.schema_version)); + assert.equal(shown.workflow, 'quick'); + assert.equal(shown.path, undefined, 'old direct variants must not be identified as current direct by show'); + assert.equal(readFileSync(join(dir, '.spec-superflow.yaml'), 'utf8'), before); + assert.match(read('docs/legacy-workflow.md'), /schema 1\/2.*Quick\/Hotfix\/Lightweight.*workflow_variant: direct/s); +}); diff --git a/tests/lib/platform-runtime-distribution.test.mjs b/tests/lib/platform-runtime-distribution.test.mjs index 106bccd1..f6661629 100644 --- a/tests/lib/platform-runtime-distribution.test.mjs +++ b/tests/lib/platform-runtime-distribution.test.mjs @@ -148,16 +148,18 @@ describe('local runtime deployment', () => { }); const content = readFileSync(join(target, '.zcode', 'skills', 'workflow-start', 'SKILL.md'), 'utf8'); - const command = content.match(/node '([^']+)' runtime asset read docs\/state-machine\.md/); + const command = content.match(/node '([^']+)' runtime asset read docs\/legacy-workflow\.md/); assert.ok(command, 'workflow-start should contain a shell-literal local runtime command'); const runtimeScript = command[1]; assert.equal(runtimeScript, join(realpathSync(join(target, '.zcode', 'spec-superflow')), 'scripts', 'spec-superflow.mjs')); - const output = execFileSync(process.execPath, [runtimeScript, 'runtime', 'asset', 'read', 'docs/state-machine.md'], { + const output = execFileSync(process.execPath, [runtimeScript, 'runtime', 'asset', 'read', 'docs/legacy-workflow.md'], { cwd: target, encoding: 'utf8', }); - assert.match(output, /State Machine/); + assert.match(output, /Legacy workflow recovery/); + assert.match(output, /## spec-writer/); + assert.match(output, /debug attempt record/); } finally { rmSync(target, { recursive: true, force: true }); } diff --git a/tests/lib/token-rules.test.mjs b/tests/lib/token-rules.test.mjs index 69a43525..3cdd5d05 100644 --- a/tests/lib/token-rules.test.mjs +++ b/tests/lib/token-rules.test.mjs @@ -174,7 +174,8 @@ describe('planning document readability contract', () => { const tasks = read('templates/tasks.md'); assert.match(writer, /without pausing between individual artifacts/i); - assert.match(writer, /one DP-2/i); + assert.match(writer, /one concrete plan for approval/i); + assert.doesNotMatch(writer, /SSF state set.*dp_2/); assert.match(writer, /Self-check five questions once/i); assert.match(proposal, /完成证明/); assert.match(proposal, /Scope[\s\S]*In Scope[\s\S]*Out of Scope/); @@ -208,11 +209,11 @@ describe('test-quality guidance contract', () => { `${name} must point agents to the shared test-quality guide`); } - assert.match(executor, /Quick follows the verification strategy persisted in its receipt/, + assert.match(read('docs/legacy-workflow.md'), /Quick follows the verification strategy persisted in its receipt/, 'Quick must retain its user-selected verification strategy'); - assert.match(executor, /Tweak skips TDD/, + assert.match(read('docs/legacy-workflow.md'), /Tweak skips TDD/, 'Tweak must retain its direct-edit boundary'); - assert.match(executor, /Full and legacy Hotfix use RED → GREEN → REFACTOR/, + assert.match(read('docs/legacy-workflow.md'), /Full and legacy Hotfix use RED → GREEN → REFACTOR/, 'Full work must retain the TDD iron law'); }); }); diff --git a/tests/lib/windows-skill-commands.test.mjs b/tests/lib/windows-skill-commands.test.mjs index 426c092f..ae55658f 100644 --- a/tests/lib/windows-skill-commands.test.mjs +++ b/tests/lib/windows-skill-commands.test.mjs @@ -4,12 +4,12 @@ import { readFileSync } from 'node:fs'; import { join } from 'node:path'; const timestampSkills = [ - ['skills/workflow-start/SKILL.md', 'dp_0_timestamp'], - ['skills/need-explorer/SKILL.md', 'dp_1_timestamp'], - ['skills/spec-writer/SKILL.md', 'dp_2_timestamp'], + ['docs/legacy-workflow.md', 'dp_0_timestamp'], + ['docs/legacy-workflow.md', 'dp_1_timestamp'], + ['docs/legacy-workflow.md', 'dp_2_timestamp'], ['skills/contract-builder/SKILL.md', 'dp_3_timestamp'], - ['skills/release-archivist/SKILL.md', 'dp_6_timestamp'], - ['skills/release-archivist/SKILL.md', 'dp_7_timestamp'], + ['docs/legacy-workflow.md', 'dp_6_timestamp'], + ['docs/legacy-workflow.md', 'dp_7_timestamp'], ]; describe('cross-platform skill commands', () => { diff --git a/tests/lib/workflow-start-recommendation.test.mjs b/tests/lib/workflow-start-recommendation.test.mjs index 04928c2f..bd5f3a0c 100644 --- a/tests/lib/workflow-start-recommendation.test.mjs +++ b/tests/lib/workflow-start-recommendation.test.mjs @@ -12,14 +12,16 @@ describe('workflow-start path recommendation protocol', () => { assert.match(skill, /Infer scope and risks/i); assert.match(skill, /do not turn CLI fields into a questionnaire/i); assert.match(skill, /same turn/i); - assert.match(skill, /workflow accept.*--verification/i); + assert.match(read('docs/legacy-workflow.md'), /workflow accept.*--verification/i); assert.match(skill, /Reuse authorization already given/i); - assert.match(skill, /nonrecommended choice requires acknowledgment/i); + assert.match(read('docs/legacy-workflow.md'), /nonrecommended choice requires acknowledgment/i); }); it('validates and initializes before recommending a new change', () => { const skill = read('skills/workflow-start/SKILL.md'); assert.match(skill, /single safe relative path segment under `changes\//); - assert.ok(skill.indexOf('SSF state init') < skill.indexOf('SSF workflow recommend')); + const legacy = read('docs/legacy-workflow.md'); + assert.ok(legacy.indexOf('SSF state init') < legacy.indexOf('SSF workflow recommend')); + assert.doesNotMatch(skill, /SSF state init/); assert.match(skill, /Never infer approval from artifact existence/i); });