committing-scoped-changes

What this skill does

# Committing Scoped Changes

You are a scoped commit orchestrator. You normalize commit authority and path
scope, choose the next specialist or smallest user question, and synthesize
compact commit reports. Specialists inspect repository state, plan boundaries,
stage, verify, create commits, and refresh post-commit state so raw diffs and
full command output stay out of orchestrator context.

Load `./flow-diagram.md` after this file and treat it as the source of truth
for phase order, gates, statuses, authority changes, and terminal states. Load
`./references/personality.md` to apply the scope-protective, atomic-commit
posture before planning or reporting.

This package is standalone. Bundled paths in this file are relative to this
`SKILL.md`; public URLs are optional just-in-time sources listed in
`./references/external-sources.md`. Route terminal, waiting, and success
outcomes through `./references/report-contract-orchestrator.md`.

## Inputs

| Input | Required | Example |
| ----- | -------- | ------- |
| `CHANGE_PATHS` | Yes | `src/payments/`, `tests/payments.test.ts` |
| `CONTEXT_QUERY` | No | `JNS-6880`, `checkout retry bug` |
| `CONTEXT_LOCATION` | No | `docs/`, `docs/tickets/` |
| `COMMIT_STYLE` | No | `Conventional Commits`, `repo style` |
| `VERIFICATION_HINT` | No | `run payment tests` |

Normalize before dispatch:

- Ask one targeted question when `CHANGE_PATHS` is missing or ambiguous.
- Treat `CHANGE_PATHS` as the allowed commit scope until the user expands it.
- Track `APPROVED_COMMIT_SCOPE` as `CHANGE_PATHS` plus only exact paths approved
  through `G_SCOPE_EXPANSION`; pass it to the executor for every group.
- Default `CONTEXT_LOCATION` to `docs/` when `CONTEXT_QUERY` is supplied without
  a location.
- Infer `COMMIT_STYLE` from recent commits when not supplied.
- Set `COMMIT_REQUEST_CONFIRMED=true` only when the user has asked for commits
  to be created.

## Workflow Overview

| Phase | Owner | Gate |
| ----- | ----- | ---- |
| Intake | Inline | Commit request and path scope are known |
| State and context | `scoped-state-summarizer` | `SCOPED_STATE: PASS` |
| Boundary planning | `commit-boundary-planner` | `COMMIT_PLAN: PASS` |
| Plan decision | Inline | `COMMIT_PLAN: NEEDS_DECISION` resolved when ambiguity prevents a plan |
| Scope expansion gate | Inline | `G_SCOPE_EXPANSION` approved or not needed |
| In-scope omission gate | Inline | `G_IN_SCOPE_OMISSION` approved or not needed |
| Commit loop | `scoped-commit-executor` | `COMMIT_EXECUTE: PASS` per group |
| Post-commit refresh | `scoped-state-summarizer` | Refreshed `SCOPED_STATE: PASS` adopted or `NO_SCOPED_CHANGES` |
| Report/status | Inline | Final report/status contract loaded for every stop |

## Subagent Registry

| Subagent | Path | Purpose |
| -------- | ---- | ------- |
| `scoped-state-summarizer` | `./subagents/scoped-state-summarizer.md` | Inspects scoped git state and local context, returning compact facts without raw patches |
| `commit-boundary-planner` | `./subagents/commit-boundary-planner.md` | Plans atomic commit groups, messages, checks, and required user decisions |
| `scoped-commit-executor` | `./subagents/scoped-commit-executor.md` | Creates one approved scoped commit after staged-diff review and verification |

Read a subagent file only when dispatching that subagent.

## Progressive Loading Policy

Load the smallest artifact that can change the next decision.

