@laitszkin/apollo-toolkit 3.8.3 → 3.9.0

package/CHANGELOG.md

@@ -34,6 +34,17 @@ All notable changes to this repository are documented in this file.
 ### Added
 - (None yet)
 
+## [v3.9.0] - 2026-05-05
+
+### Changed
+- Refine agent-facing descriptions and workflow copy across planning, review, and submission skills (`commit-and-push`, `version-release`, `generate-spec`, `implement-specs*`, `develop-new-features`, `enhance-existing-features`, `review-spec-related-changes`, `solve-issues-found-during-review`, `maintain-skill-catalog`, `align-project-documents`, `maintain-project-constraints`); keep CI-visible contract wording aligned with `test/skill-workflows.test.js`.
+
+## [v3.8.4] - 2026-05-04
+
+### Changed
+- Simplify `generate-spec` checklist template from 108 lines to 53 lines: consolidate multi-field behavior-to-test items into single-line checkboxes, flatten hardening records, and streamline E2E/integration decisions and completion records
+- Emphasize official documentation lookup as mandatory step in `generate-spec` workflow
+
 ## [v3.8.0] - 2026-04-30
 
 ### Added

package/align-project-documents/SKILL.md

@@ -1,158 +1,86 @@
 ---
 name: align-project-documents
-description: Read the entire codebase, then generate standardized project documentation under docs/features/, docs/architecture/, and docs/principles/ from code evidence. Remove old documentation that does not conform to the template structure, then refresh AGENTS.md/CLAUDE.md via maintain-project-constraints.
+description: >-
+  Regenerate standardized tree `docs/features` (BDD zero code paths), `docs/architecture` (macro layer rules), `docs/principles` (evidence-backed conventions) after reading the ENTIRE production codebase—legacy scattered Markdown must migrate or be removed before finish then invoke **`maintain-project-constraints`** so AGENTS/CLAUDE indexes match disk.
+  Use for repo-wide doc realignments (“rebuild project docs from code”)—skip for single-file README nitpicks unless user explicitly requests full regeneration.
+  Violation examples: features mentioning `src/foo.ts`… acceptable feature: “Given signed-in user When export Then CSV downloads”… architecture stays stable if module renamed internally…
 ---
 
 # Align Project Documents
 
 ## Dependencies
 
-- Required: `maintain-project-constraints` to refresh `AGENTS.md/CLAUDE.md` after documentation changes.
+- Required: `maintain-project-constraints` after `docs/` work to refresh `AGENTS.md`/`CLAUDE.md` and the doc index.
 - Conditional: none.
 - Optional: none.
-- Fallback: not applicable.
+- Fallback: If `maintain-project-constraints` cannot run, **MUST NOT** pretend the constraints files are refreshed—report the gap.
 
-## Standards
+## Non-negotiables
 
-- Evidence: Treat source code, configuration, scripts, and tests as the sole source of truth.
-- Execution: Read the entire codebase before writing any documentation; ground every claim in concrete file paths.
-- Quality: Remove outdated documentation that does not conform to the template structure; never leave mixed documentation formats in place.
-- Output: Produce standardized, maintainable documentation organized into three categories: features, architecture, and principles.
+- **MUST** read the **entire** codebase (all meaningful source/config/test entrypoints—not a single-folder sample) **before** writing category docs; code is sole truth—existing prose is corroborating only.
+- **MUST NOT** ship `docs/features/` bullets that cite file paths, function names, or implementation detail—user-facing **BDD** only (`Given` / `When` / `Then`).
+- **`docs/architecture/`** stays **macro** (layers, boundaries, data-flow direction)—**MUST NOT** document code that will rot on every refactor.
+- **`docs/principles/`** **MUST** remain traceable to **concrete** repo patterns (with examples)—not aspirational platitudes without evidence.
+- **MUST** create or refresh `docs/features/`, `docs/architecture/`, `docs/principles/` with categorized files; **MUST** remove or migrate stale non-conforming docs (**MUST NOT** leave mixed legacy layout alongside new structure indefinitely).
+- **MUST** invoke **`maintain-project-constraints`** after category docs stabilize so `AGENTS.md`/`CLAUDE.md` indexes match disk.
+- Default doc **language**: match user preference or repo’s dominant README/docs language consistently per run.
 
