project-guide 2.6.0__tar.gz → 2.7.0__tar.gz

{project_guide-2.6.0 → project_guide-2.7.0}/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.7.0] - 2026-05-11
+
+New top-level `project-guide git-push` command — a thin wrapper over [gitbetter](https://github.com/pointmatic/gitbetter)'s `git-push` that auto-derives the commit subject from the most-recently-completed-and-not-yet-committed story in `docs/specs/stories.md`. Developer-lane convenience only; the LLM still does not initiate commits.
+
+### Added
+- **`project-guide git-push [BRANCH_NAME]` command** (`project_guide/cli.py`) — parses `docs/specs/stories.md` for the last `[Done]` story heading, derives a normalized commit subject (strip `### Story ` prefix and ` [Done]` suffix, convert backticks and double quotes to single quotes, preserve the colon after the story ID), and shells out to gitbetter's `git-push` via `shutil.which` discovery + `subprocess.run(check=False)` with no captured output (gitbetter inherits stdin/stdout/stderr and stays fully interactive). Child exit code propagates unchanged.
+- **Hard-error semantics** for ambiguous states: no `[Done]` story → exit 1; last `[Done]` already committed (per `git log --pretty=%s` subject-prefix match) → exit 1 with `Use 'git-push' directly for any follow-up commit.`; multiple uncommitted `[Done]` stories → exit 1 listing the IDs; `git-push` not on PATH → exit 1 with `brew install pointmatic/tap/gitbetter` hint. The wrapper deliberately refuses to second-guess the developer in ambiguous cases — raw `git-push` remains the escape hatch.
+- **`project_guide/stories.py`** — `StoryHeading` dataclass, `_read_done_stories()`, and `derive_commit_message()` as reusable helpers (the message transformer is exposed as a public name because the heading rules are part of the wrapper's documented contract).
+- **External CLI dependency pattern** documented in `docs/specs/tech-spec.md` under Cross-Cutting Concerns — `git-push` is the first project-guide subcommand depending on an external binary; future workflow-integration commands should follow the same shape (`shutil.which` discover, `subprocess.run(check=False)` invoke, propagate exit code).
+
+### Docs
+- `docs/specs/features.md` — new FR-15 (Story-Aware `git-push` Wrapper), added Inputs / Command Line entry, added Acceptance Criteria item 17.
+- `docs/specs/tech-spec.md` — added `git-push` to the Commands table, Key Functions documents the new helpers, new Cross-Cutting Concerns section "External CLI Dependencies (Story P.k pattern)".
+- `docs/specs/project-essentials.md` — new sub-section reinforcing the LLM-vs-developer-lane rule for this command and documenting the heading-derivation rules.
+- `README.md` — new `### git-push` section in Command Reference between `heal` and `override`, with the optional-dependency callout for gitbetter.
+
+## [2.6.1] - 2026-05-11
+
+Post-v2.6.0 follow-up: tighten the canonical `# project-guide` gitignore block from four lines to three. Behavior unchanged; the dropped line was functionally redundant.
+
+### Changed
+- **`project_guide/cli.py:_build_project_guide_block()`** — dropped the trailing `<target>/**/*.bak.*` line. The broader `<target>/**` rule introduced in v2.6.0 already ignores backups under that subtree, so the explicit line was a no-op carried over from the pre-P.d block during the policy inversion. New canonical form is three lines: header, `<target>/**`, `!<target>/go.md`.
+- **`project_guide/cli.py:_recognized_block_lines()`** — kept the `<target>/**/*.bak.*` entry in the recognized-lines set so v2.6.0-shipped installs heal cleanly to the v2.6.1 3-line form on the next `init --force`. Foreign hand-customized blocks remain warned-about (no behavior change there).
+- **Tests** — `_EXPECTED_GITIGNORE_BLOCK` updated to the 3-line form; added a test for the v2.6.0-→-v2.6.1 cleanup path on `init --force`.
+- **Docs** — updated the gitignore prose in `docs/specs/features.md`, `docs/specs/tech-spec.md`, `docs/specs/project-essentials.md`, and `README.md` to reflect the 3-line canonical form. Historical references to the 4-line v2.6.0 form retained where they explain the migration path.
+
+### Migration
+None required. v2.6.0 installs see no behavioral change — the dropped line was a no-op under the `<target>/**` rule. Running `init --force` on a v2.6.0 install simply produces a tidier 3-line block. Consumers who never run `init --force` keep the 4-line block forever without issue.
+
 ## [2.6.0] - 2026-05-09
 
 Phase P: Auto-heal and production hardening. Collapses the consumer-repo install footprint to a single tracked file (`go.md`) plus the tracked config; everything else is gitignored bundled data, repopulated on demand by a new self-contained `heal` command that runs invisibly before every other invocation. Bundled with a subset of post-1.0 production-readiness items: `SECURITY.md`, `CONTRIBUTING.md`, tightened `dependabot.yml`, and a CI-workflow PR-readiness audit.

{project_guide-2.6.0 → project_guide-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-guide
-Version: 2.6.0
+Version: 2.7.0
 Summary: Stay organized and in control with adaptive LLM workflow prompts.
 Project-URL: Homepage, https://github.com/pointmatic/project-guide
 Project-URL: Documentation, https://pointmatic.github.io/project-guide/
@@ -125,7 +125,7 @@ This creates:
 - `docs/project-guide/go.md` - Rendered LLM instructions (tracked — must be visible to IDE-integrated LLMs)
 - `docs/project-guide/` - Mode templates, artifact templates, and metadata (gitignored bundled data)
 
-Everything under `docs/project-guide/` is gitignored **except** `go.md` (which the LLM reads) and `.bak.*` backup files. The gitignored template tree is bundled static data — `project-guide heal` repopulates it on first invocation in a fresh clone, and the auto-hook makes that healing run silently before any other command.
+Everything under `docs/project-guide/` is gitignored **except** `go.md` (which the LLM reads). The gitignored template tree is bundled static data — `project-guide heal` repopulates it on first invocation in a fresh clone, and the auto-hook makes that healing run silently before any other command.
 
 ### 2. Tell your LLM to read the guide
 
@@ -374,6 +374,45 @@ project-guide heal
 project-guide heal --no-input
 ```
 
+### `git-push`
+
+Wrap [gitbetter](https://github.com/pointmatic/gitbetter)'s `git-push` with a commit message auto-derived from the most-recently-completed-and-not-yet-committed story in `docs/specs/stories.md`. Optional: requires gitbetter on PATH.
+
+```bash
+project-guide git-push [BRANCH_NAME]
+```
+
+**Arguments:**
+- `BRANCH_NAME` (optional) - Passed through to gitbetter for branch-aware push flows (e.g. switching to a feature branch and offering cleanup after merge)
+
+**Heading-to-message transformation:**
+```
+### Story G.a: v1.2.3 New command `foo` with "Hello" [Done]
+                                ↓
+       G.a: v1.2.3 New command 'foo' with 'Hello'
+```
+Backticks and double quotes become single quotes; single quotes pass through; the colon after the story ID is preserved (it's the anchor for the already-committed check).
+
+**Hard errors (exit 1):**
+- No `[Done]` story in `stories.md`
+- The last `[Done]` story is already committed — the wrapper does not second-guess; resolve manually with raw `git-push`
+- Multiple `[Done]` stories are uncommitted — commit them one at a time with explicit messages via raw `git-push`
+- `git-push` not on PATH — install gitbetter: `brew install pointmatic/tap/gitbetter`
+
+**Examples:**
+```bash
+# Most common: ready to commit the just-completed story to the current branch
+project-guide git-push
+
+# Feature-branch push (gitbetter switches to the branch first, offers cleanup after merge)
+project-guide git-push feature/heal-command
+```
+
+**Optional dependency.** gitbetter is not required for any other `project-guide` command. Install it only if you want this wrapper:
+```bash
+brew install pointmatic/tap/gitbetter
+```
+
 ### `override`
 
 Mark a file as customized to prevent automatic updates.

{project_guide-2.6.0 → project_guide-2.7.0}/README.md

@@ -89,7 +89,7 @@ This creates:
 - `docs/project-guide/go.md` - Rendered LLM instructions (tracked — must be visible to IDE-integrated LLMs)
 - `docs/project-guide/` - Mode templates, artifact templates, and metadata (gitignored bundled data)
 
-Everything under `docs/project-guide/` is gitignored **except** `go.md` (which the LLM reads) and `.bak.*` backup files. The gitignored template tree is bundled static data — `project-guide heal` repopulates it on first invocation in a fresh clone, and the auto-hook makes that healing run silently before any other command.
+Everything under `docs/project-guide/` is gitignored **except** `go.md` (which the LLM reads). The gitignored template tree is bundled static data — `project-guide heal` repopulates it on first invocation in a fresh clone, and the auto-hook makes that healing run silently before any other command.
 
 ### 2. Tell your LLM to read the guide
 
@@ -338,6 +338,45 @@ project-guide heal
 project-guide heal --no-input
 ```
 
+### `git-push`
+
+Wrap [gitbetter](https://github.com/pointmatic/gitbetter)'s `git-push` with a commit message auto-derived from the most-recently-completed-and-not-yet-committed story in `docs/specs/stories.md`. Optional: requires gitbetter on PATH.
+
+```bash
+project-guide git-push [BRANCH_NAME]
+```
+
+**Arguments:**
+- `BRANCH_NAME` (optional) - Passed through to gitbetter for branch-aware push flows (e.g. switching to a feature branch and offering cleanup after merge)
+
+**Heading-to-message transformation:**
+```
+### Story G.a: v1.2.3 New command `foo` with "Hello" [Done]
+                                ↓
+       G.a: v1.2.3 New command 'foo' with 'Hello'
+```
+Backticks and double quotes become single quotes; single quotes pass through; the colon after the story ID is preserved (it's the anchor for the already-committed check).
+
+**Hard errors (exit 1):**
+- No `[Done]` story in `stories.md`
+- The last `[Done]` story is already committed — the wrapper does not second-guess; resolve manually with raw `git-push`
+- Multiple `[Done]` stories are uncommitted — commit them one at a time with explicit messages via raw `git-push`
+- `git-push` not on PATH — install gitbetter: `brew install pointmatic/tap/gitbetter`
+
+**Examples:**
+```bash
+# Most common: ready to commit the just-completed story to the current branch
+project-guide git-push
+
+# Feature-branch push (gitbetter switches to the branch first, offers cleanup after merge)
+project-guide git-push feature/heal-command
+```
+
+**Optional dependency.** gitbetter is not required for any other `project-guide` command. Install it only if you want this wrapper:
+```bash
+brew install pointmatic/tap/gitbetter
+```
+
 ### `override`
 
 Mark a file as customized to prevent automatic updates.

{project_guide-2.6.0 → project_guide-2.7.0}/docs/specs/features.md

@@ -81,6 +81,10 @@ For a high-level concept (why), see [`concept.md`](concept.md). For implementati
 **`project-guide heal`**
 - Optional: `--no-input` (auto-yes the `[Y/n]` prompt; emit a one-line stderr notice when writes occur — auto-enabled by `CI=1`, `PROJECT_GUIDE_NO_INPUT=1`, or non-TTY stdin)
 
+**`project-guide git-push [BRANCH_NAME]`**
+- Optional positional `BRANCH_NAME` — passed through to gitbetter's `git-push` for branch-aware push flows
+- No other flags — the wrapped command is fully interactive (preview, confirm, branch cleanup, reject/recovery menu), so `--no-input` / `--quiet` would be no-ops; for those, route through raw `git-push` instead
+
 **`project-guide override FILE_NAME REASON`**
 - Required: file name (template-relative path)
 - Required: reason for override
@@ -127,7 +131,7 @@ Only `.project-guide.yml` (config) and `docs/project-guide/go.md` (rendered LLM
 ```
 project-root/
 ├── .project-guide.yml              # Configuration (tracked)
-├── .gitignore                      # `# project-guide` block: ignore everything under target_dir except go.md and *.bak.*
+├── .gitignore                      # `# project-guide` block: ignore everything under target_dir except go.md
 └── docs/
     └── project-guide/
         ├── go.md                   # Rendered entry point (tracked in git — required for IDE LLM visibility)
@@ -242,7 +246,7 @@ The system renders a single entry-point document (`go.md`) from Jinja2 templates
 1. Copy template tree from package to target directory (default: `docs/project-guide`)
 2. Render `go.md` in `default` mode
 3. Create `.project-guide.yml` with current version, target directory, metadata file path, and `default` mode
-4. Add `*.bak.*` entries to `.gitignore` under a `# project-guide` comment (the rendered `go.md` is tracked in git so the LLM can read it)
+4. Write the canonical `# project-guide` block to `.gitignore` (3 lines: ignore everything under `target_dir` except `go.md` — the LLM reads it and IDE-integrated LLMs hide gitignored files from the LLM's view; see FR-14)
 5. Report number of files installed
 
 **Edge Cases:**
@@ -372,7 +376,29 @@ The bundled `templates/artifacts/pyve-essentials.md` artifact covers: two-enviro
 - `.project-guide.yml` is absent (let `init` bootstrap; the hook does not error).
 - The config fails to load (schema mismatch, parse error) — the subcommand surfaces the error with its own guidance.
 
-**Inverted gitignore policy.** `init`'s gitignore writer ignores everything under `target_dir` except `go.md` and `.bak.*` backups. The remaining template tree is bundled static data that `heal` repopulates on first invocation. This eliminates the ~35-file install footprint from consumer-repo `git status` and PR reviews. Consumers migrating from a pre-Phase-P install run `project-guide init --force` to refresh the gitignore block; `git rm --cached` is the manual cleanup for previously tracked files.
+**Inverted gitignore policy.** `init`'s gitignore writer produces a canonical 3-line block under a `# project-guide` header: ignore everything under `target_dir` *except* `go.md` (tightened from the original 4-line v2.6.0 form in v2.6.1 — the explicit `.bak.*` line was redundant with the broader `**` rule). The remaining template tree is bundled static data that `heal` repopulates on first invocation. This eliminates the ~35-file install footprint from consumer-repo `git status` and PR reviews. Consumers migrating from a pre-Phase-P install run `project-guide init --force` to refresh the gitignore block; `git rm --cached` is the manual cleanup for previously tracked files. v2.6.0 installs heal to the v2.6.1 3-line form on the next `init --force`.
+
+### FR-15: Story-Aware `git-push` Wrapper (gitbetter integration)
+
+`project-guide git-push [BRANCH_NAME]` wraps [gitbetter](https://github.com/pointmatic/gitbetter)'s `git-push` with story metadata: it derives the commit message from the most-recently-completed-and-not-yet-committed story in `docs/specs/stories.md` and shells out to gitbetter to perform the actual push. The wrapper collapses the developer's per-story commit step from "find the story ID, format the message, type the command" to a single command, while delegating every real git operation (preview, confirm, branch cleanup, reject/recovery menu) to gitbetter.
+
+**Heading-to-message transformation:**
+- Input: `### Story G.a: v1.2.3 New command \`foo\` with "Hello" [Done]`
+- Output: `G.a: v1.2.3 New command 'foo' with 'Hello'`
+- Rules: strip `### Story ` prefix and ` [Done]` suffix; replace backticks and double quotes with single quotes; preserve single quotes and the colon after the story ID. The colon is the anchor the already-committed check searches for in `git log --pretty=%s`.
+
+**Hard errors (exit 1):**
+- `docs/specs/stories.md` is absent.
+- No `[Done]` story in `stories.md`.
+- The last `[Done]` story is already committed (per `git log` subject prefix match) — the wrapper does not second-guess; the developer resolves manually with raw `git-push`.
+- Multiple `[Done]` stories are uncommitted — same reasoning. The wrapper is for the common "one story done, ready to push" case; multi-story batches are explicit-is-better-than-implicit.
+- `git-push` is not on PATH — the wrapper prints the install hint (`brew install pointmatic/tap/gitbetter`) and exits.
+
+**Child-process semantics.** The wrapper invokes `git-push` via `subprocess.run(argv, check=False)` with no captured output, so gitbetter inherits the parent's stdin/stdout/stderr and stays fully interactive. The child's exit code is propagated to `sys.exit` unchanged so gitbetter's reject/recovery menu surfaces with real semantics.
+
+**LLM-vs-developer-lane.** This is a developer-lane convenience command. The LLM **does not** initiate it — the approval-gate discipline (do not propose commits, pushes, or follow-ups at story-end) remains in force. The wrapper is invoked by the developer after the LLM presents a completed story.
+
+**`spec_artifacts_path` resolution.** The wrapper reads `spec_artifacts_path` from project-guide metadata when available; otherwise falls back to `docs/specs`. This lets the wrapper work in projects that haven't yet run `project-guide init`, including this project itself before metadata renders.
 
 ### FR-7: Shell Completion
 
@@ -500,3 +526,4 @@ modes:
 14. Package is published to PyPI as `project-guide`
 15. `project-guide heal` (FR-14) is **silent on no drift** and applies fixes after the `[Y/n]` prompt on drift; under `--no-input` / `CI=1` / non-TTY the prompt is replaced with auto-yes plus the `Auto-healing N templates under --no-input.` stderr notice
 16. The auto-hook fires for every CLI invocation including `--help` and `--version`, is silent in the steady state, recursion-guarded by `PROJECT_GUIDE_HEALING=1`, and never blocks the original subcommand on prompt decline
+17. `project-guide git-push [BRANCH_NAME]` (FR-15) derives the commit message from the last `[Done]` story, hard-errors on already-committed or multi-uncommitted-Done states or missing gitbetter, and propagates gitbetter's child exit code unchanged

{project_guide-2.6.0 → project_guide-2.7.0}/docs/specs/project-essentials.md

@@ -63,11 +63,11 @@ The hook is silent in the steady state (no drift → no output). It is recursion
 
 **Skip conditions:** the hook returns silently when `PROJECT_GUIDE_HEALING=1` is set, when `.project-guide.yml` is absent (let `init` bootstrap; `heal` would error otherwise), or when config load / drift detection fails. Missing `.project-guide.yml` is a hard error from the **`heal` subcommand itself** but a silent skip from the **hook** — the original subcommand surfaces the missing-config error with its own guidance.
 
-### Inverted gitignore policy (added v2.6.0)
+### Inverted gitignore policy (added v2.6.0, tightened v2.6.1)
 
-`init`'s gitignore writer ignores everything under `target_dir` except `go.md` and `.bak.*` backups (Story P.d). The remaining template tree is bundled static data that `heal` repopulates on first invocation in a fresh clone, so tracking it in the consumer repo would just add ~35 files of noise to `git status` and PR reviews.
+`init`'s gitignore writer produces a canonical 3-line block: ignore everything under `target_dir` *except* `go.md` (Story P.d wrote the inversion; Story P.j / v2.6.1 dropped a redundant `.bak.*` line that the original block carried over from the pre-P.d shape). The remaining template tree is bundled static data that `heal` repopulates on first invocation in a fresh clone, so tracking it in the consumer repo would just add ~35 files of noise to `git status` and PR reviews.
 
-**Idempotent rewrite:** `_ensure_gitignore_entry()` recognizes the new canonical block plus the legacy `.bak.*`-only form (and the legacy `<target>/go.md` line) and rewrites them cleanly. A foreign hand-customized block under a `# project-guide` header is left untouched with a stderr warning; migrate manually or run `init --force`.
+**Idempotent rewrite:** `_ensure_gitignore_entry()` recognizes the v2.6.1 canonical block plus prior forms (the v2.6.0 4-line block, the pre-P.d `.bak.*`-only block, and the legacy `<target>/go.md` line) and rewrites all of them cleanly to the v2.6.1 3-line form. A foreign hand-customized block under a `# project-guide` header is left untouched with a stderr warning; migrate manually or run `init --force`.
 
 ### IDE-LLM visibility constraint (added v2.6.0)
 
@@ -94,3 +94,20 @@ Auto-healing N templates under --no-input.
 ```
 
 The notice is **non-suppressible** (always emitted even with `--quiet`) so CI logs and embedding callers (pyve scaffolding, etc.) have a visible signal that file writes occurred. This is the heal-specific application of the `--no-input` contract documented earlier in this file.
+
+### `project-guide git-push` is developer-lane (added v2.7.0)
+
+`project-guide git-push` is a thin wrapper over [gitbetter](https://github.com/pointmatic/gitbetter)'s `git-push` that auto-derives the commit message from the most-recently-completed-and-not-yet-committed `[Done]` story heading. It is a **developer-lane convenience command** — the LLM **must not** initiate it. The approval-gate discipline rule earlier in this file ("do not propose commits, pushes, or bundling options ... do not offer 'want me to also …?' follow-ups") remains in force, and applies to this wrapper just as it does to raw `git`. The wrapper exists to shorten the developer's typing at commit time, not to give the LLM a new excuse to volunteer commits.
+
+**Heading-to-message rules:**
+- Output is `"<id>: <title>"`. The colon after the story ID is preserved — it is the anchor the already-committed check searches for in `git log --pretty=%s` via the regex `^([A-Z]\.[a-z]+):\s`.
+- Backticks (`` ` ``) in the title become single quotes.
+- Double quotes (`"`) in the title become single quotes.
+- Single quotes pass through unchanged. The wrapper invokes gitbetter via `subprocess.run([...], shell=False)`, so there is no shell-quoting concern.
+
+**Branch logic:**
+- 0 uncommitted `[Done]` stories → exit 1 "Story <last id> is already committed."
+- 1 uncommitted `[Done]` story → derive message, invoke `git-push`.
+- 2+ uncommitted `[Done]` stories → exit 1 listing the IDs; developer commits them one at a time with raw `git-push`.
+
+**External CLI dependency pattern.** `git-push` is the first `project-guide` subcommand that depends on an external binary being on PATH. See `tech-spec.md` § "External CLI Dependencies" for the canonical pattern (discover via `shutil.which`, invoke via `subprocess.run(..., check=False)` with no captured output, propagate exit code). Future workflow-integration commands should follow the same shape.

{project_guide-2.6.0 → project_guide-2.7.0}/docs/specs/stories.md

@@ -34,7 +34,7 @@ Collapse the `docs/project-guide/` install footprint in consumer repos to a sing
 
 **Implementation order:** `heal` core (P.a) → auto-hook (P.b) → `--no-input` semantics (P.c) → gitignore template flip (P.d). Production hardening items (P.e–P.h) are independent and can ship in any order. P.i is the doc-only story that bundles the v2.6.0 release.
 
-**Version cadence:** phase-bundled — stories within Phase P run unversioned; **P.i owns the single `v2.6.0` bump** at end-of-phase (per the bundled-release option in the Version Cadence rule).
+**Version cadence:** phase-bundled — stories P.a–P.i ran unversioned and shipped together as **v2.6.0** (P.i owned the single bundled bump). **Stories P.j and P.k were added post-bundle** and follow standard per-story cadence: **P.j → v2.6.1** (patch — gitignore-block tightening, a fix-up to P.d), **P.k → v2.7.0** (minor — new `git-push` wrapper command). Phases can be extended after their bundled release, but new stories then follow the standard per-story cadence rather than rejoining the (already-shipped) bundle.
 
 ### Story P.a: Heal command with drift detection and create-missing semantics [Done]
 
@@ -192,6 +192,76 @@ Doc-only release bundling story for Phase P. Updates the spec artifacts, README,
 - [x] Bump `pyproject.toml`: `version = "2.6.0"`
 - [x] Add `## [2.6.0] - <date>` entry to `CHANGELOG.md` summarizing all of Phase P's user-visible changes (heal command, auto-hook, gitignore inversion, SECURITY.md, CONTRIBUTING.md, dependabot, CI tightening)
 
+### Story P.j: v2.6.1 Drop redundant `.bak.*` line from canonical gitignore block [Done]
+
+Tighten the canonical `# project-guide` gitignore block from four lines to three by removing the `<target>/**/*.bak.*` line — it is already covered by the broader `<target>/**` rule introduced in P.d. The fourth line was carried over from the pre-P.d block during the policy inversion and is functionally redundant under the new shape. **Existing installs are not at risk:** `_recognized_block_lines()` continues to recognize the old line, so `init --force` cleanly rewrites a v2.6.0-style 4-line block to the v2.6.1 3-line form.
+
+- [x] In `project_guide/cli.py:_build_project_guide_block()`: remove the trailing `f"{target_dir}/**/*.bak.*\n"` line. New canonical form:
+  ```
+  # project-guide
+  <target>/**
+  !<target>/go.md
+  ```
+- [x] In `project_guide/cli.py:_recognized_block_lines()`: **keep** the `f"{target_dir}/**/*.bak.*"` entry in the recognized set so a v2.6.0-shipped 4-line block is treated as "ours" and rewritten on `init --force` rather than warned about as foreign.
+- [x] In `tests/test_cli.py`:
+  - [x] Update `_EXPECTED_GITIGNORE_BLOCK` to the 3-line form
+  - [x] Update `test_init_force_rewrites_old_recognized_block_cleanly` to verify the test case where the prior block is the v2.6.0 4-line form (recognized → rewritten to 3-line) in addition to the existing legacy-`.bak.*`-only case *(split into two tests: `test_init_force_rewrites_legacy_bak_only_block_cleanly` for the pre-P.d shape and `test_init_force_rewrites_v260_four_line_block_to_three_lines` for the v2.6.0→v2.6.1 cleanup)*
+  - [x] Update `test_init_with_existing_canonical_block_is_idempotent` so the seed block is the new 3-line form *(picked up via the `_EXPECTED_GITIGNORE_BLOCK` rebind)*
+  - [x] All assertions that the `.bak.*` line is present should be removed
+- [x] Doc updates (bundled in this story):
+  - [x] `docs/specs/features.md`: update the Outputs / File Structure prose that currently lists `.bak.*` as a separate exception — the only tracked file under `target_dir` is `go.md`; `.bak.*` is just one of the many things subsumed by the broad `**` rule
+  - [x] `docs/specs/tech-spec.md`: update the `## .gitignore Management` code block from 4 lines to 3, and refresh the surrounding prose
+  - [x] `docs/specs/project-essentials.md`: amend the "Inverted gitignore policy" sub-section added in P.i to note the v2.6.1 simplification (the `.bak.*` line was redundant and was removed; existing v2.6.0 blocks heal on `init --force`)
+  - [x] `README.md`: update the Quick Start step-1 footnote to drop the "and `.bak.*` backup files" callout — `.bak.*` is no longer a separate exception, just one of the things ignored by `<target>/**`
+- [x] Bump `project_guide/version.py`: `__version__ = "2.6.1"`
+- [x] Bump `pyproject.toml`: `version = "2.6.1"`
+- [x] Add `## [2.6.1] - <date>` entry to `CHANGELOG.md` (this is a follow-up tightening of P.d; the v2.6.0 entry stays as historical record of what actually shipped, including the redundant line)
+
+**Migration:** none required. Consumer repos running v2.6.0 see identical *behavior* under v2.6.1 (the gitignore semantics don't change — the redundant line was a no-op). Running `init --force` on a v2.6.0 install simply produces a tidier 3-line block. Consumers who never run `init --force` keep the 4-line block forever without issue.
+
+### Story P.k: v2.7.0 `project-guide git-push` wrapper for gitbetter [Done]
+
+Add a new `project-guide git-push [BRANCH_NAME]` command that auto-derives the commit message from the most-recently-completed-and-not-yet-committed story heading in `docs/specs/stories.md` and shells out to [gitbetter](https://github.com/pointmatic/gitbetter)'s `git-push` to perform the actual push. Collapses the developer's per-story commit step from "find the story ID, format the message correctly, type the command" to a single command, while delegating every actual git operation (preview, confirm, branch cleanup, reject/recovery menu) to gitbetter.
+
+This is a developer-lane convenience command. **The LLM still does not initiate it** — the approval-gate discipline rule in `project-essentials.md` remains in force, and this story's doc updates reinforce that explicitly so future LLMs don't start offering `project-guide git-push` as a follow-up.
+
+- [x] Story detection (`project_guide/stories.py` or a small new helper):
+  - [x] Parse `docs/specs/stories.md` for the **last** `### Story <ID>: ... [Done]` heading in file order *(implemented as `_read_done_stories()` returning **all** `[Done]` headings; the "last" rule emerges naturally from the "0 / 1 / 2+ uncommitted" branch logic)*
+  - [x] When no `[Done]` story exists, exit 1 with stderr `No completed story found in <stories.md>.`
+  - [x] When `stories.md` is absent, exit 1 with stderr matching the existing `_read_stories_summary` no-stories behavior *(emits `Error: docs/specs/stories.md not found.`)*
+- [x] Commit-message derivation:
+  - [x] Input form: `### Story G.a: v1.2.3 New command \`foo\` with "Hello" [Done]`
+  - [x] Output form: `G.a: v1.2.3 New command 'foo' with 'Hello'`
+  - [x] Transformations: strip `### Story ` prefix, strip ` [Done]` suffix, replace each backtick with a single quote, replace each double quote with a single quote. Single quotes in the original heading pass through unchanged (no shell quoting concerns because the wrapper invokes gitbetter via `subprocess.run([...], shell=False)`)
+  - [x] Preserve the colon after the story ID (matches the project's commit-message convention and is the anchor the already-committed check searches for)
+- [x] Already-committed detection (Q5 → hard error):
+  - [x] Run `git log --pretty=%s` and scan for a subject line whose prefix matches `<story_id>: ` (e.g., `G.a: `)
+  - [x] If found, exit 1 with stderr `Story <ID> is already committed. Use 'git-push' directly for any follow-up commit.` — the developer resolves manually rather than the wrapper second-guessing
+- [x] Multi-uncommitted-story detection (Q3 → hard error):
+  - [x] If more than one `[Done]` story in the file has no matching `git log` subject, exit 1 with stderr listing the IDs and pointing the developer at raw `git-push` to commit them one at a time with explicit messages
+- [x] gitbetter invocation:
+  - [x] Detect `git-push` on PATH via `shutil.which("git-push")`; on miss, exit 1 with stderr `git-push not found on PATH. Install gitbetter: brew install pointmatic/tap/gitbetter`
+  - [x] Build argv: `["git-push", message]` plus `[branch_name]` when provided
+  - [x] `subprocess.run(argv, check=False)`; propagate the child's exit code unchanged so gitbetter's reject/recovery menu surfaces to the developer with its real exit semantics
+- [x] CLI surface (`project_guide/cli.py`):
+  - [x] New `@main.command(name="git-push")` with optional `BRANCH_NAME` positional
+  - [x] No `--quiet` / `--no-input` plumbing — the wrapped command is fully interactive, so the flags would be no-ops
+  - [x] Help text cites gitbetter, the brew install command, and the auto-message-derivation rules
+- [x] Tests in `tests/test_cli.py`: 11 new tests under `--- Story P.k ---`. Covers happy path, branch-name passthrough, all heading transforms (plain, backticks-only, double-quotes-only, both, single-quote passthrough, no-version doc-only form), already-committed error, multi-uncommitted error, no-Done error, stories.md missing, `git-push` missing on PATH, and child-exit-code propagation.
+- [x] Doc updates (bundled in this story per the version-bumping rule — code story owns its own doc churn):
+  - [x] `docs/specs/features.md`: new functional requirement (FR-15 or next) for the wrapper; add to Inputs / Command Line; add an Acceptance Criteria item
+  - [x] `docs/specs/tech-spec.md`: add `git-push` to the CLI Design / Commands table; document the `shutil.which` discovery + `subprocess.run` exit-code-propagation pattern under Cross-Cutting Concerns *(added as new "External CLI Dependencies (Story P.k pattern)" section so future wrappers follow the same shape)*
+  - [x] `README.md`: new `### git-push` section in Command Reference between `update` (or `heal`) and `override`; make the gitbetter dependency clearly optional and link the install command
+  - [x] `docs/specs/project-essentials.md`: append a sub-section covering (a) the message-derivation rules, (b) the **LLM-vs-developer-lane reminder** — `project-guide git-push` is invoked by the developer after the LLM presents a completed story; the LLM still does not initiate commits per the approval-gate discipline
+- [x] Bump `project_guide/version.py`: `__version__ = "2.7.0"`
+- [x] Bump `pyproject.toml`: `version = "2.7.0"`
+- [x] Add `## [2.7.0] - <date>` CHANGELOG entry summarizing the new command and gitbetter integration
+
+**Out of scope (revisit if demand):**
+- Passthrough of gitbetter's other flags (`--amend`, `--keep`, `--force-with-lease`). The wrapper accepts only `BRANCH_NAME`; everything else routes through raw `git-push`.
+- A parallel `project-guide git-tag` wrapper. gitbetter has one but the project's release process already uses `bump-version` + raw `git tag`, so the value is lower.
+- Pre-flight `pyve test` / `ruff check` gates before invoking gitbetter. The developer runs those during the story's normal cycle before marking `[Done]`, so re-running them at push time is redundant.
+
 ---
 
 ## Future

{project_guide-2.6.0 → project_guide-2.7.0}/docs/specs/tech-spec.md

@@ -121,18 +121,22 @@ project-guide/
 | `status` | Grouped status: Mode, Guide, Files (with `--verbose`) |
 | `update` | Hash-based sync with prompt/force/dry-run |
 | `heal` | Silent-when-clean drift repair with create-missing semantics; fires automatically before every other command via the group-level auto-hook |
+| `git-push [BRANCH_NAME]` | Wrap gitbetter's `git-push` with a commit message derived from the last `[Done]` story heading; shells out via `shutil.which` + `subprocess.run`, propagates child exit code |
 | `override` | Lock a file from updates |
 | `unoverride` | Remove a file lock |
 | `overrides` | List all locked files |
 | `purge` | Remove all project-guide files with confirmation |
 
 **Key functions:**
-- `_ensure_gitignore_entry(target_dir)` — writes the canonical `# project-guide` block: ignore everything under `target_dir` except `go.md` and `*.bak.*`. Idempotent. Recognized prior blocks (legacy `.bak.*`-only form, legacy `<target>/go.md` line) are rewritten cleanly; foreign hand-customized content under a `# project-guide` header is left alone with a stderr warning.
+- `_ensure_gitignore_entry(target_dir)` — writes the canonical `# project-guide` block: ignore everything under `target_dir` except `go.md` (3-line form as of P.j / v2.6.1). Idempotent. Recognized prior blocks (pre-P.d `.bak.*`-only form, v2.6.0 4-line form with the redundant `.bak.*` line, legacy `<target>/go.md` line) are rewritten cleanly to the v2.6.1 3-line form; foreign hand-customized content under a `# project-guide` header is left alone with a stderr warning.
 - `_copy_template_tree(src, dest, force)` — recursive copy preserving structure
 - `_migrate_config_if_needed()` — renames legacy `.project-guides.yml`
 - `_apply_heal(config, config_path)` — apply pending template syncs and re-render `go.md`. Sets `PROJECT_GUIDE_HEALING=1` in `os.environ` before doing any writes so nested subprocess invocations don't re-enter the auto-hook.
 - `_run_pre_invoke_hook()` — group-level auto-heal hook (Story P.b/c). Calls `should_skip_input()` to honor the `--no-input` contract via env / TTY signals; silent when no drift; prompts on drift in interactive mode; auto-yes + `Auto-healing N templates under --no-input.` stderr notice in skip-input mode.
 - `HealGroup(click.Group)` — custom Click group whose overridden `main()` runs `_run_pre_invoke_hook()` before `super().main()`, so `--help` and `--version` (eager flags that would otherwise short-circuit during arg parsing) still trigger the hook.
+- `_get_committed_story_ids()` — parses `git log --pretty=%s` and extracts story IDs from any subject line whose prefix matches `<id>: ` (regex `^([A-Z]\.[a-z]+):\s`). Returns an empty set on `git`-not-found, non-git cwd, or empty history. Used by the `git-push` wrapper to decide which `[Done]` stories are uncommitted.
+- `_resolve_spec_artifacts_path()` — best-effort resolver for the `spec_artifacts_path` metadata value used by `git-push` to locate `stories.md`. Falls back to `docs/specs` when config / metadata are unavailable so the wrapper works in projects that haven't yet run `init`.
+- `project_guide/stories.py:_read_done_stories()` / `derive_commit_message()` — pure helpers used by `git-push`. `_read_done_stories` returns all `[Done]` headings as `StoryHeading(story_id, title)` tuples in file order; `derive_commit_message` produces the gitbetter-ready subject `"<id>: <transformed title>"` (backticks → single quotes, double quotes → single quotes, single quotes pass through, colon preserved).
 
 ### Module: `config.py` (138 lines)
 
@@ -266,17 +270,18 @@ class ModeDefinition:
 
 ### `.gitignore` Management
 
-`init` writes a canonical 4-line block under a `# project-guide` comment header (Story P.d):
+`init` writes a canonical 3-line block under a `# project-guide` comment header (Story P.d, tightened in P.j / v2.6.1):
 ```
 # project-guide
 docs/project-guide/**
 !docs/project-guide/go.md
-docs/project-guide/**/*.bak.*
 ```
 
 **Why this shape:** every file under `target_dir` except `go.md` is bundled static data that `heal` (FR-14) repopulates on first invocation, so tracking the full template tree in the consumer repo would just add ~35 files of noise to `git status` and PR reviews. `go.md` itself **must remain tracked** because IDE-integrated LLMs (Cursor, Claude Code, etc.) typically hide gitignored files from the LLM's view, and the LLM's instruction to `Read docs/project-guide/go.md` requires the file to be visible. The repo-history value of `go.md` is incidental — the file churns on every mode switch — and that churn is the acceptable cost for LLM visibility.
 
-**Existing-block detection:** `_ensure_gitignore_entry()` is idempotent. A recognized prior block (either the new canonical form or the legacy `.bak.*`-only form) is rewritten cleanly. A foreign hand-customized block under a `# project-guide` header is left untouched with a stderr warning. A `.gitignore` with no `# project-guide` header gets the canonical block appended (separated by a blank line). Migration for pre-Phase-P consumer repos: `project-guide init --force` rewrites the block; `git rm --cached` is the manual cleanup for already-tracked files.
+**Why not the explicit `.bak.*` line that v2.6.0 shipped?** It was carried over from the pre-P.d block during the policy inversion but is functionally redundant: the `<target>/**` rule already ignores backups produced by sync/heal under that subtree. P.j dropped the line; existing v2.6.0 installs heal cleanly to the 3-line form on `init --force` because `_recognized_block_lines()` still lists the v2.6.0 entry.
+
+**Existing-block detection:** `_ensure_gitignore_entry()` is idempotent. A recognized prior block (the v2.6.1 canonical form, the v2.6.0 4-line form, or the pre-P.d `.bak.*`-only form) is rewritten cleanly to the v2.6.1 3-line form. A foreign hand-customized block under a `# project-guide` header is left untouched with a stderr warning. A `.gitignore` with no `# project-guide` header gets the canonical block appended (separated by a blank line). Migration for pre-Phase-P consumer repos: `project-guide init --force` rewrites the block; `git rm --cached` is the manual cleanup for already-tracked files.
 
 ---
 
@@ -337,6 +342,17 @@ Fail fast with actionable messages:
 - `.project-guides.yml` → `.project-guide.yml` (automatic rename on any CLI command)
 - v1.x config detection → migration notice in `status` output
 
+### External CLI Dependencies (Story P.k pattern)
+
+`git-push` is the first `project-guide` subcommand that **depends on an external CLI being on PATH** (gitbetter's `git-push` binary). Future workflow-integration commands (potential `git-tag`, `git-rebase`, etc.) should follow the same pattern:
+
+1. **Discover** via `shutil.which(name)`. If `None`, exit 1 with stderr that names the missing tool and the canonical install command. Never silently fall back to a degraded behavior.
+2. **Invoke** via `subprocess.run(argv, check=False)` with **no captured output** so the external tool inherits the parent's stdin/stdout/stderr (interactive flows like prompts and progress reporting must reach the developer unaltered).
+3. **Propagate** the child's exit code with `sys.exit(result.returncode)`. The wrapper's own exit semantics are a passthrough — the external tool's reject/recovery semantics are the source of truth, not the wrapper's.
+4. **Tests** mock both `shutil.which` (to control discovery) and `subprocess.run` (to control the child's behavior and capture argv). See `tests/test_cli.py::test_git_push_*` for the reference test shape.
+
+This deliberately keeps each wrapper a thin convenience layer rather than a parallel implementation. The tested invariants are: discovery error message, argv shape (including positional passthrough), and exit-code propagation. Nothing else.
+
 ### Auto-Heal Group Hook (Phase P)
 
 Every `project-guide` invocation runs the heal drift-detection + prompt path before dispatching the requested subcommand. This is implemented as a custom `HealGroup(click.Group)` whose overridden `main()` calls `_run_pre_invoke_hook()` before delegating to `super().main()`. Running before `super().main()` is deliberate: it places the hook **ahead of `make_context` / arg parsing**, which is what makes the hook fire even for `--help` and `--version` (eager flags that would otherwise short-circuit before any subcommand or group body runs).