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

{project_guide-2.7.0 → project_guide-2.7.2}/.gitignore

@@ -32,6 +32,8 @@ build/
 /site/
 
 # project-guide
-docs/project-guide/**
-!docs/project-guide/go.md
-docs/project-guide/**/*.bak.*
+/docs/project-guide/.metadata.yml
+/docs/project-guide/README.md
+/docs/project-guide/developer/
+/docs/project-guide/templates/
+/docs/project-guide/**/*.bak.*

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

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

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

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+
+### Fixed
+- **`project_guide/stories.py:_STORY_RE`** — extended the story-ID character class from `[A-Z]\.[a-z]+` to `[A-Z]\.[a-z]+(?:\.\d+)?` so headings of the form `### Story J.m.1: ...` parse correctly. Without this, `_read_done_stories()` silently filtered such headings out and the wrapper picked the wrong "last [Done] story."
+- **`project_guide/cli.py:_COMMIT_SUBJECT_STORY_ID_RE`** — extended in the same shape so the already-committed check recognizes commit subjects like `J.m.1: ...`. Without this fix the duplicate-detection path would have a second-layer hole even after the stories.md side was fixed.
+- **`project_guide/actions.py:_VERSION_RE`** — extended in the same shape so `detect_latest_version()` no longer under-reports the highest version when the latest story uses the sub-numbered form.
+
+### Documented
+- **`_phase-letters.md`** — added a "Sub-numbered stories" subsection covering both use cases: pre-implementation split (`J.m` was planned but split into `J.m.1`, `J.m.2` before any work; bare `J.m` heading dropped) and post-implementation follow-up (`J.m` shipped, then a bug or follow-on feature lands as `J.m.1` before proceeding to `J.n`). Flat single-level only — no cascading like `J.m.1.1`.
+
+### Tests
+- New `tests/test_stories.py` covering `_STORY_RE`, `_read_done_stories()`, and `derive_commit_message()` — `stories.py` had no direct unit tests prior to this story (the test-coverage gap that let the bug ship in P.k).
+- New `tests/test_cli.py` cases for both `git-push` scenarios (post-impl follow-up with bare `J.m` present; pre-impl split with no bare `J.m`) and the round-trip "sub-numbered story is already committed" path.
+- New `tests/test_actions.py` case asserting `detect_latest_version()` picks up the version on a sub-numbered heading.
+
+## [2.7.1] - 2026-05-11
+
+Compatibility fix for IDE-integrated LLM @-mention / fuzzy-search. The v2.6.0–v2.7.0 gitignore block used a clean `<target>/**` + `!<target>/go.md` negation pair — correct per the `.gitignore` spec, but **several IDE 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. Those tools applied the broad `**` rule, hid `go.md`, and defeated the IDE-LLM-visibility constraint that's the entire reason `go.md` is tracked. P.l switches to a negation-free explicit-list form so simplistic parsers handle it reliably.
+
+### Changed
+- **`project_guide/cli.py:_build_project_guide_block()`** — rewritten to enumerate the bundled template root (`_get_package_template_dir()`) and emit one anchored `/<target>/<child>[/]` line per top-level entry other than `go.md`, plus a trailing `/<target>/**/*.bak.*` defensive catch-all for top-level backups. The list is dynamic — new top-level files/directories in the bundled tree are picked up automatically by both the writer and the test helper that mirrors it. Default install now writes:
+  ```
+  # project-guide
+  /docs/project-guide/.metadata.yml
+  /docs/project-guide/README.md
+  /docs/project-guide/developer/
+  /docs/project-guide/templates/
+  /docs/project-guide/**/*.bak.*
+  ```
+- **`project_guide/cli.py`** — `_recognized_block_lines()` replaced with `_is_recognized_block_line(line, target_dir)` predicate. Accepts the v2.7.1+ form (any line anchored at `/<target>/`) plus every prior legacy line (`<target>/**`, `!<target>/go.md`, `<target>/**/*.bak.*`, `<target>/go.md`). Existing v2.6.x/v2.7.0 installs heal cleanly to the v2.7.1 form on `init --force`; no multi-step migration required.
+- **Tests** — `_EXPECTED_GITIGNORE_BLOCK` constant replaced with `_expected_gitignore_block()` helper that mirrors the writer's enumeration; new `test_init_force_rewrites_v261_three_line_block_to_explicit_list` for the v2.6.1/v2.7.0 → v2.7.1 migration path; the foreign-block test now seeds a line not anchored at `/<target>/` so the predicate correctly flags it as foreign.
+- **Docs** — updated the gitignore prose in `docs/specs/features.md`, `docs/specs/tech-spec.md`, and `docs/specs/project-essentials.md` to document the three-version evolution (v2.6.0 → v2.6.1 → v2.7.1) and the "do not simplify back to negation" warning for future maintainers.
+
+### Migration
+None required at the consumer level. The v2.6.x/v2.7.0 negation form and the v2.7.1 explicit-list form produce identical git-tracking outcomes (only `go.md` is tracked). The behavior change is purely in what `_ensure_gitignore_entry()` writes. Consumers whose IDE handles negation correctly may keep their existing block indefinitely; only consumers hitting the IDE bug actually benefit from running `project-guide init --force` to adopt the new form.
+
 ## [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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-guide
