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

{project_guide-2.7.2 → project_guide-2.8.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.8.0}/CHANGELOG.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-guide
-Version: 2.7.2
+Version: 2.8.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.8.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.8.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.8.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_STORY_ID_RE` 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)