@use-the-fork/spindle 0.0.2 → 0.2.0

package/build/Assets/Blueprints/skills/ref-php-laravel-saloon-api-integrations/references/testing.md

@@ -0,0 +1,119 @@
+# Testing
+
+Keep test runs offline. Use `MockClient` with fake responses or existing fixtures.
+Assert the outgoing request and the application's handling of success and failure responses, including 401, 422, and 500.
+
+## Block network access
+
+Block requests without a mock client and prevent automatic recording when a fixture is missing.
+For Pest, add this setup to `tests/Pest.php`.
+For PHPUnit, run it in the base `TestCase::setUp()` after `parent::setUp()`.
+
+```php
+use Saloon\Config;
+use Saloon\MockConfig;
+
+Config::preventStrayRequests();
+MockConfig::throwOnMissingFixtures();
+```
+
+`preventStrayRequests()` alone does not stop fixture recording when a mock client is attached.
+`throwOnMissingFixtures()` throws `FixtureMissingException` instead of recording a missing fixture.
+
+## Fake responses
+
+`MockResponse::make(body, status, headers)` builds a response. An array body is encoded as JSON.
+
+```php
+use Saloon\Http\Faking\MockClient;
+use Saloon\Http\Faking\MockResponse;
+
+$mockClient = new MockClient([
+    ListProductsRequest::class => MockResponse::make(['data' => [['id' => 1, 'name' => 'Widget']]], 200),
+    CreateProductRequest::class => MockResponse::make(['errors' => ['name' => ['Required']]], 422),
+]);
+```
+
+Mock keys can also be:
+
+- URL patterns with `*` wildcards: `'inventory.example.com/api/v1/products/*' => MockResponse::make(...)`.
+- An unkeyed list, returned in sequence regardless of the request: `[MockResponse::make('first'), MockResponse::make('second')]`.
+- A closure: `fn (PendingRequest $pendingRequest) => MockResponse::make(...)`.
+
+## Attach the mock
+
+**Local**: attach the mock to a connector or request you control.
+
+```php
+$connector = new InventoryConnector('https://inventory.example.com/api/v1', 'test-token');
+$connector->withMockClient($mockClient);
+```
+
+**Global**: mock requests sent deep inside application code.
+
+```php
+$mockClient = MockClient::global([
+    ListProductsRequest::class => MockResponse::make(['data' => []], 200),
+]);
+```
+
+Without the Laravel plugin, reset global mocks between tests with `MockClient::destroyGlobal()` in `beforeEach` or `setUp`.
+The Laravel plugin resets them automatically.
+
+## Assertions
+
+```php
+use Saloon\Http\Request;
+use Saloon\Http\Response;
+
+$mockClient->assertSent(ListProductsRequest::class);
+$mockClient->assertNotSent(CreateProductRequest::class);
+$mockClient->assertSentCount(1);
+$mockClient->assertSentCount(1, ListProductsRequest::class);
+```
+
+These are separate assertion examples. Use `assertNothingSent()` when no request should leave the application.
+For a connector configured with `test-token`, assert the actual bearer header rather than a masked placeholder:
+
+```php
+$token = 'test-token';
+
+$mockClient->assertSent(function (Request $request, Response $response) use ($token) {
+    return $request instanceof CreateProductRequest
+        && $request->body()->all() === ['name' => 'Widget', 'price_cents' => 999]
+        && $response->getPsrRequest()->getHeaderLine('Authorization') === ('Bearer ' . $token);
+});
+```
+
+## Complete example: a failure path
+
+```php
+it('reports validation errors when the inventory API rejects a product', function () {
+    $mockClient = MockClient::global([
+        CreateProductRequest::class => MockResponse::make(['errors' => ['name' => ['Required']]], 422),
+    ]);
+
+    $result = app(ProductSync::class)->create(name: '', priceCents: 0);
+
+    expect($result->errors)->toBe(['name' => ['Required']]);
+
+    $mockClient->assertSent(fn (Request $request) => $request instanceof CreateProductRequest
+        && $request->body()->get('name') === '');
+});
+```
+
+A synchronous 422 returns a response rather than throwing.
+If the code under test calls `throw()` or uses `AlwaysThrowOnErrors`, assert the exception instead.
+See [Handling failures](handling-failures.md).
+
+## Fixtures
+
+`MockResponse::fixture('inventory/products')` replays `tests/Fixtures/Saloon/inventory/products.json` when the file exists.
+With the setup above, a missing file fails the test without contacting the API.
+Change the directory with `MockConfig::setFixturePath('tests/fixtures/http')`.
+
+Record fixtures only through an explicitly authorized process outside normal test runs and CI.
+That process must omit `throwOnMissingFixtures()` and use credentials restricted to recording.
+Without that guard, a missing fixture triggers a real API call and saves the response.
+Use lowercase fixture paths. Redact secrets before committing fixture files.
+To refresh a fixture, delete only its file in the recording process.

package/build/Assets/Blueprints/skills/{author-design → sdd-author-design}/SKILL.md

@@ -1,17 +1,25 @@
 ---