-## Goal
+## Standards (summary)
 
-Generate a complete, code-grounded project documentation set under `docs/` that describes what the system does from a user perspective (features), how it is designed (architecture), and what conventions govern its code (principles).
+- **Evidence**: Paths and reads logged while building claims; contradictory old docs flagged, not blindly merged.
+- **Execution**: Whole repo read → ingest old docs → write three pillars → prune → constraints refresh.
+- **Quality**: Features user-only; architecture stable abstractions; principles evidence-backed.
+- **Output**: Standardized tree + synced agent constraint files.
 
-## Target Documentation Structure
+## Target structure
 
 ```
 docs/
-├── features/       — BDD-described user-facing capabilities, categorized by functional area
-├── architecture/   — macro-level design principles, organized by module or layer
-└── principles/     — code style, naming conventions, dependency management, and development constraints
+├── features/       — User-facing capability, BDD only (no code paths)
+├── architecture/   — Layers/modules, boundaries, integration contracts (macro)
+└── principles/     — Style, tooling, conventions with codebase examples
 ```
 
-### docs/features/
-
-- Describe what the system does from a user's perspective.
-- Never reference specific code paths, file names, or implementation details.
-- Use BDD (Behavior-Driven Development) phrasing: "Given ... When ... Then ...".
-- Group features by functional category; each category gets its own markdown file.
-- File titles must clearly convey which functional area or module they cover.
-
-Example feature description:
-
-```markdown
-# 用戶認證與授權
-
-## 登入
-
-- **Given** 用戶擁有有效的帳號密碼
-- **When** 用戶提交登入表單
-- **Then** 系統驗證憑證並返回存取令牌，用戶進入主頁面
-```
-
-### docs/architecture/
-
-- Extract macro-level design principles from the codebase.
-- Group principles by module or architectural layer; each module gets its own markdown file.
-- Every principle must be sufficiently abstract to avoid becoming stale after minor code changes.
-- Focus on module responsibilities, boundary rules, data flow direction, and integration contracts — not on specific implementation details.
-
-Example architecture principle:
-
-```markdown
-# API 層設計原則
-
-## 路由與處理器分離
-
-路由定義與請求處理邏輯存放在不同模組中。路由層只負責 URL 映射與中介軟體綁定，
-處理器層負責請求解析、業務邏輯調用與回應組裝。
-```
-
-### docs/principles/
-
-- Extract code style, naming conventions, and development constraints from the codebase.
-- Categorize into separate markdown files (e.g., naming conventions, dependency management, error handling patterns).
-- Each principle must be traceable to concrete examples in the codebase.
-
-Example principle:
-
-```markdown
-# 命名約定
-
-## 檔案命名
-
-- TypeScript 模組檔案使用 kebab-case：`user-service.ts`
-- React 元件檔案使用 PascalCase：`UserProfile.tsx`
-- 測試檔案與被測檔案同名，加上 `.test` 後綴：`user-service.test.ts`
-```
+Extended rules and checklist: `references/templates/standardized-docs-template.md`.
 
 ## Workflow
 
-### 1) Read the entire codebase
-
-- Read every source file in the repository to build a complete mental model.
-- Pay special attention to:
-  - Entry points (CLI commands, server startup, job runners)
-  - Public-facing interfaces (API routes, CLI commands, UI pages)
-  - Module boundaries and dependency directions
-  - Configuration files, environment variables, and external service integrations
-  - Test files that document expected behavior
-- Record concrete file paths as evidence for every claim that will appear in documentation.
-
-### 2) Read existing project documentation as reference
+**Chain-of-thought:** **`Pause →`** after each major phase; ambiguity on “user-visible” vs “internal” ⇒ re-read callers before classifying.
 
-- Enumerate all existing documentation files (`README.md`, `docs/**`, `CONTRIBUTING.md`, etc.).
-- Extract factual claims that can be cross-referenced with the codebase.
-- Note gaps where documentation is missing or outdated.
-- Treat existing docs as secondary sources; code is always the primary source of truth.
+### 1) Read entire codebase
 
