spec-kitty.tasks-finalize

## Startup Upgrade Check

Run this at most once per active agent session before the first Spec Kitty command workflow.
If you already ran `spec-kitty upgrade --agent-check --json` in this session, reuse that result and skip this block.
Do not run or announce an upgrade check again for later Spec Kitty commands in the same session.
Otherwise, before continuing, run:

```bash
spec-kitty upgrade --agent-check --json
```

If JSON `action` is `none`, continue.
If `action` is `auto_upgrade`, run `upgrade_command` before continuing. If it fails, tell the user and continue with the current Spec Kitty version.
If `action` is `guidance`, show `upgrade_note` briefly, then continue.
If `action` is `prompt`, ask the user with the host-native question UI when available:

`Spec Kitty {latest_version} is available. You are on {installed_version}. Upgrade now?`

Use these choices:

1. Upgrade now (recommended) - record `upgrade_now`, run `upgrade_command`, then continue.
2. Always keep me up to date - record `always`, run `upgrade_command`, then continue.
3. Not now - record `not_now`, then continue.
4. Never ask again - record `never_ask`, then continue.

Record the selected choice before continuing:

```bash
spec-kitty upgrade --agent-choice <upgrade_now|always|not_now|never_ask> --agent-latest <latest_version> --json
```

If no host-native question UI is available, present the same four choices in plain text and wait for the user.
In non-interactive hosts, choose `not_now` and continue.


# /spec-kitty.tasks-finalize - Finalize Tasks

**Version**: 3.2.0

## Purpose

Run the finalization command to parse dependencies from `tasks.md`, validate
them, update WP frontmatter, and commit all task artifacts to the target branch.

---

## 📍 WORKING DIRECTORY: Stay in planning repository

**IMPORTANT**: This step works in the planning repository. NO worktrees created.

## User Input

The content of the user's message that invoked this skill (everything after the skill invocation token, e.g. after `/spec-kitty.<command>` or `$spec-kitty.<command>`) is the User Input referenced elsewhere in these instructions.

You **MUST** consider this user input before proceeding (if not empty).

## Steps

### 1. Run Validate-Only Preflight

**CRITICAL**: Run this preflight command from repo root before any mutating
finalization:

```bash
spec-kitty agent mission finalize-tasks --validate-only --mission <mission-slug> --json
```

This command will:

- Parse dependencies from tasks.md
- Parse `Requirement Refs` from tasks.md
- Preview WP frontmatter updates without writing files
- Validate dependencies (check for cycles, invalid references)
- Validate requirement mapping:
  - Every WP has at least one requirement reference
  - Referenced requirement IDs exist in spec.md
  - Every FR-### in spec.md is mapped to at least one WP

If the JSON output contains `"error": "Requirement mapping validation failed"`,
do **not** run finalization. Report the blocking fields
(`missing_requirement_refs_wps`, `unknown_requirement_refs`, and
`unmapped_functional_requirements`), then fix mappings with
`spec-kitty agent tasks map-requirements --mission <mission-slug> --json` or by
updating WP `requirement_refs`.

### 1b. Ownership Overlap — domain-focused / refactor missions

If validate-only fails with `"error": "Ownership validation failed"` and
`ownership_errors` listing overlapping `owned_files`:

**Ownership collisions are EXPECTED for domain-focused and refactor-oriented
missions** (cross-cutting strangler work, repo-wide migrations, boundary
enforcement) where many work packages legitimately edit the same files. This is
not a defect in the slicing. Handle it as follows:

1. **Linearize shared surfaces (execution safety).** Work packages that touch the
   same files MUST be made dependent/linear (via `Depends on WPxx`) so they
   execute sequentially in one lane and **share a single worktree** (or run
   direct-to-branch). Limited parallelism is acceptable and expected for these
   missions — do not force artificial parallelism. Note: linearization protects
   the *worktree* from concurrent edits; it does **not** by itself satisfy
   ownership validation (see step 3).
2. **Declare cross-cutting WPs codebase-wide (the exemption).** A WP that is
   expected to overlap broadly should carry `scope: codebase-wide` in its
   frontmatter; the ownership validator exempts codebase-wide WPs from overlap
   and authoritative-surface checks. Keep the genuinely-targeted WPs (single test
   file, single module) narrow and mutually disjoint.
3. **`codebase-wide` is the ONLY exemption.** Two *narrow* WPs that claim the same
   files **always** fail ownership validation — regardless of whether they sit in
   different lanes or are linked in a dependency hierarchy. Dependency/lane
   structure never bypasses the overlap check. If WPs legitimately share a
   surface, mark the broadly-overlapping one `scope: codebase-wide`; otherwise
   re-slice so the narrow WPs are disjoint.

Do **not** fabricate disjoint `owned_files` that misrepresent which WP edits
which files solely to pass validation — linearize and/or declare codebase-wide
instead.

### 2. Run Finalization Command

Only after validate-only exits successfully, run the mutating finalization
command from repo root:

```bash
spec-kitty agent mission finalize-tasks --mission <mission-slug> --json
```

This command will update WP frontmatter, compute lanes, and commit all tasks to
the target branch.

### 3. Check Output

The JSON output includes:

- `"commit_created": true/false` — whether a commit was made
- `"commit_hash"` — the commit hash if created
- `"wp_count"` — number of WP files processed
- `"dependencies_parsed"` — dependency relationships found
- `"requirement_refs_parsed"` — requirement reference mapping found
- Validation details when checks fail (`missing_requirement_refs_wps`, `unknown_requirement_refs`, `unmapped_functional_requirements`)

### 4. Verify

**IMPORTANT — DO NOT COMMIT AGAIN AFT