-Version: 2.7.0
+Version: 2.7.2
 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/

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

@@ -376,7 +376,15 @@ 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 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`.
+**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):
+
+- **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.
+
+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.
+
+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.
 
 ### FR-15: Story-Aware `git-push` Wrapper (gitbetter integration)
 

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

@@ -63,11 +63,17 @@ 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)
+### Inverted gitignore policy (added v2.6.0, tightened v2.6.1, IDE-compat reshape v2.7.1)
 
-`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.
+`init`'s gitignore writer produces a canonical block that ignores everything under `target_dir` *except* `go.md`. The policy has gone through three shapes:
 
-**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`.
+- **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.
+
+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)
 

{project_guide-2.7.0 → project_guide-2.7.2}/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 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.
+**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, P.k, and P.l 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), **P.l → v2.7.1** (patch — switch the gitignore block from negation to explicit-list form for IDE compatibility). 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]
 
@@ -262,6 +262,86 @@ This is a developer-lane convenience command. **The LLM still does not initiate
 - 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.
 
+### Story P.l: v2.7.1 Negation-free gitignore for IDE LLM compatibility [Done]
+
+Switch the canonical `# project-guide` gitignore block from the v2.6.1/v2.7.0 negation form (`<target>/**` + `!<target>/go.md`) to a **negation-free explicit-list** form. Motivation: 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 and fuzzy-search, and defeat the IDE-LLM-visibility constraint that's the entire reason `go.md` is tracked.
+
+The new canonical form lists every gitignored top-level entry explicitly so no negation is required. The list is **dynamically generated** from the bundled template root, so new top-level files or subdirectories added in future stories are picked up automatically — no manual maintenance.
+
+- [x] In `project_guide/cli.py:_build_project_guide_block()`: rewrite to enumerate `_get_package_template_dir()` and emit one `/<target>/<child>[/]` line per top-level entry except `go.md`, plus the existing `/<target>/**/*.bak.*` backup-catch-all. New canonical form for the default install layout:
+  ```
+  # project-guide
+  /docs/project-guide/.metadata.yml
+  /docs/project-guide/README.md
+  /docs/project-guide/developer/
+  /docs/project-guide/templates/
+  /docs/project-guide/**/*.bak.*
+  ```
+  Use a leading slash to anchor each rule at repo root; trailing slash on directories. Children sorted for deterministic output.
+- [x] In `project_guide/cli.py`: update the recognized-block check to accept every form we've ever written: *(replaced `_recognized_block_lines()` with a `_is_recognized_block_line(line, target_dir)` predicate — cleaner because the v2.7.1+ "anything anchored at `/<target>/`" rule isn't expressible as a fixed set)*
+  - [x] New v2.7.1+ form: any line starting with `/<target>/`
+  - [x] v2.6.1 form: `<target>/**`, `!<target>/go.md`
+  - [x] v2.6.0 form: `<target>/**`, `!<target>/go.md`, `<target>/**/*.bak.*`
+  - [x] pre-P.d form: `<target>/**/*.bak.*` only
+  - [x] Legacy `<target>/go.md` line
+- [x] In `tests/test_cli.py`:
+  - [x] Compute the expected block from the bundled tree via `_expected_gitignore_block()` helper instead of a hardcoded constant
+  - [x] Add `test_init_force_rewrites_v261_three_line_block_to_explicit_list` for the v2.6.1/v2.7.0 → v2.7.1 migration
+  - [x] Renamed the v2.6.0 → v2.7.1 migration test to `test_init_force_rewrites_v260_four_line_block_to_explicit_list` (was the v2.6.1-form rewrite test)
+  - [x] Foreign-block warning test updated to use a line not anchored at `/<target>/` so the new predicate flags it correctly
+  - [x] Idempotency test passes against the new canonical form (the seed builds from `_expected_gitignore_block()`)
+  - [x] All prior P.j/P.d migration tests continue to pass
+- [x] Doc updates (bundled in this story):
+  - [x] `docs/specs/features.md` FR-14: amended the "Inverted gitignore policy" paragraph with the three-version evolution (v2.6.0 → v2.6.1 → v2.7.1) and the IDE-compat rationale
+  - [x] `docs/specs/tech-spec.md` § `.gitignore Management`: replaced the negation code block with the explicit-list form, added a "Why explicit list instead of `**` + `!go.md`?" paragraph plus an explicit "do not simplify back" warning, and a "Why the trailing `<target>/**/*.bak.*` line?" paragraph
+  - [x] `docs/specs/project-essentials.md`: amended the "Inverted gitignore policy" sub-section to cover the v2.7.1 form change and the "future maintainers: do not simplify back to `**` + `!`" warning
+  - [x] `README.md`: no user-facing prose changes needed (Quick Start footnote still reads correctly — "ignored except go.md")
+- [x] Bump `project_guide/version.py`: `__version__ = "2.7.1"`
+- [x] Bump `pyproject.toml`: `version = "2.7.1"`
+- [x] Add `## [2.7.1] - <date>` CHANGELOG entry framed as a compatibility fix
+
+**Migration:** none required by consumers. The new and old blocks produce identical git-tracking outcomes (only `go.md` is tracked). The behavior change is purely in what `_ensure_gitignore_entry()` writes. Existing v2.6.x/v2.7.0 installs heal to the v2.7.1 form on `init --force` because all prior shapes remain recognized. Consumers whose IDE handles negation correctly can keep their existing block indefinitely — only consumers hitting the IDE bug actually need to migrate.
+
+**Why dynamic enumeration:** hardcoding the install footprint in `_build_project_guide_block()` means every new top-level template file or subdirectory requires a writer-code update. Enumerating `_get_package_template_dir()` at write time keeps the canonical block in sync with the bundled tree automatically. The trade-off is that the writer now reads from the package — not a real concern since `init` already does the same to copy the template tree.
+
+**Out of scope:**
+- An opt-back-in flag (`--gitignore-style=negation`). YAGNI until someone asks; the new form is strictly better for the documented IDE-LLM-visibility constraint.
+- A `project-guide check` integrity rule that detects "consumer has tracked-but-should-be-ignored files under `target_dir`". Defer until there's a second integrity rule worth shipping (see Future > Integrity & Validation).
+
+### Story P.m: v2.7.2 Recognize sub-numbered story IDs (`J.m.1`) in regex sites [Done]
+
+Reported bug: in a consumer project with the heading sequence `… J.l [Done], J.m.1 [Done]`, `project-guide git-push` printed `"Story J.l is already committed. Use 'git-push' directly for any follow-up commit."` and refused to push, even though `J.m.1` was the actual just-completed story.
+
+**Root cause:** three regexes encoded the story-ID shape as `[A-Z]\.[a-z]+`, which silently fails to match the sub-numbered form. `stories.py:_STORY_RE` was the proximate cause — `_read_done_stories()` filtered the `J.m.1` heading out entirely, leaving `J.l` as the "last `[Done]`," and the commit-subject check then correctly observed that `J.l` had been committed. The other two sites (`cli.py:_COMMIT_SUBJECT_STORY_ID_RE`, `actions.py:_VERSION_RE`) had the same hole and were fixed in the same story to avoid a half-fix where a future code path re-introduced the bug from a different angle.
+
+**Sub-numbered form** — `<phase>.<letter>.<digit>+`, flat single-level only (no cascading like `J.m.1.1`). Two use cases per the developer's intent:
+
+- **Pre-implementation split:** `J.m` is planned but its scope is judged too large before any work begins; the heading is split into `J.m.1`, `J.m.2` and the bare `J.m` heading is dropped. Sequence: `… J.l, J.m.1, J.m.2, J.n, …`.
+- **Post-implementation follow-up:** `J.m` ships, then a bug or follow-on feature must land before proceeding to `J.n`; the follow-up is added as `J.m.1` (and may cascade to `J.m.2`, `J.m.3`, …). Sequence: `… J.l, J.m, J.m.1, J.m.2, …, J.n, …`.
+
+Both scenarios are exercised by the new test suite.
+
+- [x] `project_guide/stories.py:_STORY_RE` — extend capture group to `[A-Z]\.[a-z]+(?:\.\d+)?` with comment cross-referencing `_phase-letters.md`
+- [x] `project_guide/cli.py:_COMMIT_SUBJECT_STORY_ID_RE` — matching extension; updated comment to reflect the new shape so future readers see why the two regexes must move together
+- [x] `project_guide/actions.py:_VERSION_RE` — matching extension; `detect_latest_version()` now picks up versions on sub-numbered headings
+- [x] `project_guide/templates/project-guide/templates/modes/_phase-letters.md` — new "Sub-numbered stories" subsection documenting both scenarios and the flat-only constraint
+- [x] Ran `project-guide update` to propagate the template change into `docs/project-guide/templates/modes/_phase-letters.md` (installed copy)
+- [x] New `tests/test_stories.py` — first direct unit-test coverage for `stories.py` (the gap that let the bug ship in P.k). Covers `_STORY_RE` matches (plain, sub-numbered, multi-digit sub-number), `_read_done_stories()` for both scenarios, `derive_commit_message()` with sub-numbered ID, and the round-trip through `cli._COMMIT_SUBJECT_STORY_ID_RE`
+- [x] `tests/test_cli.py` — new cases for both `git-push` scenarios (post-impl follow-up; pre-impl split with no bare `J.m`) and the "sub-numbered story is already committed" path that surfaces the second-layer regex hole
+- [x] `tests/test_actions.py` — new case asserting `detect_latest_version()` picks up the version on a sub-numbered heading
+- [x] Bump `project_guide/version.py`: `__version__ = "2.7.2"`
+- [x] Bump `pyproject.toml`: `version = "2.7.2"`
+- [x] Add `## [2.7.2] - 2026-05-19` entry to `CHANGELOG.md` framed as a bug fix with test-coverage backfill
+
+**Migration:** none. The change is purely permissive — existing plain-letter IDs (`J.l`, `J.m`) continue to match. Consumers who never used sub-numbered IDs see no behavior change; consumers who did will see `git-push` and `detect_latest_version()` start handling those headings correctly.
+
+**Why the docs change rides this story:** the sub-numbered form was already in use by consumers but undocumented in `_phase-letters.md`. Extending the regex without documenting the form would leave the next maintainer staring at an unexplained `(?:\.\d+)?` tail. Doc + code travel together.
+
+**Out of scope:**
+- Multi-level cascading (`J.m.1.1`). The developer's intent is flat; YAGNI until a consumer asks. Adding it later is a strict superset (`(?:\.\d+)+` instead of `(?:\.\d+)?`) and would be backwards compatible.
+- A `project-guide check` rule that warns when a sub-numbered ID appears without a preceding plain-letter heading in non-pre-split contexts. The two valid scenarios cover everything seen in the wild; defer until there's evidence of misuse.
+- Sub-numbered phase letters (`AA.1`). Phases don't carry the same pre-impl-split / post-impl-followup workflow that motivates the story-level sub-numbering, and no consumer has asked.
+
 ---
 
 ## Future

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

