project-guide 2.7.2__tar.gz → 2.9.0__tar.gz

{project_guide-2.7.2 → project_guide-2.9.0}/.project-guide.yml

@@ -1,8 +1,8 @@
 version: '2.0'
-installed_version: 2.7.2
+installed_version: 2.8.0
 target_dir: docs/project-guide
 metadata_file: .metadata.yml
-current_mode: debug
+current_mode: code_direct
 test_first: false
 pyve_version: pyve version 2.6.2
 project_name: project-guide

{project_guide-2.7.2 → project_guide-2.9.0}/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.9.0] - 2026-05-20
+
+**`project-guide git-push` learns to read and write bundled commits (P.u).** When a developer commits multiple `[Done]` stories under one bundled subject (e.g., `H.a, H.b, H.c InputSource ...`), the wrapper now correctly recognizes all bundled IDs as committed instead of misreporting them as uncommitted. When 2+ `[Done]` stories remain uncommitted, the wrapper offers a bundled commit subject with a `[Y/n]` gate rather than forcing the developer to hand-type one. A new duplicate-`<id>` warning surfaces git-log anomalies where the same story ID appears in multiple commits.
+
+### Added
+- **P.u — Bundled-commit recognition in already-committed check.** `parse_committed_ids_from_subject` (new, in `project_guide/stories.py`) extracts the full ordered list of story IDs from a commit subject across single-ID, legacy `Story <id>:`, legacy bundle (no colons), canonical unversioned bundle (`H.a, H.b, H.c: title`), per-story-versioned bundle (`H.j: v0.10.0, H.k: v0.11.0 title`), mixed-version bundle, and single-trailing-version bundle forms. The parser is permissive on read (every `:` optional) and the formatter is strict on emit (colon precedes a version or a title, never separates two bare IDs).
+- **P.u — Bundle-offer flow.** When 2+ uncommitted `[Done]` stories exist, the wrapper proposes a bundled commit subject `<id1>[: <ver1>], <id2>[: <ver2>], ... <title1> + <title2> + ...` and prompts `Use this message? [Y/n]` (default `Y`). Accept → invoke `git-push` with the bundled message. Decline → exit 1 with the existing `"use git-push directly"` manual-resolution hint. New `derive_bundle_commit_message` formatter in `project_guide/stories.py` handles per-story version detection, backtick / double-quote sanitization (same rules as single-story), title joining with `" + "`, and whitespace trim-and-collapse on the final subject.
+- **P.u — Duplicate-`<id>` warning.** When the same bare story ID appears in 2+ commit subjects in `git log`, the wrapper emits a stderr warning listing each duplicate ID and the offending subjects, and prompts `Continue? [Y/n]` (default `Y`). The version is incidental — duplicate detection is keyed on `<id>` only, so a story shipped under two different versions still surfaces.
+- **P.u — `--no-input` flag on `git-push`.** New `--no-input/--input` option auto-declines both the bundle offer and the duplicate-`<id>` continuation prompt (also auto-enabled by `CI=1` or non-TTY stdin per the standard `--no-input` contract). Auto-no is chosen for both gates because accepting either would change the shape of a commit (or paper over a history anomaly) silently — a developer decision, not a CI default.
+
+### Changed
+- **P.u — `_get_committed_story_ids` return type.** The helper now returns `tuple[set[str], dict[str, list[str]]]` (committed-IDs set + duplicates map) instead of `set[str]`. This is an internal-only API; no public surface affected.
+- **P.u — Commit-subject parser location.** Retired `_COMMIT_SUBJECT_STORY_ID_RE` from `project_guide/cli.py` (introduced by P.k, made permissive in P.s) in favor of the structured `parse_committed_ids_from_subject` parser in `project_guide/stories.py`. Tests that referenced the regex directly have been migrated to call the parser.
+- **P.u — `project-essentials.md` `git-push` section.** Expanded with the bundle-offer flow, the colon-precedes-version-or-title rule, the duplicate-`<id>` warning, the `--no-input` defaults, and the parse-permissive / emit-strict invariant.
+
+### Fixed
+- **P.u — Field bug: bundled commits no longer misclassified as uncommitted.** Pre-P.u, a bundled commit like `H.a, H.b, H.c InputSource ...` was invisible to the single-ID regex, so all bundled stories appeared "uncommitted" on the next `git-push` invocation — the wrapper either re-proposed the oldest one or fell through to the multi-uncommitted error path. Now correctly recognized.
+
+## [2.8.0] - 2026-05-20
+
+**Phase P closing bundle: cycle-mode LLM-workflow discipline + XP methodology grounding + untracked-by-default `go.md` policy.** Six stories shipped between v2.7.2 and v2.8.0 (P.n–P.s). The one consumer-visible behavior change is the new tracked-`go.md` heal warning and the matching `git rm --cached docs/project-guide/go.md` consumer migration (P.o); the remaining five stories are template/doc reshapes that change how the LLM behaves on the next `project-guide mode <X>` render, with no consumer migration required.
+
+### Changed
+- **P.o — Untracked-by-default `go.md` policy.** `project_guide/cli.py:heal` now detects when `docs/project-guide/go.md` is in the consumer's git index and emits a stderr warning with a copyable migration command (`git rm --cached docs/project-guide/go.md && git commit`). Silent when go.md is untracked, when cwd is not a git repo, under the recursion guard, or under `--no-input`. `project_guide/cli.py:init` emits a stderr note after the initial render that `go.md` is intentionally untracked. The warning is non-fatal and never runs git operations itself — same wrapper-initiates-git-ops constraint that bounded the P.k `git-push` wrapper.
+- **P.s — Permissive commit-subject regex.** `_COMMIT_SUBJECT_STORY_ID_RE` now accepts both the bare `<id>: <title>` form (canonical going forward; matches `derive_commit_message`'s output) and the legacy `Story <id>: <title>` form (still seen in consumer repos). Resolves a field bug where mixed-form commit history caused the `git-push` wrapper to miss `Story `-prefixed commits and emit a spurious "multiple uncommitted" error.
+
+### Added
+- **P.p — Three-flavor spike taxonomy.** `developer/best-practices-guide.md`'s "Hello World First — Spike Early, Spike Often" section now documents three spike flavors: **integration spike** (will external systems connect?), **architectural spike** (Beck-canonical; will this design work?), **investigation spike** (is there a viable path at all?). Each flavor has a question-answered framing, triggers, and output. New section closing with the canonical 3-story foundation table (A.a Scaffolding / A.b Hello World / A.c integration spike).
+- **P.p — XP methodology grounding.** New top-level section in `developer/best-practices-guide.md` covering lineage (Beck 1999, C3 team), why XP practices counter known LLM failure modes (test-first vs. "looks right" hallucination, small steps vs. context-window drift, spikes vs. fabricated confidence, documented decisions vs. invisible scope creep, pair-style developer/LLM rotation), and a bibliography (Beck 1999/2004, Jeffries/Anderson/Hendrickson 2000).
+- **P.p — Inserting-a-new-story rules.** New "Inserting a new story" subsection in `_phase-letters.md` covering Append (default) / Sub-number extension / Renumber (last-resort) with both P.s-triage precision rules: Sub-number is valid only when the parent is the latest top-level committed ID; Renumber is valid only on working-tree-only IDs.
+- **P.q — Four cycle-discipline rules** in `_header-common.md`'s universal Rules block: **Sequential, story-by-story documentation**, **Documentation timing** (default write-then-execute + debug exception, on-disk-before-gate invariant), **Spikes for uncertainty reduction** (cross-references P.p's three-flavor taxonomy), **Approval-gate documentation handoff** (LLM authors the story before pausing, not after the developer asks).
+- **P.q — Debug-mode Step-5 reinforcement.** New "Documentation timing in `debug`" paragraph names debug as the one legitimate exception to the universal timing rule and states explicitly that the LLM authors the story. New **"Deferring the Gate Artifact to the Developer"** anti-pattern entry sibling to "Declaring the Fix Complete After Step 4."
+- **P.r — Mode echo + step-name conventions** in `_header-common.md`: the "After reading" protocol now has `**First line, always:** "Mode: <mode_name>."` as the always-first line, and a new universal Rules-block bullet requires step references to include the step's name in parens on first mention (e.g., "Cycle Step 1 (read stories) done; per Step 2 (announce next story), …").
+
+### Fixed
+- **P.n — Scope-of-authority guardrail.** Closed a drift path where cycle modes could rationalize creating new `## Phase` headings in `stories.md`. New universal Rules-block bullet plus debug-mode Step-5 "Scope reminder" paragraph: cycle modes may append stories under an *existing* phase and edit story bodies, but may **not** create new phase headings, re-theme existing phases, or move stories between phases — phase creation is the exclusive job of `plan_phase` / `plan_production_phase`.
+- **P.p — Foundation-story reconciliation.** Three docs (`plan-stories-mode.md`, `developer/best-practices-guide.md`, `developer/project-guide.md`) previously disagreed on the foundation-story structure (3-story vs. 2-story; A.a "Hello World" vs. A.a Scaffolding). Reconciled to the canonical 3-story foundation that `plan-stories-mode.md` already produces: **A.a Scaffolding** (in `scaffold_project` mode), **A.b Hello World** (runtime self-proof), **A.c integration spike** (integration self-proof). The terminology rename "end-to-end stack spike" → "integration spike" propagated across `plan-stories-mode.md`, `plan-phase-mode.md`, and `plan-production-phase-mode.md`.
+- **P.s docs reconciliation.** Commit-message examples across `project-essentials.md`, `code-direct-mode.md`, `best-practices-guide.md`, and `production-github-guide.md` flipped from the legacy `"Story <id>: <title>"` form to the bare `"<id>: <title>"` form (canonical; matches the wrapper's emitted output).
+- **P.t (this release) — Foundation cleanup follow-up.** Fixed stale "Start with Story A.a (Hello World)" line in `code-direct-mode.md:39` left over from P.p's reconciliation (A.a is now Scaffolding; A.b is Hello World; A.c is the integration spike).
+- **P.t (this release) — Refactor modes now author session-level stories.** Closed the gap surfaced by P.t's mode-template audit: `refactor-plan-mode.md` and `refactor-document-mode.md` did not previously create `stories.md` entries, leaving refactor work outside the universal P.q Rule 1 "every chunk of LLM-produced work is captured as a story" invariant. Both modes now have a new **Session Story** section (authored once per session, after Step 1 of the first document; checklist captures one task per document touched + the project-essentials revisit for `refactor_plan`) and a closing **Session Close** / **Step F.5** that flips the checklist `[x]`, marks the story `[Done]`, defers the version-bump decision to the developer, and presents the session story at a session-level gate distinct from the per-document gates. One refactor session = one story = one developer commit.
+
+### Migration
+Consumers upgrading from v2.6.x – v2.7.x: run once on your default branch to migrate `go.md` to untracked-by-default per the new policy:
+```bash
+git rm --cached docs/project-guide/go.md && git commit -m "untrack go.md per project-guide v2.8.0"
+```
+`heal` continues to warn until the migration is applied. Consumers who never migrate continue to function — `go.md` keeps appearing in their working-tree diff on every mode switch, but no command fails. See P.o's body in `docs/specs/stories.md` for full rationale. No migration required for the five template/doc stories beyond the standard `project-guide update` on next invocation.
+
 ## [2.7.2] - 2026-05-19
 
 Bug fix: `project-guide git-push` (and version/phase detection) silently dropped sub-numbered story IDs (`J.m.1`, `J.m.2`, …). When the latest `[Done]` story used the sub-numbered form, the wrapper fell back to the previous bare-letter heading and reported it as "already committed," blocking the push of the new story.

{project_guide-2.7.2 → project_guide-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-guide
-Version: 2.7.2
+Version: 2.9.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/
@@ -122,11 +122,19 @@ project-guide init
 
 This creates:
 - `.project-guide.yml` - Configuration file (tracked)
-- `docs/project-guide/go.md` - Rendered LLM instructions (tracked — must be visible to IDE-integrated LLMs)
+- `docs/project-guide/go.md` - Rendered LLM instructions (**unignored but intentionally untracked** as of v2.8.0 — must be visible to IDE-integrated LLMs, but kept out of git so branch switches don't trip on it)
 - `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). 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.
 
+**Upgrading from v2.6.x – v2.7.x?** Earlier project-guide versions left `go.md` tracked by historical accident. v2.8.0 flips the policy to untracked-by-default to eliminate branch-switch and merge friction. If `heal` warns that `go.md` is tracked, run once on your default branch:
+
+```bash
+git rm --cached docs/project-guide/go.md && git commit -m "untrack go.md per project-guide v2.8.0"
+```
+
+The file stays visible to your IDE LLM (the gitignore block hasn't changed), but it stops appearing in diffs and stops blocking `git switch`.
+
 ### 2. Tell your LLM to read the guide
 
 ```
@@ -365,6 +373,8 @@ project-guide heal [OPTIONS]
 
 **Auto-hook:** every `project-guide` invocation (including `--help` and `--version`) calls heal first via a group-level hook, so the fresh-clone case usually resolves itself silently the first time you run *any* command. The hook is silent in the steady state and prompts only when there's actual drift.
 
+**Tracked-`go.md` warning (v2.8.0+):** if `docs/project-guide/go.md` is in your git index, `heal` emits a stderr warning with a copyable migration command. The current policy is untracked-by-default — `go.md` stays visible to IDE LLMs (because it's unignored) but is kept out of the index so branch switches don't trip on it. The warning is non-fatal; the consumer applies the migration on their own schedule.
+
 **Examples:**
 ```bash
 # Interactive: prompts on drift

{project_guide-2.7.2 → project_guide-2.9.0}/README.md

@@ -86,11 +86,19 @@ project-guide init
 
 This creates:
 - `.project-guide.yml` - Configuration file (tracked)
-- `docs/project-guide/go.md` - Rendered LLM instructions (tracked — must be visible to IDE-integrated LLMs)
+- `docs/project-guide/go.md` - Rendered LLM instructions (**unignored but intentionally untracked** as of v2.8.0 — must be visible to IDE-integrated LLMs, but kept out of git so branch switches don't trip on it)
 - `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). 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.
 
+**Upgrading from v2.6.x – v2.7.x?** Earlier project-guide versions left `go.md` tracked by historical accident. v2.8.0 flips the policy to untracked-by-default to eliminate branch-switch and merge friction. If `heal` warns that `go.md` is tracked, run once on your default branch:
+
+```bash
+git rm --cached docs/project-guide/go.md && git commit -m "untrack go.md per project-guide v2.8.0"
+```
+
+The file stays visible to your IDE LLM (the gitignore block hasn't changed), but it stops appearing in diffs and stops blocking `git switch`.
+
 ### 2. Tell your LLM to read the guide
 
 ```
@@ -329,6 +337,8 @@ project-guide heal [OPTIONS]
 
 **Auto-hook:** every `project-guide` invocation (including `--help` and `--version`) calls heal first via a group-level hook, so the fresh-clone case usually resolves itself silently the first time you run *any* command. The hook is silent in the steady state and prompts only when there's actual drift.
 
+**Tracked-`go.md` warning (v2.8.0+):** if `docs/project-guide/go.md` is in your git index, `heal` emits a stderr warning with a copyable migration command. The current policy is untracked-by-default — `go.md` stays visible to IDE LLMs (because it's unignored) but is kept out of the index so branch switches don't trip on it. The warning is non-fatal; the consumer applies the migration on their own schedule.
+
 **Examples:**
 ```bash
 # Interactive: prompts on drift

{project_guide-2.7.2 → project_guide-2.9.0}/docs/specs/features.md

@@ -376,15 +376,16 @@ 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 produces a canonical block under a `# project-guide` header that ignores everything under `target_dir` *except* `go.md`. The block has gone through three shapes (P.d → P.j → P.l):
+**Inverted gitignore policy.** `init`'s gitignore writer produces a canonical block under a `# project-guide` header that ignores everything under `target_dir` *except* `go.md`. The block has gone through three shapes; the **tracking status** of `go.md` flipped in v2.8.0 (P.d → P.j → P.l → P.o):
 
 - **v2.6.0 (P.d):** 4-line negation form (`<target>/**` + `!<target>/go.md` + redundant `<target>/**/*.bak.*`).
 - **v2.6.1 (P.j):** 3-line negation form — dropped the redundant `.bak.*` line.
 - **v2.7.1 (P.l):** **negation-free explicit-list form** — lists every top-level entry under `target_dir` other than `go.md`, plus a `<target>/**/*.bak.*` catch-all for top-level backups. The list is generated dynamically from the bundled template tree, so new top-level files/subdirectories added in future releases are picked up automatically.
+- **v2.8.0 (P.o):** **untracked-by-default `go.md`**. The gitignore block is unchanged from v2.7.1 — `go.md` is still un-listed (and therefore unignored), preserving IDE-LLM visibility. What flips is the **tracking status**: `go.md` is no longer in the consumer's git index. `heal` warns (stderr) when it detects a tracked `go.md` with a copyable `git rm --cached docs/project-guide/go.md && git commit` migration command; `init` emits a stderr note that fresh installs leave `go.md` untracked. Branch switches and merges no longer trip on `go.md`.
 
-P.l abandoned the negation form because several IDE-integrated tools (Cursor, parts of the VS Code fork ecosystem, certain LSP-based search backends) implement a subset of `.gitignore` semantics that does not honor re-include negation — they apply the broad `**` rule, hide `go.md` from @-mention / fuzzy-search, and defeat the IDE-LLM-visibility constraint that's the whole reason `go.md` is tracked.
+P.l abandoned the negation form because several IDE-integrated tools (Cursor, parts of the VS Code fork ecosystem, certain LSP-based search backends) implement a subset of `.gitignore` semantics that does not honor re-include negation — they apply the broad `**` rule, hide `go.md` from @-mention / fuzzy-search, and defeat the IDE-LLM-visibility constraint that's the whole reason `go.md` stays unignored. The v2.8.0 tracking flip preserves that visibility — `go.md` remains unignored — while removing the version-control churn and branch-switch failure mode that motivated P.o.
 
-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. Existing v2.6.x/v2.7.0 installs heal to the v2.7.1 explicit-list form on the next `init --force` — every prior shape stays recognized by `_is_recognized_block_line()`. The track-only-`go.md` policy is unchanged across all three shapes; only the syntax that expresses it differs.
+Consumers migrating from a pre-Phase-P install run `project-guide init --force` to refresh the gitignore block. Consumers upgrading from v2.6.x/v2.7.x to v2.8.0 run `git rm --cached docs/project-guide/go.md && git commit` once on their default branch to migrate the tracking status; `heal` surfaces the warning until the migration is applied. Existing pre-v2.7.1 installs heal to the v2.7.1 explicit-list form on the next `init --force` — every prior shape stays recognized by `_is_recognized_block_line()`.
 
 ### FR-15: Story-Aware `git-push` Wrapper (gitbetter integration)
 

{project_guide-2.7.2 → project_guide-2.9.0}/docs/specs/project-essentials.md

@@ -32,9 +32,10 @@ Any future interactive prompt added to a CLI command **must** use the `should_sk
 
 ### Commit workflow
 
-- **Commit messages reference the story ID**; include **`vX.Y.Z`** when this commit is the **single** version bump for that story — examples:
-  - `"Story M.a: v2.3.0 project-essentials render hook"` (M.a owns v2.3.0)
-  - `"Story M.c: align specs with FR-9"` (doc-only; no version in title — rides M.b's or whichever code story owns the release line)
+- **Commit messages reference the story ID** in the bare form `<id>: <title>` (no `Story ` prefix — the prefix is implicit context and adds no information the `<id>:` anchor doesn't already convey). Include **`vX.Y.Z`** when this commit is the **single** version bump for that story — examples:
+  - `"M.a: v2.3.0 project-essentials render hook"` (M.a owns v2.3.0)
+  - `"M.c: align specs with FR-9"` (doc-only; no version in title — rides M.b's or whichever code story owns the release line)
+  - The `project-guide git-push` wrapper's commit-subject parser (`parse_committed_ids_from_subject` in `stories.py`; retired the single-regex `_COMMIT_SUBJECT_STORY_ID_RE` in Story P.u) accepts both bare and legacy `Story <id>:` forms for backward compatibility with historical hand-typed commits (Story P.s), but **bare is canonical** for new commits.
 - **Direct commits to main** in `code_direct` mode — no branches, no PRs.
 
 ### Config schema versioning
@@ -63,23 +64,31 @@ 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, tightened v2.6.1, IDE-compat reshape v2.7.1)
+### Inverted gitignore policy (added v2.6.0, tightened v2.6.1, IDE-compat reshape v2.7.1, untracked-by-default v2.8.0)
 
-`init`'s gitignore writer produces a canonical block that ignores everything under `target_dir` *except* `go.md`. The policy has gone through three shapes:
+`init`'s gitignore writer produces a canonical block that ignores everything under `target_dir` *except* `go.md`. The block has gone through three shapes; the **tracking status** of `go.md` flipped in v2.8.0:
 
 - **v2.6.0 (P.d):** 4-line negation form (`<target>/**` + `!<target>/go.md` + redundant `<target>/**/*.bak.*`).
 - **v2.6.1 (P.j):** 3-line negation form — dropped the redundant `.bak.*` line.
 - **v2.7.1 (P.l):** **negation-free explicit-list form** — lists every top-level entry under `target_dir` other than `go.md`, plus a `<target>/**/*.bak.*` defensive catch-all. The list is dynamically enumerated from the bundled template root at write time, so new top-level files/directories added in future stories are picked up automatically.
+- **v2.8.0 (P.o):** gitignore block unchanged from v2.7.1; **tracking status of `go.md` flips** from "tracked by historical accident" to **untracked-by-default**. `heal` emits a stderr warning with a copyable `git rm --cached docs/project-guide/go.md && git commit` command when it detects `go.md` in the consumer's git index. `init` emits a stderr note that the file is intentionally untracked.
 
 P.l abandoned negation because several IDE-integrated tools (Cursor, parts of the VS Code fork ecosystem, certain LSP-based search backends) implement a subset of `.gitignore` semantics that does **not** honor re-include negation — they apply the broad `**` rule, hide `go.md` from @-mention / fuzzy-search, and defeat the IDE-LLM-visibility constraint the policy is trying to enforce. **Future maintainers: do not "simplify" back to `**` + `!` — the regression is invisible from git's perspective but breaks the IDE workflow.**
 
 **Idempotent rewrite:** `_ensure_gitignore_entry()` uses `_is_recognized_block_line(line, target_dir)` as its "ours-vs-foreign" predicate. It accepts anything anchored at `/<target>/` (the v2.7.1+ form) plus every prior legacy form (v2.6.1 3-line, v2.6.0 4-line, pre-P.d `.bak.*`-only, legacy `<target>/go.md`). Any block whose lines all satisfy the predicate is rewritten cleanly to the current canonical 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)
+### IDE-LLM visibility constraint (added v2.6.0, untracked-by-default refinement v2.8.0)
 
-`go.md` **must remain non-gitignored** 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.
+`go.md` **must remain non-gitignored** 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.
 
-This is the constraint that forces the **inverted** gitignore policy rather than the simpler "ignore the entire `target_dir`" approach. Future refactors of the gitignore logic must preserve the `!<target>/go.md` exception.
+**Visibility vs. tracking — the key distinction (clarified v2.8.0):**
+
+- **Gitignore status** governs IDE-LLM visibility. The constraint is: `go.md` must remain **non-gitignored** so Cursor / Claude Code / VS Code-fork LLM tooling can read it. The v2.7.1 explicit-list gitignore block already leaves `go.md` un-listed (and therefore unignored).
+- **Tracking status** governs version-control churn and branch-switch safety. Pre-v2.8.0 `go.md` was tracked by historical accident, which made every mode switch appear in diffs and (more dangerously) caused `git switch` aborts when a feature branch had a different `go.md` than its base. v2.8.0 flips the tracking status to **untracked-but-unignored**: IDE LLMs still see the file (because it's not gitignored), but it stays out of the consumer's index so branch switches and merges no longer trip on it.
+
+The canonical state is therefore: `go.md` is **untracked-but-unignored**. Future refactors of the gitignore logic must preserve `go.md` as un-listed in the block (visibility), and project-guide itself must never `git add` it (tracking).
+
+**Warn-don't-auto-fix:** `heal` warns when `go.md` is tracked but does **not** auto-run `git rm --cached` — same wrapper-initiates-git-ops constraint that bounded the P.k `git-push` wrapper. The consumer applies the migration command on their own schedule.
 
 ### `heal` vs. `update` vs. `init` (added v2.6.0)
 
@@ -101,19 +110,35 @@ 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 developer-lane (added v2.7.0, bundled-commit support added v2.9.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.
+`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 `[Done]` story headings. 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`.
+**Heading-to-message rules (single story):**
+- 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`.
 - 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`.
+**Bundle-offer flow (P.u, v2.9.0):** when 2+ `[Done]` stories are uncommitted, the wrapper proposes a bundled commit subject and asks `[Y/n]`:
+- **Emit format:** per-story tokens joined with `", "`; each token is `<id>` or `<id>: <version>`; titles joined with `" + "` after the title boundary. Concrete shapes:
+  - All versionless → `H.a, H.b, H.c: title1 + title2 + title3`
+  - All versioned → `H.j: v0.10.0, H.k: v0.11.0 title1 + title2` (last token's `: <ver>` doubles as the title boundary)
+  - Mixed → `H.a, H.b: v1.2.3, H.c: title1 + title2 + title3`
+- **Colon rule:** a colon precedes a *version* or a *title*; it does not separate two bare IDs.
+- **Whitespace:** the assembled message is trimmed and any internal whitespace run collapsed to a single space.
+- **Title sanitization:** same backtick / double-quote rules as single-story.
+- **Decline (`n`)** → exit 1 with `"Multiple uncommitted [Done] stories: ..."` (today's manual-resolution hint).
+- **`--no-input`** → auto-decline (bundling changes the shape of the commit; that is a developer decision, not a CI default). The interactive default at the `[Y/n]` prompt is `Y`.
+
+**Bundled-commit recognition (P.u, v2.9.0):** the already-committed check parses each commit subject via `parse_committed_ids_from_subject` (in `stories.py`), which recognizes single-ID subjects (bare and `Story <id>:` legacy), legacy bundled subjects with no colons (`H.a, H.b, H.c InputSource ...`), and every canonical bundled form the wrapper itself emits. The parser is intentionally permissive on the read side and strict on the emit side. **Important:** the parser only inspects the ID-prefix shape — title text is never used to match. Story titles may contain `+` separators or any other prose without confusing the wrapper.
+
+**Duplicate-`<id>` warning (P.u, v2.9.0):** when the same bare `<id>` appears in 2+ commit subjects (regardless of version), the wrapper emits a stderr warning listing the offending subjects and asks `Continue? [Y/n]` (default `Y`). Under `--no-input`, auto-aborts with exit 1 so CI surfaces the history anomaly rather than papering over it.
+
+**Branch logic (post-P.u):**
+- 0 uncommitted `[Done]` stories → exit 1 `"Story <last id> is already committed."`
+- 1 uncommitted `[Done]` story → derive single-story message, invoke `git-push`.
+- 2+ uncommitted `[Done]` stories → propose bundled subject, prompt `[Y/n]`. Accept → invoke `git-push` with the bundled message. Decline (or `--no-input`) → exit 1 with the manual-resolution hint.
+- Duplicate `<id>` in git log → warning + prompt `Continue? [Y/n]` (defaults `Y` interactive, `n` under `--no-input`).
 
 **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.