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

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

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-guide
-Version: 2.7.0
+Version: 2.7.1
 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.1}/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.1}/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.1}/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,52 @@ 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).
+
 ---
 
 ## Future

{project_guide-2.7.0 → project_guide-2.7.1}/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.1}/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(

{project_guide-2.7.0 → project_guide-2.7.1}/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.1"

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

@@ -1,6 +1,6 @@
 [project]
 name = "project-guide"
-version = "2.7.0"
+version = "2.7.1"
 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.1}/tests/test_cli.py

@@ -2404,24 +2404,41 @@ def test_hook_under_skip_input_heals_silently_with_notice(runner, tmp_path, hook
 # --- End Story P.c -----------------------------------------------------------
 
 
-# --- Story P.d / P.j: gitignore block inversion + tightening ----------------
+# --- Story P.d / P.j / P.l: gitignore block inversion + tightening + IDE compat ---
 
 
-_EXPECTED_GITIGNORE_BLOCK = (
-    "# project-guide\n"
-    "docs/project-guide/**\n"
-    "!docs/project-guide/go.md\n"
-)
+def _expected_gitignore_block() -> str:
+    """Compute the canonical gitignore block from the bundled template tree.
+
+    Mirrors `_build_project_guide_block()`'s enumeration so tests stay
+    honest when the bundled tree changes — adding a new top-level template
+    file/directory will be picked up by both the writer and this helper.
+    """
+    from project_guide.cli import _get_package_template_dir
+
+    pkg_root = _get_package_template_dir()
+    target = "docs/project-guide"
+    entries = ["# project-guide"]
+    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}/{child.name}{suffix}")
+    entries.append(f"/{target}/**/*.bak.*")
+    return "\n".join(entries) + "\n"
 
 
 def test_init_fresh_writes_inverted_gitignore_block(runner, tmp_path):
-    """Fresh `init` writes the canonical 3-line track-only-go.md block."""
+    """Fresh `init` writes the canonical explicit-list track-only-go.md block."""
     with runner.isolated_filesystem(temp_dir=tmp_path):
         result = runner.invoke(main, ['init'])
 
         assert result.exit_code == 0, result.output
         gitignore = Path(".gitignore").read_text()
-        assert _EXPECTED_GITIGNORE_BLOCK in gitignore
+        expected = _expected_gitignore_block()
+        assert expected in gitignore
+        # No negation pattern — the whole point of the P.l rewrite.
+        assert "!" not in gitignore.split("# project-guide", 1)[1].split("\n\n", 1)[0]
 
 
 def test_init_force_rewrites_legacy_bak_only_block_cleanly(runner, tmp_path):
@@ -2442,17 +2459,15 @@ def test_init_force_rewrites_legacy_bak_only_block_cleanly(runner, tmp_path):
         gitignore = Path(".gitignore").read_text()
         # Old block lines that are not in the canonical form must be gone.
         assert gitignore.count("# project-guide") == 1, gitignore
-        assert _EXPECTED_GITIGNORE_BLOCK in gitignore
-        # The dropped legacy line must not survive.
-        assert "docs/project-guide/**/*.bak.*" not in gitignore
+        assert _expected_gitignore_block() in gitignore
         # Surrounding content preserved.
         assert "*.pyc\n" in gitignore
 
 
-def test_init_force_rewrites_v260_four_line_block_to_three_lines(runner, tmp_path):
-    """`init --force` on a v2.6.0-shipped 4-line block tightens it to the v2.6.1 3-line form (Story P.j)."""
+def test_init_force_rewrites_v260_four_line_block_to_explicit_list(runner, tmp_path):
+    """`init --force` on a v2.6.0-shipped 4-line block migrates to the v2.7.1 explicit-list form."""
     with runner.isolated_filesystem(temp_dir=tmp_path):
-        # v2.6.0 canonical form — the line P.j drops is still recognized,
+        # v2.6.0 canonical form — all four lines are still recognized,
         # so the writer cleanly rewrites the block.
         Path(".gitignore").write_text(
             "*.pyc\n"
@@ -2468,16 +2483,36 @@ def test_init_force_rewrites_v260_four_line_block_to_three_lines(runner, tmp_pat
         assert result.exit_code == 0, result.output
         gitignore = Path(".gitignore").read_text()
         assert gitignore.count("# project-guide") == 1, gitignore
-        assert _EXPECTED_GITIGNORE_BLOCK in gitignore
-        # The redundant v2.6.0 line must be gone.
-        assert "docs/project-guide/**/*.bak.*" not in gitignore
+        assert _expected_gitignore_block() in gitignore
+        # The old negation form must be gone.
+        assert "!docs/project-guide/go.md" not in gitignore
         assert "*.pyc\n" in gitignore
 
 
+def test_init_force_rewrites_v261_three_line_block_to_explicit_list(runner, tmp_path):
+    """`init --force` on a v2.6.1/v2.7.0-shipped 3-line negation block migrates to v2.7.1 explicit-list."""
+    with runner.isolated_filesystem(temp_dir=tmp_path):
+        Path(".gitignore").write_text(
+            "*.pyc\n"
+            "\n"
+            "# project-guide\n"
+            "docs/project-guide/**\n"
+            "!docs/project-guide/go.md\n"
+        )
+
+        result = runner.invoke(main, ['init', '--force'])
+
+        assert result.exit_code == 0, result.output
+        gitignore = Path(".gitignore").read_text()
+        assert gitignore.count("# project-guide") == 1, gitignore
+        assert _expected_gitignore_block() in gitignore
+        assert "!docs/project-guide/go.md" not in gitignore
+
+
 def test_init_with_existing_canonical_block_is_idempotent(runner, tmp_path):
     """Running `init` over a project whose .gitignore is already canonical does not rewrite."""
     with runner.isolated_filesystem(temp_dir=tmp_path):
-        Path(".gitignore").write_text("foo\n\n" + _EXPECTED_GITIGNORE_BLOCK)
+        Path(".gitignore").write_text("foo\n\n" + _expected_gitignore_block())
         before = Path(".gitignore").read_text()
 
         result = runner.invoke(main, ['init'])
@@ -2493,7 +2528,7 @@ def test_init_warns_on_foreign_project_guide_block_and_leaves_it_untouched(runne
         foreign_block = (
             "# project-guide\n"
             "docs/project-guide/**/*.bak.*\n"
-            "docs/project-guide/local-only.md\n"  # foreign line
+            "some/unrelated/path\n"  # foreign line — not under /docs/project-guide/
         )
         Path(".gitignore").write_text(foreign_block)
 
@@ -2516,10 +2551,10 @@ def test_init_appends_block_when_no_prior_project_guide_section(runner, tmp_path
         gitignore = Path(".gitignore").read_text()
         assert "*.pyc\n" in gitignore
         assert ".venv/\n" in gitignore
-        assert _EXPECTED_GITIGNORE_BLOCK in gitignore
+        assert _expected_gitignore_block() in gitignore
 
 
-# --- End Story P.d / P.j ----------------------------------------------------
+# --- End Story P.d / P.j / P.l ----------------------------------------------
 
 
 # --- Story P.k: project-guide git-push wrapper ------------------------------