@@ -128,7 +128,7 @@ project-guide/
 | `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` (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.
+- `_ensure_gitignore_entry(target_dir)` — writes the canonical `# project-guide` block: ignore everything under `target_dir` except `go.md` (negation-free explicit-list form as of P.l / v2.7.1, dynamically enumerated from the bundled template root). Idempotent. Recognized prior blocks (pre-P.d `.bak.*`-only form, v2.6.0 4-line form, v2.6.1/v2.7.0 3-line negation form, legacy `<target>/go.md` line) are rewritten cleanly to the v2.7.1 explicit-list form; foreign hand-customized content under a `# project-guide` header is left alone with a stderr warning. The recognized-line check is `_is_recognized_block_line(line, target_dir)` — accepts anything anchored at `/<target>/` plus the legacy negation entries.
 - `_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.
@@ -270,18 +270,28 @@ class ModeDefinition:
 
 ### `.gitignore` Management
 
-`init` writes a canonical 3-line block under a `# project-guide` comment header (Story P.d, tightened in P.j / v2.6.1):
+`init` writes a canonical **negation-free explicit-list** block under a `# project-guide` comment header (Story P.d → P.j → P.l). For the default install layout the block is:
+
 ```
 # project-guide
-docs/project-guide/**
-!docs/project-guide/go.md
+/docs/project-guide/.metadata.yml
+/docs/project-guide/README.md
+/docs/project-guide/developer/
+/docs/project-guide/templates/
+/docs/project-guide/**/*.bak.*
 ```
 
+The list is **dynamically generated** at write time by enumerating the bundled template root (`_get_package_template_dir()`) and emitting one anchored line per top-level child other than `go.md`. New top-level files or subdirectories added in future releases are picked up automatically — no manual writer update required.
+
 **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.
 
-**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.
+**Why explicit list instead of `**` + `!go.md`?** The cleaner negation form (used in v2.6.0–v2.7.0) is correct per the `.gitignore` spec, but 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 search, and defeat the IDE-LLM-visibility constraint the policy is trying to enforce. P.l (v2.7.1) switched to the explicit-list form so no negation is required; tools with simplistic parsers handle anchored line-per-entry patterns reliably. Future maintainers: do **not** "simplify" back to `**` + `!` — the regression is invisible from git's perspective but breaks the IDE workflow that motivates tracking `go.md` in the first place.
+
+**Why the trailing `<target>/**/*.bak.*` line?** Defensive coverage for backup files that `apply_file_update()` writes next to top-level synced files (e.g., `<target>/README.md.bak.<timestamp>`). Subdirectory backups are already covered by the per-directory entries; this catch-all is a simple recursive glob with no negation, so the IDEs handle it cleanly.
+
+**Existing-block detection:** `_ensure_gitignore_entry()` is idempotent. The recognized-line predicate `_is_recognized_block_line(line, target_dir)` accepts any line starting with `/<target>/` (the v2.7.1+ anchor) plus the legacy negation-form lines (`<target>/**`, `!<target>/go.md`, `<target>/**/*.bak.*`, `<target>/go.md`). A block whose every non-empty line satisfies the predicate is rewritten cleanly to the current canonical form; any line that fails the predicate marks the block as hand-customized — the writer leaves it untouched and emits a stderr warning. A `.gitignore` with no `# project-guide` header gets the canonical block appended (separated by a blank line).
 
-**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.
+**Migration:** `project-guide init --force` rewrites prior blocks (pre-P.d `.bak.*`-only, v2.6.0 4-line, v2.6.1/v2.7.0 3-line) to the v2.7.1 explicit-list form in place. `git rm --cached` remains the manual cleanup for files already tracked under the old policy.
 
 ---
 

{project_guide-2.7.0 → project_guide-2.7.2}/project_guide/actions.py

@@ -127,9 +127,11 @@ class Artifact:
             action=action,
         )
 