-name: author-design
+name: sdd-author-design
 description: "Use when a user asks to author a design for a feature, workflow, or behavior that has important product decisions to settle."
 disable-model-invocation: true
 user-invocable: true
 metadata:
   spindle:
-    version: 1.1.1
+    version: 1.1.2
 ---
 
 # Authoring a Design
 
 Help the user clarify what they want before turning an idea into a design. A design is optional; when one is created, it is authored and approved before its spec, and tickets follow the spec. Use this for product and project decisions, not as a gate for a clear, bounded task or a user who wants a spec without a design.
 
+## Required skills
+
+Before drafting or editing, read:
+
+- **REQUIRED:** `ref-asd-ste100`
+
+Apply the clarity rules from the `ref-asd-ste100` skill. Include a before/after table only when the user requests one.
+
 ## Process
 
 1. **Check the brief.** Identify the user's goal, why it matters, what success means, and which important decisions remain open. In an existing project, inspect relevant code and docs first; do not ask for facts the project already answers. If the user asks for a design and the request is specific with no consequential decision open, proceed to the design without unnecessary questioning. **Complete when** the brief is actionable or a concrete unresolved decision is identified.
@@ -21,7 +29,7 @@ Help the user clarify what they want before turning an idea into a design. A des
 3. **Compare approaches.** Present two or three viable approaches grounded in the project and clarified goal, explain their main trade-offs, recommend one, and ask the user to choose. If only one approach fits, explain why alternatives do not. Wait for the choice before drafting. **Complete when** the user has selected an approach or delegated the choice.
 
 4. **Create or select the SDD feature workspace.**
-   - For a new feature, choose a concise title and author identity, then run `spindle sdd create --title "<feature title>" --author "<author>" --with-design`. Use the returned workspace and spec paths; `design.md` is beside `spec.md`. The command creates both template files, but fill and approve the design before filling the spec.
+   - For a new feature, choose a concise title and author identity, then run `{{ computed.spindle_package_manager }} spindle sdd create --title "<feature title>" --author "<author>" --with-design`. Use the returned workspace and spec paths; `design.md` is beside `spec.md`. The command creates both template files, but fill and approve the design before filling the spec.
    - For an existing numbered SDD feature workspace, reuse it. If `design.md` already exists, preserve it and edit it only as requested. If it is missing, first confirm `spec.md` is still the untouched template; then copy the design template from the Spindle installation's `build/Assets/Templates/sdd/design.md` into that workspace without overwriting existing files. In a source checkout, use `src/Assets/Templates/sdd/design.md`.
    - If the existing spec has substantive content, stop before adding or revising a design: that would put design after spec. Explain the conflict and ask whether the user wants to continue as an explicit exception or keep the feature spec-only.
    - Do not create a dated feature directory or a second SDD workspace for the same feature.
@@ -30,7 +38,7 @@ Help the user clarify what they want before turning an idea into a design. A des
 
 5. **Write the design.** Use the existing `design.md` scaffold, replacing its `[PLACEHOLDER]` fields with the selected intent, success criteria, scope and constraints, considered approaches and trade-offs, chosen direction, and assumptions or open decisions. Write success criteria as observable outcomes that show the design achieves its intent; include measurable targets where practical without inventing precision. Leave detailed requirements and acceptance scenarios to the subsequent spec. Preserve unresolved decisions explicitly. **Complete when** the design represents the conversation, states observable success outcomes, and distinguishes user decisions from recommendations.
 
-6. **Get approval.** Share the design path and its content for user approval or correction. Do not begin spec drafting until the user approves the design. If the user opts out of brainstorming or asks for a spec without design, respect that choice; do not create a design as a gate. After approval, ask the user to invoke `/to-spec` to create the spec in the same feature workspace; do not invoke it automatically. **Complete when** the design is approved, corrected for another review, or the user has chosen the spec-only path.
+6. **Get approval.** Share the design path and its content for user approval or correction. Do not begin spec drafting until the user approves the design. If the user opts out of brainstorming or asks for a spec without design, respect that choice; do not create a design as a gate. After approval, ask the user to invoke `/sdd-to-spec` to create the spec in the same feature workspace; do not invoke it automatically. **Complete when** the design is approved, corrected for another review, or the user has chosen the spec-only path.
 
 ## Keep the conversation useful
 

package/build/Assets/Blueprints/skills/{grill-design → sdd-grill-design}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: grill-design
+name: sdd-grill-design
 description: "Challenge and refine an existing design through an interview, updating the design and relevant domain documentation."
 argument-hint: "[design.md path or feature directory]"
 disable-model-invocation: true

package/build/Assets/Blueprints/skills/{implement-spec → sdd-implement-spec}/SKILL.md

@@ -1,16 +1,14 @@
 ---
-name: implement-spec
-description: "Implement the result of /to-spec and /to-tickets in code."
+name: sdd-implement-spec
+description: "Implement the result of /sdd-to-spec and /sdd-to-tickets in code."
 disable-model-invocation: true
 metadata:
   spindle:
-    version: 1.0.0
+    version: 1.2.0
 ---
 
 # Implement a Spec
 