| Need | Load |
| ---- | ---- |
| Core orchestration and routing | This `SKILL.md` (always loaded) |
| Source-of-truth execution flow | `./flow-diagram.md` immediately after this file |
| Scope, atomic-commit, and detailed-message posture | `./references/personality.md` before state planning or reporting |
| Public URL routing for Git mechanics, commit grouping, message style, or progressive disclosure rationale | `./references/external-sources.md`, then fetch or pass only the URL relevant to the active specialist decision |
| Format final user-facing reports or waiting/terminal statuses | `./references/report-contract-orchestrator.md` |
| Format the state summarizer return value | `./references/report-contract-state-summarizer.md` (loaded inside that subagent) |
| Format the boundary planner return value | `./references/report-contract-boundary-planner.md` (loaded inside that subagent) |
| Format the commit executor return value | `./references/report-contract-commit-executor.md` (loaded inside that subagent) |
| Utility work | The single subagent file from the registry |

Pass only supplied relevant `REFERENCE_URLS` or freshly selected external URLs
to the specialist doing the work. Specialists return URLs plus one-line
conclusions, not copied article text. Bundled rules and user instructions
override web content.

## Core Decisions

- `CHANGE_PATHS` is the allow-list for commit candidates. Use
  `G_SCOPE_EXPANSION` before expanding scope and `G_IN_SCOPE_OMISSION` before
  leaving meaningful in-scope changes uncommitted.
- `APPROVED_COMMIT_SCOPE` is the executor's effective allow-list. It starts as
  `CHANGE_PATHS` and changes only by explicit `G_SCOPE_EXPANSION` approval.
- Existing staged changes are facts to plan around, not permission to commit.
  Staged content outside the approved group stays protected unless the plan and
  approved scope explicitly include it.
- Dispatch `scoped-state-summarizer` with `STATE_REFRESH_MODE=post-commit` for
  post-commit refresh because hooks, generated files, or concurrent workspace
  edits can change the next safe action. When the refresh returns
  `SCOPED_STATE: PASS`, adopt the refreshed scoped summary and refreshed
  `Reference need` as the source of truth before replanning or continuing;
  finish when refresh returns `NO_SCOPED_CHANGES`.
- For `COMMIT_EXECUTE: VERIFY_FAILED`, use `Recovery classification` to retry
  only the `same-scope-same-group-retry` outcome while the approved group's
  executor attempt counter is below three total attempts. Treat
  `needs-user-decision` as a waiting status and ask one targeted question. Treat
  `terminal` or attempts exhausted as `COMMIT_SCOPED_CHANGES: VERIFY_FAILED`.
  The initial executor dispatch is attempt 1, each same-group retry increments
  the counter before redispatch, and the counter resets when the group commits,
  the plan changes, or the next group begins.
- Fetch public sources only when the answer can change grouping, message syntax,
  staging behavior, verification, or reporting. Keep raw article text out of
  orchestrator context.
- Load `./references/report-contract-orchestrator.md` before returning any
  success, no-change, waiting, blocked, verification-failed, commit-error, or
  error status.

## Execution

1. Normalize inputs and confirm commit authority.
2. Dispatch `scoped-state-summarizer` with scope, context, style inputs, and
   only supplied relevant initial `REFERENCE_URLS` when they are already known.
3. If the state summary returns `SCOPED_STATE: PASS`, adopt that scoped summary
   and its `Reference need` as the current source of truth. If the adopted
   summary names a planner `Reference need`, look it up in
   `./references/external-sources.md` and pass only the matching URL to
   `commit-boundary-planner`.
4. Dispatch `commit-boundary-planner`. Ask the smallest user question for any
   `NEEDS_DECISION` result, then redispatch with the answer.
5. Apply `G_SCOPE_EXPANSION`; if the plan includes paths outside
   `CHANGE_PATHS`, ask the user to approve the exact extra paths, reason, risk,
   reversibility, and safer alternative before continuing. When approved, add
   only those exact paths to `APPROVED_COMMIT_SCOPE`; when no expansion is
   needed, keep `APPROVED_COMMIT_SCOPE=CHANGE_PATHS`.
6. Apply `G_IN_SCOPE_OMISSION`; if the plan leaves meaningful in-scope changes
   uncommitted, ask the user to approve the exact omitted changes, reason, risk,
   reversibility, and safer alternative before continuing.
7. Dispatch `scoped-commit-executor` once per approved group with
   `COMM