-### 3) Generate new documentation following the template structure
+- Cover entrypoints (CLI/server/workers), public surfaces, boundaries, configs, integrations, tests as behavior specs.
+- Keep an **evidence notebook** (paths) for principles and architecture—not for features text.
+  - **Pause →** Did I skip generated/vendor/`node_modules`/binary blobs incorrectly included as “must read”?
+  - **Pause →** Can I name the **top five** externally visible behaviors from code alone?
 
-- Create `docs/features/`, `docs/architecture/`, and `docs/principles/` directories if they do not exist.
-- For each category, classify findings from the codebase and write focused markdown files.
-- Titles must be descriptive and immediately tell the reader what the file covers.
-- Write in the user's language unless the repository clearly uses a different documentation language.
+### 2) Read existing prose
 
-**Features generation checklist:**
-- Identify all user-facing capabilities from routes, CLI commands, UI pages, and job outputs.
-- Group into functional categories (e.g., authentication, data export, notifications).
-- Write BDD scenarios for each feature using Given/When/Then.
-- Each file covers one functional category.
+- List `README.md`, `docs/**`, `CONTRIBUTING.md`, etc.; extract facts that code confirms; flag obsolete sections.
+  - **Pause →** Where did I treat Markdown as authoritative over a contradicted implementation?
 
-**Architecture generation checklist:**
-- Identify major modules or layers from the codebase directory structure and import graph.
-- For each module, extract the design principles that govern its structure and boundaries.
-- Keep principles at the macro level; avoid principles that would need updating for minor code changes.
-- Each file covers one module or architectural layer.
+### 3) Generate three pillars
 