-Deliver the supplied spec and all associated tickets in the existing checkout. Require configured tracker guidance; if absent, request `/setup-project`.
-
 ## Required Skills
 
 Before acting, read and follow each required skill:
@@ -19,15 +17,15 @@ Before acting, read and follow each required skill:
 
 ## Steps
 
-1. **Bind the whole-spec assignment.** Locate the full spec, every ticket and its comments, and tracker guidance. Supply accessible context pointers rather than duplicating their contents. Record the existing checkout, starting revision, existing work and permissions.
+1. **Bind the whole-spec assignment.** Locate the full spec, every ticket and its comments, and tracker guidance. Supply accessible context pointers rather than duplicating their contents. Record the original branch, existing work, permissions, and the allowed feature worktree location; obtain an allowed location for each ticket at dispatch.
 
    **Complete when:** the complete graph and delivery inputs are available to one controller, or missing requirements are reported for triage.
 
-2. **Execute the complete graph.** Follow [int-subagent-driven-dev](../int-subagent-driven-dev/SKILL.md) once with the entire graph and explicit ownership of frontier selection, sequential ticket delivery, aggregate review, and retrospective. Do not call it as a separate standalone delivery for every ticket. Its dependency validation, shared-checkout workflow, resume handling, review budgets, and completion criteria are authoritative. Accepted work does not unblock dependents until integrated and verified in the existing checkout.
+2. **Execute the complete graph.** Follow the `int-subagent-driven-dev` skill once with the entire graph and explicit ownership of frontier selection, ticket delivery, aggregate review, and retrospective. Accepted work does not unblock dependents until integrated and verified in the feature worktree.
 
    If the tracker calls for a PR, or the user requests one, open an authorized draft during execution after the first authorized commit is available; retain it as draft while delivery is incomplete.
 
-   **Complete when:** its final report reconciles every ticket and requirement, one aggregate review, fresh verification and one retrospective for the spec, or explicitly identifies unfinished work and blockers.
+   **Complete when:** its final report reconciles every ticket and requirement, one aggregate review, fresh verification, and any retrospective required by policy or requested by the user, or explicitly identifies unfinished work and blockers.
 
 3. **Apply authorized publication transitions.** Mark an authorized draft ready only after the full delivery's review and checks pass. Apply closing references and ticket closure only with the user's authorization.
 

package/build/Assets/Blueprints/skills/{to-spec → sdd-to-spec}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: to-spec
+name: sdd-to-spec
 description: "Turn an agreed feature request or approved design into a spec in its SDD feature workspace, then publish it to the configured ticket tracker."
 argument-hint: "[design file path]"
 disable-model-invocation: true
@@ -30,7 +30,7 @@ An optional design file path may be supplied. Read the entire file before drafti
 
 2. **Select or create the SDD feature workspace.**
    - Reuse the existing numbered `.scratch/<feature-id>-<slug>/` workspace when the selected design or spec belongs to one. Use its `spec.md`; do not create a second workspace for the same feature.
-   - Otherwise, derive a concise feature title from the agreed request and choose an author identity for this run. Run `spindle sdd create --title "<feature title>" --author "<author>"`; add `--with-design` when the selected design must be retained in the new workspace. If using a design outside `.scratch`, copy that approved source into the newly created `design.md`, replacing only the fresh template. Save the returned `spec` path and continue in that workspace.
+   - Otherwise, derive a concise feature title from the agreed request and choose an author identity for this run. Run `{{ computed.spindle_package_manager }} spindle sdd create --title "<feature title>" --author "<author>"`; add `--with-design` when the selected design must be retained in the new workspace. If using a design outside `.scratch`, copy that approved source into the newly created `design.md`, replacing only the fresh template. Save the returned `spec` path and continue in that workspace.
    - When the workspace has `design.md`, read it fully and use it as the requirements source. If it still contains `[PLACEHOLDER]` markers or has not been approved, pause and ask the user to finish or approve the design before drafting the spec.
    - The selected SDD workspace's pre-created `spec.md` is the output. Replace its template content with the completed spec; do not create a dated folder or a second spec.
 
@@ -48,6 +48,6 @@ An optional design file path may be supplied. Read the entire file before drafti
    - Give each important user story a concise, observable acceptance outcome or example scenario focused on user-visible behavior. Leave implementation-slice completion criteria to tickets; no fixed scenario format is required.
    - Use domain glossary terms. Do not include file paths or code snippets unless a prototype captures a decision more clearly than prose.
    - Publish the completed spec according to the configured ticket-tracker guidance. Ask before publishing if the destination or status is unclear.
-   - Once the spec is published, ask the user to invoke `/to-tickets` for planning. Do not invoke it automatically or start implementation here.
+   - Once the spec is published, ask the user to invoke `/sdd-to-tickets` for planning. Do not invoke it automatically or start implementation here.
 
    **Complete when:** the spec is published at the feature workspace's `spec.md` path, tracker publication is resolved, and no blocking ambiguity is hidden.