-# Matches `### Story <Phase>.<sub>: vMAJOR.MINOR.PATCH ...`
+# Matches `### Story <Phase>.<sub>: vMAJOR.MINOR.PATCH ...` — the optional
+# `(?:\.\d+)?` tail covers sub-numbered IDs (`J.m.1`, `J.m.2`, …) per the
+# `_phase-letters.md` "Sub-numbered stories" rule.
 _VERSION_RE = re.compile(
-    r"^###\s+Story\s+[A-Za-z]+\.[a-z]+:\s+v(\d+)\.(\d+)\.(\d+)",
+    r"^###\s+Story\s+[A-Za-z]+\.[a-z]+(?:\.\d+)?:\s+v(\d+)\.(\d+)\.(\d+)",
     re.M,
 )
 

{project_guide-2.7.0 → project_guide-2.7.2}/project_guide/cli.py

@@ -312,39 +312,62 @@ _GITIGNORE_HEADER = "# project-guide"
 def _build_project_guide_block(target_dir: str) -> str:
     """Build the canonical project-guide gitignore block.
 
-    Policy (Story P.d, tightened in P.j): everything under ``target_dir`` is
-    gitignored except ``go.md`` (which the LLM reads, and IDE-integrated
-    LLMs typically hide gitignored files from the LLM's view). The remaining
-    template tree — including ``.bak.*`` backup files — is bundled static
-    data that ``heal`` repopulates on first invocation, so it does not need
-    to be tracked in the consumer repo. P.j dropped the explicit ``.bak.*``
-    line because the broad ``**`` rule already covers it; the old line is
-    still recognized as ours so v2.6.0 installs heal to this shape on
-    ``init --force``.
+    Policy (Story P.d, tightened in P.j, reshaped in P.l): everything under
+    ``target_dir`` is gitignored except ``go.md``. ``go.md`` must remain
+    tracked because IDE-integrated LLMs (Cursor, parts of the VS Code fork
+    ecosystem, several LSP-based search backends) typically hide gitignored
+    files from the LLM's @-mention / fuzzy-search view.
+
+    P.l (v2.7.1) abandons the cleaner ``<target>/**`` + ``!<target>/go.md``
+    shape because several of those same IDEs implement a subset of
+    ``.gitignore`` semantics that does not honor re-include negation —
+    they apply the broad ``**`` rule, hide ``go.md``, and defeat the
+    visibility constraint the policy is trying to enforce. The new form
+    lists every top-level entry under ``target_dir`` explicitly so no
+    negation is required. The list is enumerated from the bundled template
+    tree at write time, so future additions to the install footprint are
+    picked up automatically.
+
+    The trailing ``<target>/**/*.bak.*`` rule defensively ignores backup
+    files that ``apply_file_update`` writes next to top-level synced files
+    (subdirectory backups are already covered by the per-directory entries).
     """