-**Principles generation checklist:**
-- Identify recurring patterns in code style, naming, error handling, dependency management, and testing.
-- Categorize patterns into separate files (e.g., `coding-style.md`, `naming-conventions.md`, `dependency-management.md`).
-- Support each principle with a brief rationale traceable to the codebase.
+- **features/**: categories → one markdown per category → BDD scenarios only.
+- **architecture/**: one file per layer/module cluster → boundaries and flows, stable wording.
+- **principles/**: split files (`naming-conventions.md`, etc.) → each point ties to observable repo habit.
+  - **Pause →** Random feature paragraph: grep for `./src` or `` ` `` — if found, rewrite for user observable outcome only.
 
-### 4) Remove old documentation that does not conform
+### 4) Remove non-conforming legacy
 
-- Scan `docs/` and the repository root for documentation files that do not fit the new structure.
-- Remove any documentation file whose content has been fully migrated into the new structure.
-- Keep only files that belong to the new structure or have not yet been migrated.
-- When in doubt, preserve the file and note it as a candidate for later migration.
+- Delete or migrate files fully superseded; if uncertain, **keep** file list in report as migration backlog — **do not** silently duplicate two competing truths forever.
 
-### 5) Update AGENTS.md/CLAUDE.md via maintain-project-constraints
+### 5) Refresh constraints
 
-- After the new documentation is complete, invoke `maintain-project-constraints` to refresh `AGENTS.md/CLAUDE.md`.
-- `maintain-project-constraints` will read the codebase (or the newly generated docs), extract macro business goals, write them to `AGENTS.md`/`CLAUDE.md`, and maintain the project document index.
+- Run **`maintain-project-constraints`** so Commands / Business Goals / Doc Index mirror new files.
 
-## Quality Gate (must pass before finishing)
+### 6) Gates before finish
 
-- Every feature description is written from a user perspective with no code references.
-- Every architecture principle is macro-level and resilient to minor code changes.
-- Every code principle is traceable to concrete examples in the codebase.
-- All generated files have descriptive, scannable titles.
-- No stale documentation remains that duplicates or contradicts the new structure.
-- `maintain-project-constraints` has been run and `AGENTS.md`/`CLAUDE.md` is up to date.
+- No code paths in features; architecture still macro after imagined small refactor; principles cite real examples; index lists every file under the three dirs; constraints skill executed.
 
-## Reference Template
+## Sample hints
 
-- `references/templates/standardized-docs-template.md`: describes the three-category documentation structure, writing rules, and quality checklist for each category.
+- **Feature OK**: “Given a signed-in user When they export Then a CSV download starts” — no `handlers/export.rs` references.
+- **Feature bad**: “Call `ExportService.run` …” — violates Non-negotiables (implementation leak).
+- **Architecture OK**: “API layer handles I/O only; domain module owns business rules” — stable across internal renames.
+- **Principle OK**: “TypeScript files use kebab-case — see `src/user-profile/`” — traceable pattern.

package/commit-and-push/SKILL.md

@@ -1,94 +1,71 @@
 ---
 name: commit-and-push
-description: "Guide the agent to submit local changes with commit and push only (no versioning). Use when users ask to commit, submit, or push changes without requesting tag/version/release operations. Depend directly on `archive-specs` when completed plan sets should become durable docs or when project docs need alignment, and let that skill own the downstream documentation synchronization work."
+description: >-
+  Commit and push only (no semver): inspect staged vs unstaged, classify scopes, run mandated reviews (`review-change-set`, conditional `discover-edge-cases`/`harden-app-security`), **`submission-readiness-check`** BEFORE final commit honoring `CHANGELOG.md` Unreleased + `archive-specs` redirections, preserve intentional staging splits, forbid UI git stubs, VERIFY remote hashes post-push **`version-release` elsewhere**.
+  Use for “please commit”, “submit”, “push branch” lacking explicit semver/tag language **STOP** tagging here… BAD skip readiness red… GOOD staged subset untouched unrelated dirty files changelog mirrors diff… hashes `git rev-parse HEAD` versus upstream… archive specs before commit flagged…
 ---
 
 # Commit and Push
 
 ## Dependencies
 
-- Required: `submission-readiness-check` before the final commit.
-- Conditional: `archive-specs` when completed plan sets should be converted or repository docs need alignment; `review-change-set` is required for code-affecting changes; `discover-edge-cases` and `harden-app-security` are important review gates that remain conditional, but become required whenever the reviewed scope or risk profile warrants them.
+- Required: **`submission-readiness-check`** immediately before the **final** commit.
+- Conditional: **`archive-specs`** when readiness (or completed specs) requires doc conversion or categorized `docs/` alignment; **`review-change-set`** for every **code-affecting** scope; **`discover-edge-cases`** and **`harden-app-security`** become **required** when classification/risk indicates (same scope)—treat as blocking, not polish.
 - Optional: none.
-- Fallback: If any required dependency is unavailable, stop and report the missing dependency.
+- Fallback: Any **required** dependency unavailable ⇒ **MUST** stop and report—**MUST NOT** “light” commit.
 
-## Standards
+## Non-negotiables
 
-- Evidence: Inspect git state and classify the change set before deciding which quality gates apply, then compare the actual pending diff against root `CHANGELOG.md` `Unreleased` before committing, while also distinguishing the staged surface from additional unstaged work before deciding commit scope.
-- Execution: Run the required quality-gate skills when applicable, and treat every conditional gate whose scenario is met as blocking before submission; hand the repository to `submission-readiness-check` for readiness classification, invoke `archive-specs` directly whenever completed plan sets should be converted or project docs need alignment, preserve staging intent, honor any explicit user-specified target branch, and when the worktree is already clean inspect local `HEAD`, upstream state, and the most recent relevant commit before deciding the request is a no-op; when worktree-based delivery is involved, verify where the authoritative target branch lives before moving history, re-validate on that target branch after replay or merge, and remove the temporary worktree only after the target branch is safely updated; when the user asks for multiple commits or a narrower staged subset, keep those commit boundaries explicit instead of broadening scope implicitly; then commit and push without release steps; run dependent git mutations sequentially and verify the remote branch actually contains the new local `HEAD` before reporting success, and never treat UI directives such as `::git-stage`, `::git-commit`, or `::git-push` as substitutes for actual git commands or as evidence that submission already happened.
-- Quality: Re-run relevant validation for runtime changes, preserve unrelated local work safely when branch switching or post-push local sync is required, do not bypass blocking readiness findings such as missing/stale `Unreleased` bullets or unsynchronized project docs, and never collapse intentionally separated commit scopes just because related unstaged changes are present.
-- Output: Produce a concise Conventional Commit, push it to the intended branch, and report any temporary stash/restore, commit-scope separation, or local branch sync that was required.
+- **MUST** use real `git` mutations (`git add`, `git commit`, `git push`, `git stash`, etc.); **MUST NOT** treat UI tokens (`::git-commit`, IDE buttons) as proof of history.
+- **MUST** run **`submission-readiness-check`** before final commit; unresolved readiness (e.g. stale/missing `CHANGELOG.md` **Unreleased**, doc drift) **blocks** commit.
+- Code-affecting: **`review-change-set` MANDATORY**; unresolved confirmed findings **block**. When risk profile matches, **`discover-edge-cases`** / **`harden-app-security`** equally blocking.
+- **`archive-specs`**: when readiness says convert/archive or `docs/` mismatch—**MUST** run **before** final commit, not as a vague follow-up.
+- **MUST** reconcile **staged vs unstaged** with user intent—**MUST NOT** broaden scope by auto-staging unrelated files when user staged a subset.
+- **`CHANGELOG.md` `Unreleased`**: for code-affecting or user-visible docs, **MUST** reflect this change before commit; reopen diff after edits to match commit scope.
+- **MUST** resolve **target branch** per user (or current if explicit) before rewriting history; protect unrelated dirty work (`stash` etc.); **no** force-push unless user explicitly requests.
+- After **push**, **MUST** verify remote tip matches local `HEAD` (`git rev-parse` / `@{u}` / `ls-remote`) before claiming success.
+- **MUST NOT** run version bump, tag, or GitHub release (**use `version-release`**).
+- Clean worktree requests: **MUST** inspect `HEAD`, upstream, last commit—**MUST NOT** fabricate “pushed” when already satisfied or impossible.
 
-## References
+**Repository regression checks (verbatim requirements):** Treat root `CHANGELOG.md` `Unreleased` coverage as mandatory for code-affecting or user-visible changes. Re-open the final `CHANGELOG.md` diff after readiness updates. **`review-change-set` is required for code-affecting changes**; Run `review-change-set` for every code-affecting change before continuing; treat unresolved review findings as blocking. Any conditional gate whose trigger is confirmed by this classification becomes mandatory before commit. Treat every scenario-matched gate as blocking before commit. **`discover-edge-cases` and `harden-app-security` are important review gates**—when their scenario is met, treat them as blocking review gates, not optional polish.
+
+## Standards (summary)
 
-Load only when needed:
+- **Evidence**: `git status`/`diff`; classification drives gates; changelog diff matches commit.
+- **Execution**: Inspect → classify → (deps) → readiness → commit → push verify.
+- **Quality**: No gate bypass; sequential git ops; preserve intentional commit boundaries.
+- **Output**: Conventional commit message + confirmed remote + note stash/scope if any.
+
+## References
 
 - `references/commit-messages.md`
 - `references/branch-naming.md`
 
 ## Workflow
 
-1. Inspect current state
-   - Run `git status -sb`, `git diff --stat`, and `git diff --cached --stat`.
-   - Check staged files with `git diff --cached --name-only`.
-   - Compare the staged and unstaged surfaces explicitly so you can tell whether the user already prepared a narrower commit than the full worktree diff.
-   - Inventory repository planning artifacts and project docs, not only staged files, to detect repo specs and non-standard documentation layouts.
-   - If the worktree is already clean, inspect `git log -1 --stat`, local `HEAD`, and the configured upstream state before concluding there is nothing to submit; use that evidence to determine whether the requested work was already committed and pushed, committed but not pushed, or never landed.
-2. Classify changes
-   - `code-affecting`: runtime code, tests, build scripts, CI logic, or behavior-changing config.
-   - `docs-only`: content updates only (for example README, docs, comments).
-   - `repo-specs-present`: the repository contains live project planning artifacts such as `spec.md`, `tasks.md`, `checklist.md`, or plan directories; exclude reference examples, templates, and archived samples.
-   - `repo-specs-ready-for-conversion`: the relevant `spec.md`, `tasks.md`, and `checklist.md` have been updated to reflect the actual outcome of the work, and any unchecked task/decision checkbox that is clearly not selected, replaced, deferred, or `N/A` (for example, E2E intentionally not created) does not by itself mean the spec set is unfinished.
-   - `project-doc-structure-mismatch`: existing `README.md` and project docs do not match the categorized structure required by `archive-specs`.
-   - Treat a spec set as still active when it documents remaining implementation gaps, follow-up integration work, undecided design work, or deferred tasks that still belong to the same in-flight change.
-   - Any conditional gate whose trigger is confirmed by this classification becomes mandatory before commit, including review, spec archival, docs synchronization, and changelog updates.
-3. Resolve branch target before mutating history
-   - Treat an explicit user-specified destination such as `main`, `origin/main`, or another named branch as authoritative over the current branch.
-   - If the current branch does not match the requested destination, inspect `git status --short` for unrelated local changes before switching branches.
-   - Preserve unrelated uncommitted work safely before branch operations, for example with `git stash push`, and restore it after the target branch has been updated.
-   - If the fix was committed on the wrong branch, move it to the requested branch with safe history-preserving operations such as `cherry-pick`, `merge --ff-only`, or a clean replay; do not force-push unless the user explicitly asks for it.
-   - If the user asks to sync the local target branch after pushing, fast-forward or pull that branch locally and then restore any preserved worktree changes.
-   - If the implementation lives in a detached or temporary `git worktree`, inspect both the temporary worktree and the main worktree before deciding the replay method.
-   - When the main worktree already contains staged or partially overlapping copies of the same changes, compare file content and branch tips first; do not create an unnecessary merge commit when a direct replay onto the authoritative target branch is safer.
-   - When the worktree diff is broader than the requested issue, stop and separate the requested commit scope before replaying anything to the target branch.
-4. Run code-affecting dependency skills (when applicable)
-   - Run `review-change-set` for every code-affecting change before continuing; treat unresolved review findings as blocking.
-   - Run `discover-edge-cases` and `harden-app-security` for the same code-affecting scope when the reviewed risk profile or repository context says their coverage is needed; treat them as blocking review gates, not optional polish, whenever that condition is met.
-   - Consolidate and resolve all confirmed findings before continuing.
-   - Re-run relevant tests when runtime logic changes.
-5. Run shared submission readiness
-   - Execute `$submission-readiness-check` after code/doc scans are complete and before the final commit.
-   - Let it decide whether completed plan sets should be converted, whether project docs need alignment through `archive-specs`, and whether `CHANGELOG.md` is blocking submission.
-   - Do not continue to commit while `submission-readiness-check` reports unresolved readiness blockers.
-   - Treat root `CHANGELOG.md` `Unreleased` coverage as mandatory for code-affecting or user-visible changes: if the current work is not reflected there yet, update it before committing instead of merely noting the gap.
-   - Re-open the final `CHANGELOG.md` diff after readiness updates and confirm the `Unreleased` bullets describe the same scope as the commit you are about to create.
-   - When readiness indicates doc conversion or project-doc drift, run `archive-specs` before the final commit instead of duplicating documentation alignment work locally.
-6. Commit
-   - Preserve user staging intent where possible.
-   - If the user explicitly asks for separate commits, or the staged set is already a deliberate subset of the worktree, keep those scopes separated and do not auto-stage the remaining diff unless the user expands the requested scope.
-   - If the user later broadens the requested scope, restate the new grouping, verify it against the actual staged/unstaged surfaces, and only then create the additional commit(s).
-   - Use actual `git add` / `git commit` operations; do not emit UI git directives as a stand-in for repository mutations.
-   - Write a concise Conventional Commit message using `references/commit-messages.md`.
-7. Push
-   - Push commit(s) to the intended branch.
-   - Do not overlap `git commit`, `git push`, branch switching, or post-push sync operations; wait for each mutation to finish before starting the next one.
-   - After pushing, verify the remote branch tip matches the local `HEAD`, for example by comparing `git rev-parse HEAD` with the target branch hash from `git rev-parse @{u}` or `git ls-remote --heads <remote> <branch>`.
-   - If the push result is ambiguous, out of order, or the hashes do not match, rerun the missing git step sequentially and re-check before reporting success.
-   - Confirm the local branch state matches the user's requested destination when post-push synchronization was requested.
-   - When the user explicitly asks to merge work back from a temporary worktree and delete that worktree, do the final verification on the authoritative target branch first, then remove the temporary worktree and prune stale worktree records before reporting completion.
-   - Do not claim success based on emitted UI directives or optimistic status text alone; remote-hash verification is the required evidence.
-
-## Notes
-
-- Never run version bump, tag creation, or changelog release steps in this skill.
-- Treat every scenario-matched gate as blocking before commit, not as an optional reminder to maybe do later.
-- Never skip `review-change-set` for code-affecting changes, and do not continue past review while confirmed findings remain unresolved.
-- Never downgrade `discover-edge-cases` or `harden-app-security` to optional follow-up when the change risk says they apply.
-- Never claim the repository is ready to commit while root `CHANGELOG.md` `Unreleased` is missing the current change or still describes superseded work.
-- Never fabricate a commit/push result when the worktree is already clean; either identify the exact existing commit/upstream state that satisfies the user's request or say that no matching new submission exists.
-- Never treat `::git-stage`, `::git-commit`, `::git-push`, or similar UI helpers as proof that repository history was mutated; rely on actual git command results plus local/remote hash checks.
-- Never delete a temporary worktree before the target branch has been updated, tested, and verified to contain the intended final content.
-- Never auto-stage or auto-merge unrelated unstaged changes into a commit when the user or current index state already defines narrower commit boundaries.
-- If release/version/tag work is requested, use `version-release` instead.
-- If a new branch is required, follow `references/branch-naming.md`.
-- A pushed implementation can still leave an active spec set behind; commit completion and spec archival are separate decisions.
+**Chain-of-thought:** **`Pause →`** guards skipping a gate or mis-sizing scope.
+
+1. **Inspect** — `git status -sb`; `git diff --stat`; `git diff --cached --stat`; `git diff --cached --name-only`. If clean: `git log -1 --stat`, upstream tracking, whether work already pushed.
+   - **Pause →** Is the user’s intended commit **exactly** the staged set, or full worktree—I must not mix them silently?
+
+2. **Classify** — Tag mentally: `code-affecting` | `docs-only` | `repo-specs-present` | `repo-specs-ready-for-conversion` | `project-doc-structure-mismatch` (per `archive-specs` needs). Active specs with unfinished same-change work stay active.
+   - **Pause →** Which conditional skills just became **mandatory**—did I list them explicitly?
+
+3. **Branch target** — Honor user branch; if switch needed, protect unrelated changes; cherry-pick/replay off wrong branch safely; worktree cases: identify authoritative target **before** replay.
+   - **Pause →** Am I about to merge noise because diff > issue scope—should I stop and narrow first?
+
+4. **Code-affecting gates** — `review-change-set` always; add `discover-edge-cases` / `harden-app-security` when risk/trigger says so; fix or document blockers; re-test material logic.
+
+5. **Readiness** — Run **`submission-readiness-check`**; if it routes to **`archive-specs`**, run that **now**; fix `Unreleased` bullets; recheck changelog vs staged intent.
+   - **Pause →** Could I commit while readiness still red—**why not**?
+
+6. **Commit** — Respect staging; separate commits if user asked; Conventional message per `references/commit-messages.md`.
+
+7. **Push** — Sequential; verify remote hash; sync local branch after if user asked; worktree cleanup **only after** target branch verified good.
+   - **Pause →** What two hashes prove remote == local?
+
+## Sample hints
+
+- **Scope**: Staged `foo.ts` only; unstaged `bar.ts` unrelated → commit **must not** pick up `bar.ts` without user scope change.
+- **Changelog**: Code change with no `Unreleased` bullet → **blocking** until added.
+- **Push proof**: “Pushed” means e.g. local `abc123` equals `origin/feature` `abc123`, not “command sent.”