package/build/Assets/Blueprints/skills/{to-tickets → sdd-to-tickets}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: to-tickets
+name: sdd-to-tickets
 description: "Break an approved feature spec into tracer-bullet tickets with explicit blockers, then publish them to the configured ticket tracker."
 argument-hint: "[spec path or tracker reference]"
 disable-model-invocation: true
@@ -20,7 +20,7 @@ An optional argument is one spec path or tracker reference. Read the full spec a
    - Use the spec's existing feature workspace. In Spindle's local tracker, this is a numbered `.scratch/<feature-id>-<slug>/` directory containing `spec.md`, `sdd.json`, and `tickets/`. Never create a dated folder or a second workspace for the same feature.
    - If `design.md` exists in the feature workspace, read it and confirm it was completed and approved before the spec. If the spec is not approved or a present design is unfinished, stop and resolve that before ticket planning.
    - A design is optional. Do not require or create one when the approved spec was intentionally written without a design.
-   - For local SDD tracker work, use the feature's `spec.md` path with `spindle sdd` ticket commands. Otherwise follow the configured tracker's documented conventions.
+   - For local SDD tracker work, use the feature's `spec.md` path with `{{ computed.spindle_package_manager }} spindle sdd` ticket commands. Otherwise follow the configured tracker's documented conventions.
 
    **Complete when:** one approved spec and its tracker destination are identified; any existing design precedes it and is approved.
 
@@ -41,7 +41,7 @@ An optional argument is one spec path or tracker reference. Read the full spec a
    **Complete when:** the user approves the ticket breakdown and blocker relationships.
 
 5. **Publish the tickets.**
-   - For a local Spindle SDD tracker, create each ticket in dependency order with `spindle sdd ticket create --spec <absolute-spec-path>`. Supply its title, reporter, category (`bug` or `enhancement`), and author. Fill the generated ticket's Requirements and Acceptance Criteria using the tracker guidance. After creation, use `spindle sdd ticket update --spec <absolute-spec-path> --ticket <id> --blocked-by <blocker-ids...> --author <author>` to record each dependency; omit `--blocked-by` when there are no blockers. Keep the approved spec and feature ledger authoritative.
+   - For a local Spindle SDD tracker, create each ticket in dependency order with `{{ computed.spindle_package_manager }} spindle sdd ticket create --spec <absolute-spec-path>`. Supply its title, reporter, category (`bug` or `enhancement`), and author. Fill the generated ticket's Requirements and Acceptance Criteria using the tracker guidance. After creation, use `{{ computed.spindle_package_manager }} spindle sdd ticket update --spec <absolute-spec-path> --ticket <id> --blocked-by <blocker-ids...> --author <author>` to record each dependency; omit `--blocked-by` when there are no blockers. Keep the approved spec and feature ledger authoritative.
    - For an external ticket tracker, create one ticket per approved ticket in dependency order and use native blocking relationships when available; otherwise record blockers in each ticket. If the source was an existing ticket, create sub-tickets as required by the tracker.
    - Apply a status only when the project documents it or the user requests it. Do not close or modify a parent ticket.
    - Publishing ends here. Tell the user that delivery begins through the project's documented implementation workflow; do not start implementation.

package/build/Assets/Blueprints/skills/{setup-project → spindle-project-setup}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: setup-project
-description: "Use after spindle init to document project tooling and establish domain glossaries."
+name: spindle-project-setup
+description: "Use after {{ computed.spindle_package_manager }} spindle init to document project tooling and establish domain glossaries."
 disable-model-invocation: false
 user-invocable: true
 metadata:
@@ -14,7 +14,7 @@ Curate the commands agents should use and establish project domain documentation
 
 ## Prerequisite
 
-The user must have completed `spindle init` before running this skill. This skill
+The user must have completed `{{ computed.spindle_package_manager }} spindle init` before running this skill. This skill
 does not initialize the project. If the required project guidance or tooling
 registry is missing, report the prerequisite and stop.
 
@@ -41,7 +41,7 @@ Also inspect the source to determine whether this is an existing project: it con
 
 ### C. Update and verify tooling
 
-Load and follow the `update-tooling` skill. Supply the verified candidate commands and relevant configuration paths found in B as explicit context, and request a full registry comparison for initial setup. That skill owns the proposal, explicit approval, revision loop, `spindle tool` registry mutations, and generated-guide verification; do not duplicate or bypass its approval gate.
+Load and follow the `spindle-tooling-update` skill. Supply the verified candidate commands and relevant configuration paths found in B as explicit context, and request a full registry comparison for initial setup. That skill owns the proposal, explicit approval, revision loop, `{{ computed.spindle_package_manager }} spindle tool` registry mutations, and generated-guide verification; do not duplicate or bypass its approval gate.
 
 **Complete when:** the delegated workflow has returned with the registry and guide verified, selecting G. If approval is pending, wait; if it reports failures or discrepancies, report the blocker and stop rather than claiming setup is complete.
 

package/build/Assets/Blueprints/skills/{update-tooling → spindle-tooling-update}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: update-tooling
+name: spindle-tooling-update
 description: "Use when tooling commands are added, changed, or removed, or when refreshing the tooling registry and generated guide."
 argument-hint: "[change description or tooling paths]"
 disable-model-invocation: false