-    return (
-        f"{_GITIGNORE_HEADER}\n"
-        f"{target_dir}/**\n"
-        f"!{target_dir}/go.md\n"
-    )
-
-
-def _recognized_block_lines(target_dir: str) -> set[str]:
-    """Lines that mark an existing block as one we wrote (safe to replace).
-
-    Any block whose every non-empty line is in this set can be safely
-    rewritten to the canonical form. A block containing anything outside
-    this set has been hand-customized; we warn and leave it alone.
+    pkg_root = _get_package_template_dir()
+    entries: list[str] = [_GITIGNORE_HEADER]
+    for child in sorted(pkg_root.iterdir(), key=lambda p: p.name):
+        if child.name == "go.md":
+            continue
+        suffix = "/" if child.is_dir() else ""
+        entries.append(f"/{target_dir}/{child.name}{suffix}")
+    entries.append(f"/{target_dir}/**/*.bak.*")
+    return "\n".join(entries) + "\n"
+
+
+def _is_recognized_block_line(line: str, target_dir: str) -> bool:
+    """Return True when ``line`` is one we plausibly wrote in any past version.
+
+    A block whose every non-empty line satisfies this predicate is treated
+    as ours and rewritten cleanly to the current canonical form; a block
+    containing anything that fails this predicate is left untouched with a
+    warning. Recognized forms (newest first):
+
+    - **v2.7.1+ explicit-list form (Story P.l):** any line starting with
+      ``/<target>/``. The leading slash anchors at repo root; we never
+      write unanchored lines, and there is nothing else we plausibly
+      generate under that anchor.
+    - **v2.6.1 form (Story P.j):** ``<target>/**`` and ``!<target>/go.md``.
+    - **v2.6.0 form (Story P.d):** the v2.6.1 lines plus ``<target>/**/*.bak.*``.
+    - **pre-P.d form:** ``<target>/**/*.bak.*`` only.
+    - **Legacy variants:** ``<target>/go.md`` (incorrectly gitignored, if
+      it ever appeared in the wild).
     """
-    return {
-        # Canonical lines as of P.j (v2.6.1).
+    if line.startswith(f"/{target_dir}/"):
+        return True
+    return line in {
         f"{target_dir}/**",
         f"!{target_dir}/go.md",
-        # v2.6.0 canonical form (Story P.d) — kept recognized so v2.6.0
-        # installs heal to the P.j 3-line form on `init --force`.
         f"{target_dir}/**/*.bak.*",
-        # Legacy / pre-P.d variants we know about.
-        f"{target_dir}/go.md",  # incorrectly gitignored go.md, if it ever appeared
+        f"{target_dir}/go.md",
     }
 
 
@@ -388,8 +411,7 @@ def _ensure_gitignore_entry(target_dir: str) -> None:
         block_end += 1
 
     block_body = [lines[i].strip() for i in range(header_idx + 1, block_end)]
-    recognized = _recognized_block_lines(target_dir)
-    foreign = [bl for bl in block_body if bl and bl not in recognized]
+    foreign = [bl for bl in block_body if bl and not _is_recognized_block_line(bl, target_dir)]
 
     if foreign:
         click.secho(
@@ -1604,8 +1626,9 @@ def heal(no_input: bool):
 
 # Regex matching the story-ID prefix of a commit-subject line — used to detect
 # which stories have already been committed (Story P.k). Mirrors the
-# `[A-Z]\.[a-z]+` shape of `_STORY_RE` in `stories.py`.
-_COMMIT_SUBJECT_STORY_ID_RE = __import__("re").compile(r"^([A-Z]\.[a-z]+):\s")
+# `[A-Z]\.[a-z]+(?:\.\d+)?` shape of `_STORY_RE` in `stories.py` (the optional
+# `.\d+` tail covers sub-numbered IDs like `J.m.1`).
+_COMMIT_SUBJECT_STORY_ID_RE = __import__("re").compile(r"^([A-Z]\.[a-z]+(?:\.\d+)?):\s")
 
 
 def _get_committed_story_ids() -> set[str]:

{project_guide-2.7.0 → project_guide-2.7.2}/project_guide/stories.py

@@ -17,8 +17,11 @@ from dataclasses import dataclass, field
 from pathlib import Path
 
 # Matches: ### Story N.a: v2.4.0 Some Title [Done]
+# The optional `(?:\.\d+)?` tail captures sub-numbered IDs (`J.m.1`, `J.m.2`, …)
+# used for pre-implementation splits or post-implementation follow-ups. See
+# `_phase-letters.md` (Sub-numbered stories).
 _STORY_RE = re.compile(
-    r"^### Story ([A-Z]\.[a-z]+): (.+) \[(Done|In Progress|Planned)\]\s*$",
+    r"^### Story ([A-Z]\.[a-z]+(?:\.\d+)?): (.+) \[(Done|In Progress|Planned)\]\s*$",
     re.MULTILINE,
 )
 

{project_guide-2.7.0 → project_guide-2.7.2}/project_guide/templates/project-guide/templates/modes/_phase-letters.md

@@ -14,6 +14,15 @@ Within a phase, stories use lowercase letters following the same scheme: `A.a`,
 
 Examples: `A.a`, `A.b`, …, `A.z`, `A.aa`, `A.ab`, ….
 
+### Sub-numbered stories
+
+A story may carry an optional numeric suffix — `J.m.1`, `J.m.2`, … — appended after the sub-letter. Sub-numbers are flat (no cascading like `J.m.1.1`) and start at `1`. Two situations use them:
+
+- **Pre-implementation split.** When `J.m` is planned but its scope is judged too large before any work begins, the heading is split into `J.m.1`, `J.m.2`, … and the bare `J.m` heading is dropped. Sequence becomes `…, J.l, J.m.1, J.m.2, J.n, …`.
+- **Post-implementation follow-up.** When `J.m` ships but a bug or follow-on feature must land before proceeding to `J.n`, the follow-up is added as `J.m.1` (and may cascade to `J.m.2`, `J.m.3`, …). Sequence becomes `…, J.l, J.m, J.m.1, J.m.2, …, J.n, …`.
+
+Sub-numbered stories follow normal Version Cadence: each one that ships code takes its own bump.
+
 ### Continuing across archive boundaries
 
 When `stories.md` is archived (via `archive_stories` mode), the fresh `stories.md` starts empty — but phase letters do **not** reset. To determine the next phase letter:

{project_guide-2.7.0 → project_guide-2.7.2}/project_guide/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "2.7.0"
+__version__ = "2.7.2"

{project_guide-2.7.0 → project_guide-2.7.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "project-guide"
-version = "2.7.0"
+version = "2.7.2"
 description = "Stay organized and in control with adaptive LLM workflow prompts."
 readme = "README.md"
 license = "Apache-2.0"

{project_guide-2.7.0 → project_guide-2.7.2}/tests/test_actions.py

@@ -150,6 +150,19 @@ def test_detect_latest_version_raises_when_none_found():
         detect_latest_version(text)
 
 
+def test_detect_latest_version_recognizes_subnumbered_story_id():
+    """Sub-numbered story IDs (J.m.1, used for pre-impl splits or post-impl
+    follow-ups) must contribute to the latest-version computation. The
+    plain-letter regex silently dropped them, causing `detect_latest_version`
+    to under-report the highest version when the latest story used the
+    `.NN` form."""
+    text = (
+        "### Story J.l: v0.68.0 prior story [Done]\n\n"
+        "### Story J.m.1: v0.70.0 follow-up after J.m [Done]\n"
+    )
+    assert detect_latest_version(text) == (0, 70, 0)
+
+
 # ---------------------------------------------------------------------------
 # detect_latest_phase_letter
 # ---------------------------------------------------------------------------