@@ -34,7 +34,7 @@ flowchart TD
 
 ### A. Inspect tooling and registry
 
-Read project guidance and run `spindle tool list` from the target Git working tree. Inspect package manifests, task runner configuration, and test/build configuration for the supplied target, or the whole project when no target is supplied. Verify command names, argument forms, and working-directory requirements against configuration. Preserve unrelated registry entries; absence from a targeted inspection is not evidence that an entry is obsolete.
+Read project guidance and run `{{ computed.spindle_package_manager }} spindle tool list` from the target Git working tree. Inspect package manifests, task runner configuration, and test/build configuration for the supplied target, or the whole project when no target is supplied. Verify command names, argument forms, and working-directory requirements against configuration. Preserve unrelated registry entries; absence from a targeted inspection is not evidence that an entry is obsolete.
 
 Do not execute project commands merely to document them if execution could install dependencies, mutate data, or have side effects without authorization. If the registry is missing or invalid, report the prerequisite and stop; do not run initialization or silently repair it.
 
@@ -59,14 +59,14 @@ Ask for explicit approval of the complete change set and wait. Approval applies
 Apply only approved changes through Spindle, not by directly editing the registry or generated Markdown. Add one entry per approved command:
 
 ```sh
-spindle tool add \
+{{ computed.spindle_package_manager }} spindle tool add \
   --key test-unit \
   --section Testing \
   --command "pnpm test -- --run" \
   --description "Run the focused unit tests."
 ```
 
-Use `spindle tool update <key>` with the approved `--section`, `--command`, or `--description` fields; `--clear-description` explicitly removes a description. Use `spindle tool remove <key>` for approved removals. Each successful mutation regenerates the guide, grouped by section with empty sections omitted.
+Use `{{ computed.spindle_package_manager }} spindle tool update <key>` with the approved `--section`, `--command`, or `--description` fields; `--clear-description` explicitly removes a description. Use `{{ computed.spindle_package_manager }} spindle tool remove <key>` for approved removals. Each successful mutation regenerates the guide, grouped by section with empty sections omitted.
 Run project scripts with `{{ computed.spindle_package_manager }} <script>`, such as `{{ computed.spindle_package_manager }} lint`.
 
 If the inspected registry or relevant configuration has changed since approval, stop and return to A, then obtain approval for a refreshed proposal. If a command fails, stop and report the failure and any already-applied changes; do not claim atomicity or completion.
@@ -75,7 +75,7 @@ If the inspected registry or relevant configuration has changed since approval,
 
 ### E. Verify registry and guide
 
-Run `spindle tool list` again and inspect `docs/agents/tooling.md`. Confirm entries, sections, commands, descriptions, and limitations agree, approved changes are reflected, and unrelated entries remain unchanged. After a decline or no-op, verify the existing state without mutating it. Report mismatches; any corrective changes require a new proposal and approval rather than direct Markdown edits.
+Run `{{ computed.spindle_package_manager }} spindle tool list` again and inspect `docs/agents/tooling.md`. Confirm entries, sections, commands, descriptions, and limitations agree, approved changes are reflected, and unrelated entries remain unchanged. After a decline or no-op, verify the existing state without mutating it. Report mismatches; any corrective changes require a new proposal and approval rather than direct Markdown edits.
 
 **Complete when:** verification results and any discrepancies are known, selecting F.
 

package/build/Assets/Templates/project/copilot-instructions.md

@@ -1,14 +1,8 @@
-## Agent skills
+## Issue tracker
 
-### Issue tracker
+SDD specs and tickets live in numbered `.scratch/<feature-id>-<feature-slug>/` workspaces. See `docs/agents/issue-tracker.md` and `docs/agents/ticket-tracker.md` for their conventions.
 
-Repository triage requests are tracked as local Markdown under `.scratch/YYYY-MM-DD-<feature-slug>/`; SDD specs and tickets live in numbered `.scratch/<feature-id>-<feature-slug>/` workspaces. See `docs/agents/issue-tracker.md` and `docs/agents/ticket-tracker.md` for their conventions.
-
-### Triage labels
-
-Use `Category: bug|enhancement` and the five canonical state values in `Status:`. See `docs/agents/triage-labels.md`.
-
-### Domain docs
+## Domain docs
 
 This is a multi-context repo; use `GLOSSARY-MAP.md` to find the relevant context glossary and consult `docs/adr/` for cross-context decisions. See `docs/agents/domain.md`.
 

package/build/Assets/Templates/project/ticket-tracker.md

@@ -15,19 +15,27 @@ Spindle SDD stores feature work in `.scratch/` workspaces. A workspace contains
 Create each approved ticket in dependency order:
 
 ```sh
-spindle sdd ticket create --spec <absolute-spec-path> --title "..." --reporter "..." --category enhancement --author maintainer
+{{ computed.spindle_package_manager }} spindle sdd ticket create --spec <absolute-spec-path> --title "..." --reporter "..." --category enhancement --author maintainer
 ```
 
 The command returns the new ticket ID and path. Complete its template, then set dependencies with `ticket update`:
 
 ```sh
-spindle sdd ticket update --spec <absolute-spec-path> --ticket T-0002 --blocked-by T-0001 --author maintainer
-spindle sdd ticket comment --spec <absolute-spec-path> --ticket T-0001 --details "..." --author maintainer
-spindle sdd ready --spec <absolute-spec-path>
+{{ computed.spindle_package_manager }} spindle sdd ticket update --spec <absolute-spec-path> --ticket T-0002 --blocked-by T-0001 --author maintainer
+{{ computed.spindle_package_manager }} spindle sdd ticket comment --spec <absolute-spec-path> --ticket T-0001 --details "..." --author maintainer
+{{ computed.spindle_package_manager }} spindle sdd ready --spec <absolute-spec-path>
 ```
 
-Use `--clear-blocked-by` to remove dependencies. Use `ticket update --status` to change status. Ticket Markdown remains editable; attributed comments are appended under `## Comments`. Do not add an execution field to the ticket file: execution transitions are recorded in `sdd.json`.
+Use `--clear-blocked-by` to remove dependencies. Ticket Markdown remains editable; attributed comments are appended under `## Comments`. Do not add an execution field to the ticket file: execution transitions are recorded in `sdd.json`.
 
 ## Delivery
 
-Use `spindle sdd status` and `spindle sdd ready` to inspect work. Claim and dispatch ready tickets with `spindle sdd claim` and `spindle sdd implement`, submit the assigned report with `spindle sdd submit`, and close completed tickets with `spindle sdd ticket update --status closed`. Follow the `int-subagent-driven-dev` skill for review, correction, and feature completion.
+Use `{{ computed.spindle_package_manager }} spindle sdd status` and `{{ computed.spindle_package_manager }} spindle sdd ready` to inspect work. Follow the `int-subagent-driven-dev` skill for dispatch, review, correction, integration, and feature completion.
+
+Inspect feature records for sensitive content, then start a feature worktree in an existing external directory with `{{ computed.spindle_package_manager }} spindle sdd start --spec <absolute-spec-path> --workspace <absolute-directory> --confirm-records`. Use its returned spec path for subsequent commands.
+
+Dispatch each ready ticket to a separate worktree with `{{ computed.spindle_package_manager }} spindle sdd implement --spec <feature-spec-path> --ticket <id> --author <name> --workspace <absolute-directory>`. Inspect changed canonical records and pass `--confirm-records` before automatic record commits. Submit the implementation report and review the committed ticket before merging it with `{{ computed.spindle_package_manager }} spindle sdd integrate`.
+
+Declare the complete post-merge check list with `checks require --scope post-merge --ticket <id>`, run the checks, and record each result with `checks record --scope post-merge --ticket <id>`. Passing results close the ticket automatically unless a blocker or dependency prevents closure. Resolve it, then repeat `checks require` with the same complete list; rerun any stale checks. Failed checks block other merges until a reviewed correction passes. Resolve conflicts in the ticket worktree, adopt the rebased baseline with `checks require --rebase-baseline`, and obtain fresh checks and review.
+
+After aggregate checks and review pass, inspect records and run `{{ computed.spindle_package_manager }} spindle sdd finish --spec <feature-spec-path> --author <name> --confirm-records` from the feature worktree. Include `--report <absolute-report-path>` when a retrospective is required. In the original checkout, declare the complete list with `checks require --scope final`, run the checks, and record each result with `checks record --scope final --merge <merge-sha> --snapshot <snapshot>`. Repeat `finish` there to preflight and clean up. Final checks cover the merge; a separate ledger-only relocation commit follows. Preserve work and inspect the journal if recovery or cleanup is blocked.

package/build/BlueprintManagement/Commands/Prompts.js

@@ -20,7 +20,7 @@ export async function promptSpindlePackageManager() {
         message: "Which package-manager command should Spindle use in generated guidance?",
         options: [
             { value: "npm run", label: "npm run" },
-            { value: "pnpm", label: "pnpm" },
+            { value: "pnpm exec", label: "pnpm exec" },
             { value: "yarn", label: "yarn" },
             { value: "bun", label: "bun" },
             { value: "other", label: "Other" },

package/build/SubagentDrivenDevelopment/Commands/ChecksRecordCommand.js

@@ -2,6 +2,7 @@ import { Command } from "../../Commands/Command.js";
 import { CommandOptions } from "../../Commands/CommandOptions.js";
 import { group } from "./groups.js";
 import { ChecksService } from "../Services/ChecksService.js";
+import { FeatureFinalizationService } from "../Services/FeatureFinalizationService.js";
 export class ChecksRecordCommand extends Command {
     static register(root, createApp) {
         group(root, "checks")
@@ -9,7 +10,8 @@ export class ChecksRecordCommand extends Command {
             .description("Record an externally executed check against a current snapshot.")
             .requiredOption("--spec <path>", "Feature spec path", CommandOptions.once("--spec"))
             .option("--ticket <id>", "Ticket ID", CommandOptions.once("--ticket"))
-            .option("--scope <scope>", "Workflow scope: delivery")
+            .option("--scope <scope>", "Workflow scope: delivery, post-merge or final")
+            .option("--merge <sha>", "Exact feature merge commit; required for scope final", CommandOptions.once("--merge"))
             .requiredOption("--snapshot <snapshot>", "CLI-returned content snapshot identity", CommandOptions.once("--snapshot"))
             .requiredOption("--command <command>", "Exact required command", CommandOptions.once("--command"))
             .requiredOption("--result <result>", "Check result: passed, failed, unavailable", CommandOptions.once("--result"))
@@ -18,11 +20,12 @@ export class ChecksRecordCommand extends Command {
             .requiredOption("--author <author>", "Acting controller", CommandOptions.once("--author"))
             .allowExcessArguments(false)
             .action(async (options) => {
-            if (options.scope !== undefined && options.scope !== "delivery") {
-                throw new Error("--scope must be 'delivery'.");
+            if (options.scope !== undefined &&
+                !["delivery", "post-merge", "final"].includes(options.scope)) {
+                throw new Error("--scope must be 'delivery', 'post-merge' or 'final'.");
             }
-            if (Boolean(options.ticket) === (options.scope === "delivery")) {
-                throw new Error("checks record needs exactly one of --ticket or --scope delivery.");
+            if ((options.scope === "delivery" || options.scope === "final") === Boolean(options.ticket)) {
+                throw new Error("checks record needs --ticket or --scope delivery/final; scope post-merge also needs --ticket.");
             }
             const command = await (await createApp()).make(ChecksRecordCommand);
             console.log(JSON.stringify(await command.run(options), null, 2));
@@ -30,6 +33,25 @@ export class ChecksRecordCommand extends Command {
     }
     async run(options) {
         this.assertApplicationBooted();
+        if (options.scope === "final") {
+            if (options.ticket || options.paths || !options.merge)
+                throw new Error("Final records require --merge and do not accept ticket/path coverage.");
+            const finalization = await this.app.make(FeatureFinalizationService);
+            const feature = finalization.recordedFeature(options.spec);
+            if (!feature)
+                throw new Error("Final records require a recorded feature merge.");
+            return finalization.record({
+                feature: feature.feature,
+                merge: options.merge,
+                snapshot: options.snapshot,
+                command: options.command,
+                result: options.result,
+                author: options.author,
+                ...(options.details ? { details: options.details } : {}),
+            });
+        }
+        if (options.merge)
+            throw new Error("--merge is only valid with --scope final.");
         return (await this.app.make(ChecksService)).checksRecord(options);
     }
 }

package/build/SubagentDrivenDevelopment/Commands/ChecksRequireCommand.js

@@ -2,6 +2,7 @@ import { Command } from "../../Commands/Command.js";
 import { CommandOptions } from "../../Commands/CommandOptions.js";
 import { group } from "./groups.js";
 import { ChecksService } from "../Services/ChecksService.js";
+import { FeatureFinalizationService } from "../Services/FeatureFinalizationService.js";
 export class ChecksRequireCommand extends Command {
     static register(root, createApp) {
         group(root, "checks")
@@ -9,25 +10,48 @@ export class ChecksRequireCommand extends Command {
             .description("Add or remove a required external check.")
             .requiredOption("--spec <path>", "Feature spec path", CommandOptions.once("--spec"))
             .option("--ticket <id>", "Ticket ID", CommandOptions.once("--ticket"))
-            .option("--scope <scope>", "Workflow scope: delivery")
-            .requiredOption("--command <command>", "Exact externally executed command", CommandOptions.once("--command"))
+            .option("--scope <scope>", "Workflow scope: delivery, post-merge or final")
+            .requiredOption("--command <command>", "Exact externally executed command; repeat for post-merge or final lists", (value, previous = []) => [...previous, value], [])
             .option("--remove", "Remove the requirement; requires --details rationale")
+            .option("--rebase-baseline", "Adopt current feature HEAD after manually rebasing the ticket worktree")
             .option("--details <details>", "Removal rationale")
             .requiredOption("--author <author>", "Acting controller", CommandOptions.once("--author"))
             .allowExcessArguments(false)
             .action(async (options) => {
-            if (options.scope !== undefined && options.scope !== "delivery") {
-                throw new Error("--scope must be 'delivery'.");
+            if (options.scope !== undefined &&
+                options.scope !== "delivery" &&
+                options.scope !== "post-merge" &&
+                options.scope !== "final") {
+                throw new Error("--scope must be 'delivery', 'post-merge' or 'final'.");
             }
-            if (Boolean(options.ticket) === (options.scope === "delivery")) {
-                throw new Error("checks require needs exactly one of --ticket or --scope delivery.");
+            if ((options.scope === "delivery" || options.scope === "final") === Boolean(options.ticket)) {
+                throw new Error("checks require needs --ticket or --scope delivery/final; scope post-merge also needs --ticket.");
             }
+            if (options.scope !== "post-merge" &&
+                options.scope !== "final" &&
+                options.command.length !== 1)
+                throw new Error("Exactly one --command is required outside scopes post-merge and final.");
             const command = await (await createApp()).make(ChecksRequireCommand);
-            console.log(JSON.stringify(await command.run(options), null, 2));
+            console.log(JSON.stringify(await command.run({
+                ...options,
+                command: options.scope === "post-merge" || options.scope === "final"
+                    ? options.command
+                    : options.command[0],
+            }), null, 2));
         });
     }
     async run(options) {
         this.assertApplicationBooted();
+        if (options.scope === "final") {
+            if (options.ticket || options.remove || options.details || options.rebaseBaseline) {
+                throw new Error("Final declarations do not accept ticket, removal, rebase or coverage options.");
+            }
+            return (await this.app.make(FeatureFinalizationService)).declare({
+                spec: options.spec,
+                command: Array.isArray(options.command) ? options.command : [options.command],
+                author: options.author,
+            });
+        }
         return (await this.app.make(ChecksService)).checksRequire(options);
     }
 }

package/build/SubagentDrivenDevelopment/Commands/CorrectCommand.js

@@ -15,7 +15,6 @@ export class CorrectCommand extends Command {
             .requiredOption("--details <details>", "Correction objective or adjudication rationale", CommandOptions.once("--details"))
             .option("--decision <decision>", "Continuation decision: continue or pause")
             .option("--assessment <assessment>", "Recorded progress assessment for the prior attempt")
-            .option("--assessment-result <result>", "Progress result: productive")
             .option("--reason <reason>", "Pause reason: no-progress, repeated-failure, recurring-blocker, requirements-disagreement, worker-blocked")
             .requiredOption("--author <author>", "Controller author", CommandOptions.once("--author"))
             .allowExcessArguments(false)

package/build/SubagentDrivenDevelopment/Commands/FinishCommand.js

@@ -6,10 +6,11 @@ export class FinishCommand extends Command {
     static register(root, createApp) {
         group(root)
             .command("finish")
-            .description("Complete feature delivery after all tickets are closed and required checks and reviews pass.")
+            .description("Merge approved feature delivery, then clean up only after exact final-merge checks pass.")
             .requiredOption("--spec <path>", "Feature spec path", CommandOptions.once("--spec"))
             .option("--report <path>", "Optional or policy-required Markdown report inside feature reports/", CommandOptions.once("--report"))
             .requiredOption("--author <author>", "Controller author", CommandOptions.once("--author"))
+            .option("--confirm-records", "Confirm inspected canonical records may be committed")
             .allowExcessArguments(false)
             .action(async (options) => {
             const command = await (await createApp()).make(FinishCommand);

package/build/SubagentDrivenDevelopment/Commands/ImplementCommand.js

@@ -10,6 +10,8 @@ export class ImplementCommand extends Command {
             .requiredOption("--spec <path>", "Feature spec path", CommandOptions.once("--spec"))
             .requiredOption("--ticket <id>", "Ticket ID", CommandOptions.once("--ticket"))
             .requiredOption("--author <author>", "Controller author", CommandOptions.once("--author"))
+            .requiredOption("--workspace <directory>", "Existing absolute external directory for the ticket worktree", CommandOptions.once("--workspace"))
+            .option("--confirm-records", "Confirm that current canonical feature records were inspected before batching")
             .allowExcessArguments(false)
             .action(async (options) => {
             const command = await (await createApp()).make(ImplementCommand);

package/build/SubagentDrivenDevelopment/Commands/{ClaimCommand.js → IntegrateCommand.js}

@@ -1,23 +1,24 @@
 import { Command } from "../../Commands/Command.js";
 import { CommandOptions } from "../../Commands/CommandOptions.js";
 import { group } from "./groups.js";
-import { AssignmentService } from "../Services/AssignmentService.js";
-export class ClaimCommand extends Command {
+import { TicketIntegrationService } from "../Services/TicketIntegrationService.js";
+export class IntegrateCommand extends Command {
     static register(root, createApp) {
         group(root)
-            .command("claim")
-            .description("Claim a ready ticket from a clean Git checkout.")
-            .requiredOption("--spec <path>", "Feature spec path", CommandOptions.once("--spec"))
+            .command("integrate")
+            .description("Merge a currently reviewed ticket commit into the feature branch.")
+            .requiredOption("--spec <path>", "Canonical feature spec", CommandOptions.once("--spec"))
             .requiredOption("--ticket <id>", "Ticket ID", CommandOptions.once("--ticket"))
             .requiredOption("--author <author>", "Controller author", CommandOptions.once("--author"))
+            .option("--confirm-records", "Confirm that current canonical feature records were inspected before batching")
             .allowExcessArguments(false)
             .action(async (options) => {
-            const command = await (await createApp()).make(ClaimCommand);
+            const command = await (await createApp()).make(IntegrateCommand);
             console.log(JSON.stringify(await command.run(options), null, 2));
         });
     }
     async run(options) {
         this.assertApplicationBooted();
-        return (await this.app.make(AssignmentService)).claim(options);
+        return (await this.app.make(TicketIntegrationService)).integrate(options);
     }
 }