project-guide 2.2.3__tar.gz → 2.3.6__tar.gz

{project_guide-2.2.3 → project_guide-2.3.6}/.project-guide.yml

@@ -1,5 +1,5 @@
 version: '2.0'
-installed_version: 2.1.6
+installed_version: 2.3.5
 target_dir: docs/project-guide
 metadata_file: .metadata.yml
-current_mode: code_velocity
+current_mode: default

{project_guide-2.2.3 → project_guide-2.3.6}/.pyve/config

@@ -1,6 +1,6 @@
-pyve_version: "1.9.0"
+pyve_version: "1.13.0"
 backend: venv
 venv:
   directory: .venv
 python:
-  version: 3.14.3
+  version: 3.14.4

project_guide-2.3.6/.tool-versions

@@ -0,0 +1 @@
+python 3.14.4

{project_guide-2.2.3 → project_guide-2.3.6}/CHANGELOG.md

@@ -7,6 +7,191 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.6] - 2026-04-11
+
+### Changed
+- **Approval-gate rule added universally** (Story M.g) — closes a dogfooding-discovered bug in the Phase M implementation where the assistant repeatedly proposed "commit first or continue?" footers at the end of story-approval summaries despite the system prompt's explicit `NEVER commit changes unless the user explicitly asks`. Root cause: the `code_velocity` mode template's **Velocity Practices** section mixed LLM-lane instructions ("tests run after every story", "fix linting immediately") with developer-lane conventions ("direct commits to main", "commit messages reference story IDs") in a single unlabeled bullet list. A reasonable LLM reading the mixed list concluded it should offer to do the commit, since the convention was "direct commits with story-ID messages". The fix restructures the templates to separate the two lanes and adds a universal approval-gate rule to `_header-common.md` that inherits into every mode.
+- **`_header-common.md` **Rules** block** — added a new rule after "Never auto-advance past an approval gate":
+  > At approval gates, present the completed work and wait. Do **not** propose follow-up actions outside the current mode step — in particular, do not prompt for git operations (commits, pushes, PRs, branch creation), CI runs, or deploys unless the current step explicitly calls for them. The developer initiates these on their own schedule.
+  This is the universal fix. Because `_header-common.md` is included once by `llm_entry_point.md`, every rendered `go.md` now carries the rule — the 14 modes (`default`, `plan_*`, `refactor_*`, `archive_stories`, `project_scaffold`, `code_*`, `debug`, `document_*`) all inherit it without needing per-mode edits.
+- **`code-velocity-mode.md` "Velocity Practices" restructured into two explicitly-labeled lanes** — was a single unlabeled bullet list, is now `**LLM's role in each cycle:**` (version bump, minimal process overhead, tests after every story, fix linting immediately, update CHANGELOG before presenting) and `**Developer's role (do NOT prompt for, offer, or initiate):**` (direct commits to main, commit messages reference story IDs, decides when to commit). The "do NOT prompt for, offer, or initiate" language in the developer-lane header is load-bearing — it tells future template authors *why* the lane exists, which is the discipline that prevents this class of bug from recurring. The developer-lane header's "Decides when to commit" bullet explicitly notes that multiple stories may be bundled into one commit at the developer's discretion, which is not the LLM's call to make or suggest.
+- **`code-velocity-mode.md` step 9 ("Present") tightened** — was `**Present** the completed story to the developer for approval`, is now `**Present** the completed story concisely: what changed (files + line refs), verification results (test counts, lint status), and the suggested next story. Do not propose commits, pushes, or bundling options. Do not offer "want me to also…?" follow-ups.` This is belt-and-suspenders reinforcement of the universal rule — it catches LLMs that skim the header and jump to the cycle steps.
+- **`code-test-first-mode.md` step 8 ("Present") tightened** with the same language. `code_test_first` does NOT get the Velocity Practices lane restructure because it has no analogous section — the TDD cycle steps go straight from "Wait" to "Red-Green-Refactor" theory to "Test Writing Guidelines", with no mixed-lane bullet list to untangle. The universal `_header-common.md` rule is still sufficient for that mode.
+- **`docs/specs/project-essentials.md` for this project** dogfooded with a new `### Approval gate discipline` subsection that summarizes the rule and explains the root cause (the mixed lanes in `code_velocity`'s Velocity Practices). This is deliberately circular: the fix ships by itself as an instruction in `_header-common.md`, AND this project's project-essentials captures the same rule, which the M.a render hook then injects as a second reinforcement when any mode is rendered against this repo.
+
+### Tests
+- **Parametrized `test_header_common_approval_gate_rule_renders_in_every_mode`** — the critical test. Runs across every mode returned by `_get_all_mode_names()` (currently 14 modes). For each, runs `init + mode <name>` in a fresh `CliRunner.isolated_filesystem()` and asserts the rendered `go.md` contains the pinned substring `"do not prompt for git operations"` *inside* the **Rules** block (positional assertion, not just a presence check). This proves the rule reaches every mode, not just the ones explicitly touched by this story.
+- **`test_code_velocity_mode_separates_llm_lane_from_developer_lane`** — end-to-end render of `code_velocity`. Asserts both lane headers are present; the developer-lane header contains the "do NOT prompt for, offer, or initiate" load-bearing language; `"Direct commits to main"` appears *after* the developer-lane header (positional check, not just presence); and the LLM-lane header comes before the developer-lane header.
+- **`test_code_velocity_present_step_forbids_followup_prompts`** — asserts step 9's tightened language is present with two pinned substrings (`"Do not propose commits"` and `'want me to also'`).
+- **`test_code_test_first_present_step_forbids_followup_prompts`** — same assertion for `code_test_first`'s step 8. Ensures the Present-step tightening propagates to both code modes.
+- All four new tests pass; full suite **266 passed** (was 248; +18 = 14 parametrized + 3 code-mode + 1 from the count arithmetic). Ruff clean. No production code changed — this is a template-instruction fix only, so no mypy delta to report.
+
+### Notes
+- **Audit result**: manually grepped every bundled mode template for the "LLM/developer lane mixing" pattern. One orphan was discovered: **`production-mode.md`** (a transition checklist template that is NOT wired to any mode in `.metadata.yml` — dead code that never renders to any `go.md`). Its "Production Mode Transition Checklist" bullets mix LLM-lane and developer-lane items in an unlabeled list, but because the template is not included in any rendered guide, it cannot trigger the bug. Scope-gated to "defer" per the M.g story's out-of-scope clause — a separate follow-up story should either wire `production-mode.md` into `.metadata.yml` with the two-lane restructure or delete it as confirmed dead code. Flagged here for provenance.
+- **`document-brand-mode.md:385`** uses the good pattern already (`**Manual Updates (developer must do):**`). No fix needed; confirmed during the audit as the reference for how to label developer-lane sections.
+- **`document-landing-mode.md:56`** uses a `**Note:**` callout for a developer-side action. Also confirmed acceptable during the audit.
+- **Known limitation**: this fix addresses the *instruction*-level cause of the overreach. It does not prevent an LLM from ignoring the rule anyway — nothing short of a tool-side hook can do that. The rule is a strong nudge, not a hard gate. An LLM that has been conditioned elsewhere to offer commits can still override the rule; the fix substantially raises the cost of doing so (by putting the rule in front of the LLM on every read, in every mode) but does not make it impossible.
+- **Phase M is now complete for real this time** (`v2.3.0`–`v2.3.6`). Seven stories shipped: M.a through M.f as previously enumerated, plus M.g (this story) which closes a bug the first six stories introduced by implication. The lifecycle wiring, the render hook, the validator, and now the approval-gate discipline are all in place.
+
+## [2.3.5] - 2026-04-11
+
+### Added
+- **Phase M documentation pass** (Story M.f) — the `project-essentials.md` artifact that landed in v2.3.0 and the three planning-mode wirings that landed in v2.3.2 / v2.3.3 / v2.3.4 are now reflected across all user-facing documentation and cross-referenced from the other artifact templates:
+  - **`project_guide/templates/project-guide/templates/artifacts/concept.md`** — the existing "see also" sentence in the header gains a fourth cross-reference to `project-essentials.md` with a one-line description of what belongs there ("workflow rules, hidden coupling, tool-wrapper conventions that the LLM would otherwise random-walk on").
+  - **`project_guide/templates/project-guide/templates/artifacts/features.md`** — same cross-reference added to the "see also" sentence.
+  - **`project_guide/templates/project-guide/templates/artifacts/tech-spec.md`** — same cross-reference, with an additional one-line note that `plan_tech_spec` populates it after the tech-spec is approved (so the developer knows the capture flow is automatic, not manual).
+  - **`project_guide/templates/project-guide/templates/artifacts/stories.md`** — same cross-reference, with a one-line note that `plan_phase` appends to it per phase.
+  - **`project_guide/templates/project-guide/templates/modes/default-mode.md`** — the "Planning (sequence)" table's `plan_tech_spec` and `plan_phase` rows now mention the `project-essentials.md` side-effect. A new **"Refactoring (cycle)"** section was added to the "All Available Modes" table (previously missing entirely — Refactoring modes were listed in the README but not in the bundled default-mode template). The new `refactor_plan` row explicitly mentions the terminal-step project-essentials refresh.
+  - **`README.md` — `### Planning Modes` table** — same `plan_tech_spec` and `plan_phase` updates as above.
+  - **`README.md` — `### Refactoring Modes` table** — `refactor_plan` row rewritten from the vague "Plan a refactor" to the specific "Update `concept`/`features`/`tech-spec` for new capabilities or legacy migration; terminal step refreshes `project-essentials.md` (creates it for legacy projects)".
+  - **`docs/site/user-guide/modes.md`** — full reference entries rewritten for `plan_tech_spec`, `plan_phase`, and `refactor_plan`:
+    - `plan_tech_spec` now lists two **Artifacts** (was one) and explains the post-approval capture flow with the "skip if none" escape hatch called out.
+    - `plan_phase` now lists three **Artifacts** (was two) and explains the terminal append step with the append-only-semantics rationale (`refactor_plan`'s Final Step is where you refactor essentials, not here).
+    - `refactor_plan` now lists a **Artifact** field (was none) and explains the terminal "Revisit Project Essentials" step with all five refactor-specific framing categories visible in the prose. Legacy projects are explicitly flagged as the highest-value capture moment.
+
+### Notes
+- **Phase M is now complete** (`v2.3.0`–`v2.3.5`). Six stories shipped: M.a render hook + artifact template + dogfooding, M.b post-render placeholder validator, M.c `plan_tech_spec` create-wiring, M.d `refactor_plan` modify-wiring (terminal step), M.e `plan_phase` modify-wiring (append-only), and M.f (this documentation pass). The M.a render hook reads `<spec_artifacts_path>/project-essentials.md` at render time and injects its content under a `## Project Essentials` section in every rendered `go.md` via the `{% if project_essentials %}` guard in `_header-common.md`. The three planning modes populate, refresh, and append to the file at their respective lifecycle touchpoints. The M.b validator catches any future template edit that breaks the render pipeline (including removing the guard, typo-ing a context variable, or forgetting to update `render.py` when adding a new template variable).
+- **Documentation-only release.** No code or test changes. All 248 tests continue to pass unchanged (`pyve test`). Ruff clean across `project_guide/` and `tests/`. mypy clean on all unchanged production modules.
+- **Cross-reference scope**: only the four artifact templates that form the standard planning-doc chain (`concept.md`, `features.md`, `tech-spec.md`, `stories.md`) get the new cross-reference to `project-essentials.md`. `brand-descriptions.md` is a documentation artifact, not a planning doc, and was deliberately not touched — keeping that artifact's header focused on brand-specific cross-references.
+- **Implicit verification via the M.c / M.d / M.e end-to-end tests**: the story's "verify by running each of the three updated planning modes against a fresh fixture" checklist item is covered by the existing `test_plan_tech_spec_mode_prompts_for_project_essentials`, `test_refactor_plan_mode_prompts_for_project_essentials_revisit`, and `test_plan_phase_mode_prompts_for_project_essentials_append` tests in `tests/test_render.py`. Each runs `init` + `mode <name>` against a fresh `CliRunner.isolated_filesystem()` and asserts the prompt content. Re-running these three tests as part of the full suite (248 passed) is the verification — no separate fixture test added.
+- **What this phase leaves on the table for a future phase**: none. Phases K / L / M are all complete and ready for the next `archive_stories` run. When that happens, `stories.md` will be archived to `.archive/stories-v2.3.5.md` and a fresh empty `stories.md` will be re-rendered for the next phase.
+
+## [2.3.4] - 2026-04-11
+
+### Added
+- **`plan_phase` mode appends to `project-essentials.md`** (Story M.e) — wires the third and final planning mode to the M.a render hook, completing the M.c/M.d/M.e lifecycle coverage. Where M.c populates on initial tech-spec creation and M.d revisits on refactor, M.e runs once per new phase plan and **appends** (rather than revisits or rewrites) new must-know facts to the file. The append-only semantics are a deliberate design constraint — `plan_phase` runs frequently over a project's lifetime and should not be the place to refactor or reorder existing project-essentials content; that's `refactor_plan`'s Final Step job.
+- **New step 7 in `plan-phase-mode.md`** appended after Step 6 (stories approval), runs **once** at the end of phase planning (not per-story). Structure:
+  - **Create-if-absent branch**: if `docs/specs/project-essentials.md` doesn't exist (legacy project), the mode creates it from the artifact template first, following the same create path as `refactor_plan`'s Final Step. Legacy projects are explicitly flagged as the highest-value case.
+  - **Modify branch**: if the file exists, the mode reads it, keeps the current content in mind for the phase-specific prompt, and appends new `###` subsections under appropriate categories.
+  - **Phase-specific worked examples** with framing appropriate to "adding capability to an existing codebase": new architecture boundary (example cites Phase K's action-type registration pattern); new workflow rule or CLI contract (example cites Phase L's `--no-input` error-message contract that downstream tools pin); new hidden coupling between files (example cites Phase M's own `_header-common.md` guard + M.b validator); new deferred-but-documented item.
+  - **Principle anchor**: "if the phase introduced a new *invariant* or *convention* that someone working in this codebase a year from now would waste an hour rediscovering, it belongs in project-essentials." Straightforward feature additions with no new invariants should skip this step.
+  - **Skip-if-none escape hatch** is explicit — not every phase introduces new must-know facts.
+  - **Append-only semantics** are explicit: "append (do not rewrite or reorder)". Add new `###` subsections under the appropriate category (or create a new category if none fits). Do not edit existing content.
+  - **Heading convention reminder** (no top-level `#`; `###` for subsections) is present so the append nests correctly under the wrapper's `## Project Essentials`.
+- **`plan_phase` metadata entry** now declares three `artifacts` (was two): `new-phase-{{phase_name}}.md` (no action — document artifact), `stories.md` (`action: modify`), and the new `project-essentials.md` (`action: modify`). The new wiring does not disturb the existing two declarations — the M.e story's test explicitly guards against that regression.
+
+### Changed
+- **`{% raw %}...{% endraw %}` escape on the "hidden coupling" worked example** in `plan-phase-mode.md`. The example references `_header-common.md`'s `{% if project_essentials %}` guard literally inside a backtick code span — without the `{% raw %}` escape, Jinja2 parses the literal as an actual tag and the render fails with `Unexpected end of template`. This is the first time any bundled template has needed `{% raw %}` escaping, and it's a useful datapoint for the M.b validator's known-limitation note (templates that want to emit literal `{{ var }}` or `{% ... %}` strings need `{% raw %}`). Discovered during the first M.e test run; documented inline in the template.
+
+### Tests
+- **2 new tests in `tests/test_render.py`** under the "Story M.e" heading:
+  - `test_plan_phase_mode_prompts_for_project_essentials_append` — end-to-end render. Asserts: append step present and runs once; append-only semantics explicit ("do not rewrite or reorder"); create-if-absent branch present with legacy-project framing; at least two phase-specific worked example categories (architecture boundary, workflow rule / CLI contract); skip-if-none escape hatch; artifact template reference; heading convention reminder.
+  - `test_plan_phase_metadata_declares_project_essentials_modify_artifact` — loads bundled metadata, asserts exactly one `project-essentials.md` artifact with `ActionType.MODIFY`. Also sanity-checks that the existing `new-phase-*.md` and `stories.md` declarations are still present, guarding against a clobber regression.
+- **`test_every_mode_renders_successfully` parametrized test continues to pass unchanged** — and was specifically what caught the missing `{% raw %}` escape on the first run, since the `plan_phase` mode render failed until the escape was added.
+
+### Notes
+- **Phase M wiring is now complete** (M.c/M.d/M.e). All three planning modes populate, refresh, or append to `project-essentials.md` at their respective lifecycle touchpoints:
+  - `plan_tech_spec` → `action: create` (initial population after tech-spec approval)
+  - `refactor_plan` → `action: modify` (terminal revisit, create-if-legacy, refresh-if-exists)
+  - `plan_phase` → `action: modify` (append-only, create-if-legacy)
+  - All three use concrete worked examples with lifecycle-specific framing (initial / refactor-driven / phase-driven). All three have end-to-end render tests and metadata wiring tests. All three follow the heading convention that lets the content nest under `_header-common.md`'s `## Project Essentials` wrapper.
+- **What M.f (next and final Phase M story) adds**: a documentation pass — README / modes catalogue / CHANGELOG consolidation. No code changes; just closes out Phase M.
+- Full test suite: **248 passed** (+2 new M.e tests). Ruff clean across `project_guide/` and `tests/`. mypy clean on the unchanged production modules (no code changes in this story).
+- Verified end-to-end by running `pyve run project-guide update && pyve run project-guide mode plan_phase` in this repo. The rendered `go.md` contains the new step 7 at the expected position (after the stories-approval step 6) AND the M.a-injected `## Project Essentials` section at the top. The `{% if project_essentials %}` literal inside the worked example renders correctly (line 162 of the rendered output), confirming the `{% raw %}` escape works.
+
+## [2.3.3] - 2026-04-11
+
+### Added
+- **`refactor_plan` mode refreshes `project-essentials.md`** (Story M.d) — wires the second of the three planning modes to the M.a render hook. When a refactor updates concept/features/tech-spec, the mode now runs a terminal "Revisit Project Essentials" sequence to capture any new must-know facts the refactor introduced. Distinct from M.c's `plan_tech_spec` (initial-lifecycle path) and M.e's upcoming `plan_phase` (per-phase append) in two ways: (1) it runs **once** per refactor session, not per-document, and (2) it handles both the **create** case (legacy project being migrated to v2.x, no file exists yet) and the **modify** case (project already has the file).
+- **New "Final Step: Revisit Project Essentials" section** in `refactor-plan-mode.md`, appended after Step 8 (Cleanup). Structured as a 4-step sub-sequence to keep the decision path explicit:
+  - **Step F.1: Check for Existing File** — branches on whether `docs/specs/project-essentials.md` exists. The legacy-project branch is explicitly flagged as the highest-value case, because these projects typically have *never had their conventions written down* — their developers have internalized the rules and forgotten they're non-obvious.
+  - **Step F.2: Ask the Refactor-Revisit Prompt** — five concrete worked examples with *refactor-specific* framing (not M.c's initial-lifecycle framing): switched or added an environment manager (`pyve`/`uv`/`poetry`/`hatch`); split runtime from dev environment with the `pip install -e '.[dev]'` anti-pattern explicitly called out; renamed module or moved source-of-truth; changed domain conventions (money float → cents); new auto-generated or hidden-coupling files. Anchored by the **fork-in-the-road principle**: if the refactor introduced a decision where the *wrong* choice still "works" (runs, compiles, passes some tests), that is a project-essential. Each worked example includes a fully-rendered "*Example:*" sentence so the LLM can put concrete language in front of the developer, not abstract category names.
+  - **Step F.3: Generate or Update the File** — explicit create vs modify branching. Legacy projects get a fresh file from the artifact template; existing projects get an in-place update that preserves-updates-adds. Both paths re-iterate the heading convention (no top-level `#`; `###` for subsections).
+  - **Step F.4: Approval** — show the developer what was added, modified, and preserved, so the diff is legible.
+- **"Skip if there are none" escape hatch** is part of Step F.2, explicitly framed for the pure-doc-restructure case where no tool/architecture/convention change occurred. A pure reformat is a legitimate refactor and should not be forced to produce project-essentials content.
+- **`refactor_plan` metadata entry** now declares a single `artifacts` list (was previously empty) containing `project-essentials.md` with `action: modify`. The `modify` action type is the *conversational escape hatch* for the create-if-absent case: the deterministic action doesn't fire if the file doesn't exist, so the LLM's Step F.1 branching is what handles the create path in prose. The `action: modify` declaration is still correct at the metadata level because the *intent* is to end up with a modified (or newly-created) file.
+
+### Tests
+- **2 new tests in `tests/test_render.py`** under the "Story M.d" heading:
+  - `test_refactor_plan_mode_prompts_for_project_essentials_revisit` — end-to-end render test. Fresh `init` → `mode refactor_plan` → read `go.md`. Asserts the terminal section is present and runs once (not per-document); the create/modify branches are both visible; the legacy-project framing is explicit; at least one concrete worked example with environment-manager naming is present; the artifact template path is referenced; the heading convention reminder is emitted; the "skip if none" escape hatch is present; and the fork-in-the-road / "wrong choice still works" principle is visible (refactor-framing anchor).
+  - `test_refactor_plan_metadata_declares_project_essentials_modify_artifact` — loads the bundled metadata, gets the `refactor_plan` mode, and asserts exactly one `project-essentials.md` artifact with `ActionType.MODIFY`. The "exactly one" check is deliberate — a duplicate declaration from a copy-paste mistake would be silently accepted by the schema but would break the conversational handoff.
+- **`test_every_mode_renders_successfully` parametrized test continues to pass unchanged** — the new terminal section introduces no undefined-variable placeholders (validated by the M.b post-render validator) and the new metadata wiring does not break rendering for any of the 14 modes.
+
+### Notes
+- **Design choice — terminal step vs cycle step**: the M.d story offered two options ("add a cycle step OR extend Step 1"). I chose a terminal step (new "Final Step: Revisit Project Essentials" section appended after Step 8). Rationale: `refactor_plan`'s main cycle processes three documents (concept, features, tech-spec) one at a time — asking about project-essentials once per document would be annoying and redundant, because most of the meaningful facts a refactor introduces are cross-document (a new tool wrapper affects how you run everything, not just how you build one artifact). Running the prompt once at the end gives the developer the full refactor context and produces a cleaner essentials file.
+- **Terminology for metadata `action: modify`**: refactor_plan runs `action: modify` even though the file may not exist (legacy projects). This is the design pattern already established by `plan_phase`'s `stories.md` artifact in the bundled metadata — `modify` declares the intent ("end up with a modified file") and the mode template handles the create-if-absent case conversationally. The deterministic action handler in `actions.py` does NOT fire for `modify` actions — those go through the LLM. Only `archive` actions fire deterministically (via the `archive-stories` CLI command). So `modify` on a nonexistent file is not a runtime error; it's an instruction to the LLM.
+- Full test suite: **246 passed** (+2 new M.d tests). Ruff clean across `project_guide/` and `tests/`. mypy clean on `project_guide/render.py`.
+- Verified end-to-end by running `pyve run project-guide update && pyve run project-guide mode refactor_plan` in this repo. The rendered `go.md` contains all four sub-steps (F.1 through F.4) in the expected terminal position AND the M.a-injected `## Project Essentials` section at the top — proving the two layers compose correctly for this cycle-type mode as well.
+- **M.e (next story)** will take the same pattern into `plan_phase` with an *append-only* variant: rather than revisit or refresh, the prompt asks what *new* facts the phase introduces and appends them. Also uses `action: modify`. After M.e ships, all three planning modes (M.c/M.d/M.e) will populate `project-essentials.md` at their respective lifecycle touchpoints.
+
+## [2.3.2] - 2026-04-11
+
+### Added
+- **`plan_tech_spec` mode populates `project-essentials.md`** (Story M.c) — wires the first of the three planning modes to the M.a render hook. After the developer approves the tech-spec, the mode now asks whether any must-know facts should be captured for future LLMs working on the project, with concrete worked examples in the prompt (not just abstract category names). If the developer provides facts, the mode generates `docs/specs/project-essentials.md` from the artifact template; if not, the file is not created (an empty file is deliberately avoided on fresh projects — the "skip if none" escape hatch is explicit).
+- **New step 5 in `plan_tech_spec` mode template** at `project_guide/templates/project-guide/templates/modes/plan-tech-spec-mode.md`: "After tech-spec approval, capture project essentials." The prompt lists five categories (workflow rules, architecture quirks, domain conventions, hidden coupling, dogfooding/meta notes) and provides concrete worked examples for each — in particular, the *tool wrapper random walk* anti-pattern (Python invocation, dev tool installation, test invocation) that the story's implementation strategy explicitly calls out as the highest-value category to capture.
+- **New step 6 in the same mode**: generate `project-essentials.md` from the artifact template when the developer provides facts. The step explicitly reminds the LLM to follow the template's heading convention (no top-level `#`; `###` for subsections) so the content nests correctly under the `## Project Essentials` wrapper injected by `_header-common.md`.
+- **`plan_tech_spec` metadata entry** now declares two `artifacts` (was one): `tech-spec.md` + `project-essentials.md`, both with `action: create`. The `create` action type is correct here because `plan_tech_spec` is the initial-lifecycle population path; `refactor_plan` (M.d) and `plan_phase` (M.e) will use `modify`/`modify` since those run against existing projects where the file may already exist.
+
+### Tests
+- **2 new tests in `tests/test_render.py`** under the "Story M.c" heading:
+  - `test_plan_tech_spec_mode_prompts_for_project_essentials` — end-to-end render test. Fresh `init` → `mode plan_tech_spec` → read `go.md`. Asserts the capture step is present and ordered after tech-spec approval, at least one concrete worked example (`pyve run python` or `poetry run python`) is visible, two category names (`Workflow rules`, `Architecture quirks`) appear, the "skip if none" escape hatch is present, the artifact template path is referenced, and the heading convention reminder ("do NOT include a top-level", `###`) is emitted.
+  - `test_plan_tech_spec_metadata_declares_project_essentials_artifact` — loads the bundled `.metadata.yml`, gets the `plan_tech_spec` mode, and asserts both `tech-spec.md` and `project-essentials.md` are declared as artifacts with the `project-essentials.md` artifact using `ActionType.CREATE`. This is the wiring checkpoint that M.d/M.e will deliberately diverge from.
+- **`test_every_mode_renders_successfully` parametrized test continues to pass unchanged** — the new prompt content and the new metadata entry do not introduce any undefined-variable placeholders (validated by the M.b post-render validator) and do not break rendering for any of the 14 modes.
+
+### Notes
+- The `create` action type on the new artifact is an **intent declaration**, not an unconditional file-creation. The mode template's step 5 "skip to step 7 if there are no facts to capture" clause is the LLM-runtime escape hatch — a fresh project where the developer has nothing to put in `project-essentials.md` does NOT get an empty file. This is a deliberate design choice: empty files would trigger the render hook's "whitespace-only = omit section" branch (which is correct) but would leave a dormant empty file in `docs/specs/` that looks like an oversight. Better to not create it at all.
+- Full test suite: **244 passed** (+2 new M.c tests). Ruff clean across `project_guide/` and `tests/`. mypy clean on `project_guide/render.py`.
+- Verified end-to-end by running `pyve run project-guide update && pyve run project-guide mode plan_tech_spec` in this repo. The rendered `go.md` contains both the M.a-injected Project Essentials section at the top (fed by this project's own `docs/specs/project-essentials.md`) and the new M.c capture step at step 5 — proving the two layers compose correctly on a project that already has the file populated.
+- **What M.d and M.e add next**: M.d (`refactor_plan`) adds the same prompt with a "refactor-driven changes" framing and handles the legacy-project case where `project-essentials.md` does not yet exist; declares `action: modify` so the mode can either create-if-absent or modify-if-present. M.e (`plan_phase`) adds an append-only variant that runs once per new phase plan; also declares `action: modify`. M.c/M.d/M.e are mutually independent (per the phase plan in `docs/specs/stories.md`) but the listed order matches the project lifecycle.
+
+## [2.3.1] - 2026-04-11
+
+### Added
+- **Post-render placeholder validator** (Story M.b) — generalizes the M.a `{{ project_essentials }}` regression guard into a project-wide safeguard. After every `render_go_project_guide` call, the rendered output is scanned for any bare `{{ identifier }}` Jinja-style placeholder; if any are found, `RenderError` is raised with the offending names and a fix hint, and the output file is **not** written. This catches three distinct failure modes at the same place:
+  1. **Missed intents** — a context variable that should have been set in `render.py` but wasn't.
+  2. **Typos** — a template referencing `{{ project_essentialss }}` or any other misspelled variable name.
+  3. **Removed guards** — a future edit that drops a `{% if %}` wrapper and lets an unset variable leak through.
+- **`_UNRENDERED_PLACEHOLDER_RE` module-level regex** (`render.py`): `\{\{\s*([a-zA-Z_]\w*)\s*\}\}`. Matches exactly the shape that `_LenientUndefined.__str__` emits — `{{var}}`, `{{ var }}`, `{{  var  }}`. Deliberately does **not** match attribute access (`{{ obj.attr }}`), filters (`{{ name|upper }}`), expressions (`{{ a + 1 }}`), or statement blocks (`{% ... %}`). Those shapes raise at Jinja render time and never reach the validator.
+- **`_validate_no_unrendered_placeholders(rendered)` helper** (`render.py`): scans the rendered output, deduplicates offenders while preserving first-occurrence order, and raises `RenderError` with a message of the form `Unrendered placeholder(s) in rendered output: <names>. Hint: check (1) render.py context variables and (2) template variable spellings.`. The validator is called inside `render_go_project_guide` **after** `template.render()` and **before** `output_path.write_text()`, so a failing render leaves the filesystem untouched.
+
+### Changed
+- **`_LenientUndefined` contract documented inversion**: the class itself is unchanged (still emits `{{ name }}` for undefined variables), but its *purpose* has inverted. Before M.b, the placeholder shape was the final output — a permissive pass-through so unset variables wouldn't crash renders. After M.b, the placeholder shape is the *detection signal* — lenient undefined produces the shape that the post-render validator catches and promotes to an error. The class stays lenient so the validator can see and report every offender in one pass, rather than Jinja crashing on the first undefined variable it encounters.
+- **`test_render_undefined_vars_are_preserved` renamed to `test_render_undefined_vars_raise_render_error`** and inverted to assert the new behavior: undefined variables now raise `RenderError` with the offending name, and no output file is written.
+
+### Removed
+- **Temporary M.a regression guard `test_project_essentials_never_renders_literal_placeholder`** — the general validator subsumes it. If the `{% if %}` guard on `_header-common.md` is ever removed, the M.b validator raises `RenderError` on every mode render that has no populated `project-essentials.md`, which is far louder than a single dedicated test. A comment in the test file marks the removal for future readers.
+
+### Tests
+- **7 new tests in `tests/test_render.py`** under the "Story M.b" heading:
+  - `test_validator_raises_on_single_undefined_variable` — baseline: one typo'd variable → `RenderError` citing the name.
+  - `test_validator_error_message_lists_all_offenders` — three distinct offenders → error message names all three (no first-match short-circuit).
+  - `test_validator_deduplicates_repeated_offenders` — a name repeated 3× → appears exactly once in the message, in first-occurrence order.
+  - `test_validator_error_message_includes_fix_hint` — message contains both "render.py context variables" and "template variable spellings".
+  - `test_validator_does_not_write_output_on_failure` — the output file must not exist after a raise (pre/post `exists()` assertions).
+  - `test_validator_passes_when_all_vars_defined` — happy path: the standard `template_dir` fixture renders cleanly and the rendered file contains zero matching placeholders.
+  - `test_validator_passes_on_template_with_no_jinja_variables` — empty-match edge case: a minimal plain-text template renders without raising.
+- **Existing `test_every_mode_renders_successfully` parametrized test continues to pass unchanged.** This is the critical cross-template audit: every bundled mode is rendered through a fresh `CliRunner.isolated_filesystem()` install and must now pass the validator. All 14 modes pass, confirming that no bundled template references an undefined variable. This replaces the manual "audit existing templates" step in the M.b story checklist with an empirical proof.
+
+### Notes
+- **Audit result**: every bundled mode template's bare `{{ var }}` is backed by either a `render.py` context variable (`mode_name`, `mode_info`, `mode_description`, `sequence_or_cycle`, `next_mode`, `target_dir`, `project_essentials`) or a `metadata.common` entry (`test_invocation`, `spec_artifacts_path`, `web_root`). No mode template `{% include %}`s an artifact template, so artifact-template placeholders like `{{problem_statement}}` never enter the mode render path — they go through a separate `perform_archive` path in `actions.py` with its own `_LenientUndefined`, which is unchanged by this story.
+- **Known limitation** (documented inline in `_UNRENDERED_PLACEHOLDER_RE`'s docstring): templates that legitimately want to emit a literal `{{ var }}` string (e.g., documentation of Jinja syntax inside a code fence) will trigger false positives. Not currently a problem in any bundled template; bridge if/when needed, likely via a `{% raw %}` escape.
+- Full test suite: **242 passed** (+7 new M.b tests, −1 removed M.a guard, 1 renamed). Ruff clean across `project_guide/` and `tests/`. mypy clean on `project_guide/render.py`.
+- Verified end-to-end by re-rendering `docs/project-guide/go.md` under `default` and `plan_concept` modes per the story checklist. Both produce zero unrendered placeholders (confirmed via grep of the output).
+
+## [2.3.0] - 2026-04-11
+
+### Added
+- **`project-essentials.md` artifact and render hook** (Story M.a) — a new per-project artifact that captures must-know facts future LLMs need to avoid blunders (workflow rules, architecture quirks, domain conventions, hidden coupling, dogfooding notes). When present and non-empty, its content is injected verbatim under a `## Project Essentials` section in **every** rendered mode via `_header-common.md`, making the facts visible no matter which mode the developer is in. This story lays the rails; the `plan_tech_spec` / `refactor_plan` / `plan_phase` modes will be wired to populate it in stories M.c–M.e.
+- **`project_guide/templates/project-guide/templates/artifacts/project-essentials.md`** — the new artifact template. Ships as a comment-block-only file documenting what belongs there (workflow rules with concrete examples, architecture quirks, domain conventions, hidden coupling, dogfooding notes) and explicitly noting that an empty file is acceptable. The template deliberately omits a top-level `#` heading — the wrapper in `_header-common.md` provides the `## Project Essentials` heading, and content uses `###` for subsections to nest cleanly.
+- **`_read_project_essentials()` helper in `project_guide/render.py`** — reads `<spec_artifacts_path>/project-essentials.md` (resolved from `metadata.common["spec_artifacts_path"]`, typically `docs/specs`). Returns an empty string when the path is missing, the file does not exist, or the file is whitespace-only. `render_go_project_guide` now calls this helper and passes the result as the `project_essentials` Jinja2 context variable.
+- **`{% if project_essentials %}` guard in `_header-common.md`** — renders the `## Project Essentials` section (with the file's content and a `---` separator) only when the variable is non-empty. Empty/missing files omit the section entirely, so projects that don't want to maintain this file render cleanly.
+- **`docs/specs/project-essentials.md` for this project** (dogfooding) — populated with the current must-know facts: pyve two-environment workflow rules (`pyve run` / `pyve test` / `pyve testenv run`), the dogfooding rule (edit templates in `project_guide/templates/project-guide/`, never `docs/project-guide/`), v2 mode-driven architecture, the Phase K release-lifecycle pattern, the Phase L `--no-input` contract, and the commit/version style conventions.
+
+### Tests
+- **6 new tests in `tests/test_render.py`** under the "Story M.a" heading, all using a new `essentials_template_dir` fixture that faithfully reproduces the `{% if %}` guard shape and a new `essentials_metadata` fixture with `spec_artifacts_path`:
+  - `test_project_essentials_rendered_when_file_non_empty` — populated file → section appears between the header and the mode body.
+  - `test_project_essentials_omitted_when_file_empty` — zero-length file → section omitted.
+  - `test_project_essentials_omitted_when_file_whitespace_only` — whitespace-only file → section omitted (treated as empty).
+  - `test_project_essentials_omitted_when_file_missing` — no file at all → section omitted, no error.
+  - `test_project_essentials_omitted_when_spec_artifacts_path_not_in_metadata` — minimal metadata without `spec_artifacts_path` → lookup is skipped, section omitted.
+  - `test_project_essentials_never_renders_literal_placeholder` — **temporary regression guard** (scheduled for removal by M.b once the general post-render placeholder validator lands). Exercises all four file shapes and asserts the literal string `{{ project_essentials }}` never appears in the output. Catches a future template edit that removes the `{% if %}` guard, since `_LenientUndefined.__str__` would otherwise render the placeholder verbatim. See `render.py:83-99` for the lenient-undefined contract.
+
+### Notes
+- The M.a story deliberately does **not** add `project-essentials.md` to any mode's `.metadata.yml` `artifacts` list — that wiring is M.c–M.e's responsibility (population via `plan_tech_spec`, refresh via `refactor_plan`, append via `plan_phase`). M.a only establishes the render-time lookup, the guarded section, and the dogfooded content for this project.
+- The existing `test_every_mode_renders_successfully` parametrized test continues to pass unchanged. It runs every bundled mode through an isolated filesystem where no `docs/specs/project-essentials.md` exists, so the section is omitted and the render produces valid output — this is the implicit cross-mode regression guard.
+- Full test suite: **236 passed** (`pyve test`). Ruff clean across `project_guide/` and `tests/`. mypy clean on `project_guide/render.py`.
+- Verified end-to-end by re-rendering `docs/project-guide/go.md` under both `default` and `code_velocity` modes; the `## Project Essentials` section appears between the `**Rules**` block and the mode heading, with the `###` subsection nesting rendering correctly.
+
 ## [2.2.3] - 2026-04-11
 
 ### Fixed

{project_guide-2.2.3 → project_guide-2.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-guide
-Version: 2.2.3
+Version: 2.3.6
 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/
@@ -444,9 +444,9 @@ overrides:
 |------|---------|--------|
 | **Concept** | `project-guide mode plan_concept` | `docs/specs/concept.md` |
 | **Features** | `project-guide mode plan_features` | `docs/specs/features.md` |
-| **Tech Spec** | `project-guide mode plan_tech_spec` | `docs/specs/tech-spec.md` |
+| **Tech Spec** | `project-guide mode plan_tech_spec` | `docs/specs/tech-spec.md` + `docs/specs/project-essentials.md` (initial population) |
 | **Stories** | `project-guide mode plan_stories` | `docs/specs/stories.md` |
-| **Phase** | `project-guide mode plan_phase` | New phase added to stories |
+| **Phase** | `project-guide mode plan_phase` | New phase added to `stories.md` + append to `project-essentials.md` |
 
 ### Coding Modes
 
@@ -473,8 +473,8 @@ overrides:
 
 | Mode | Command | Workflow |
 |------|---------|----------|
-| **Plan** | `project-guide mode refactor_plan` | Plan a refactor |
-| **Document** | `project-guide mode refactor_document` | Document a refactor |
+| **Plan** | `project-guide mode refactor_plan` | Update `concept`/`features`/`tech-spec` for new capabilities or legacy migration; terminal step refreshes `project-essentials.md` (creates it for legacy projects) |
+| **Document** | `project-guide mode refactor_document` | Update README, brand descriptions, landing page, and MkDocs config |
 
 ## Troubleshooting
 

{project_guide-2.2.3 → project_guide-2.3.6}/README.md

@@ -408,9 +408,9 @@ overrides:
 |------|---------|--------|
 | **Concept** | `project-guide mode plan_concept` | `docs/specs/concept.md` |
 | **Features** | `project-guide mode plan_features` | `docs/specs/features.md` |
-| **Tech Spec** | `project-guide mode plan_tech_spec` | `docs/specs/tech-spec.md` |
+| **Tech Spec** | `project-guide mode plan_tech_spec` | `docs/specs/tech-spec.md` + `docs/specs/project-essentials.md` (initial population) |
 | **Stories** | `project-guide mode plan_stories` | `docs/specs/stories.md` |
-| **Phase** | `project-guide mode plan_phase` | New phase added to stories |
+| **Phase** | `project-guide mode plan_phase` | New phase added to `stories.md` + append to `project-essentials.md` |
 
 ### Coding Modes
 
@@ -437,8 +437,8 @@ overrides:
 
 | Mode | Command | Workflow |
 |------|---------|----------|
-| **Plan** | `project-guide mode refactor_plan` | Plan a refactor |
-| **Document** | `project-guide mode refactor_document` | Document a refactor |
+| **Plan** | `project-guide mode refactor_plan` | Update `concept`/`features`/`tech-spec` for new capabilities or legacy migration; terminal step refreshes `project-essentials.md` (creates it for legacy projects) |
+| **Document** | `project-guide mode refactor_document` | Update README, brand descriptions, landing page, and MkDocs config |
 
 ## Troubleshooting
 

{project_guide-2.2.3/project_guide/templates → project_guide-2.3.6/docs}/project-guide/.metadata.yml

@@ -53,6 +53,8 @@ modes:
     artifacts:
       - file: "{{spec_artifacts_path}}/tech-spec.md"
         action: create
+      - file: "{{spec_artifacts_path}}/project-essentials.md"
+        action: create
     files_exist:
       - "{{spec_artifacts_path}}/concept.md"
       - "{{spec_artifacts_path}}/features.md"
@@ -95,6 +97,8 @@ modes:
       - file: "{{spec_artifacts_path}}/new-phase-{{phase_name}}.md"
       - file: "{{spec_artifacts_path}}/stories.md"
         action: modify
+      - file: "{{spec_artifacts_path}}/project-essentials.md"
+        action: modify
     files_exist:
       - "{{spec_artifacts_path}}/concept.md"
       - "{{spec_artifacts_path}}/features.md"
@@ -180,6 +184,9 @@ modes:
     sequence_or_cycle: cycle
     generation_type: document
     mode_template: "{{mode_templates_path}}/refactor-plan-mode.md"
+    artifacts:
+      - file: "{{spec_artifacts_path}}/project-essentials.md"
+        action: modify
   - name: refactor_document
     info: Update documentation artifacts (README, brand descriptions, landing page, MkDocs)
     description: Update existing documentation files because of new features or improvements, including README, brand descriptions, landing page, and MkDocs configuration. You can also migrate legacy project-guide documentation--it will preserve information while restructuring into standardized sections.

project_guide-2.3.6/docs/project-guide/go.md

@@ -0,0 +1,199 @@
+# Project-Guide — Calm the chaos of LLM-assisted coding
+
+This document provides step-by-step instructions for an LLM to assist a human developer in a project. 
+
+## How to Use Project-Guide
+
+### For Developers
+After installing project-guide (`pip install project-guide`) and running `project-guide init`, instruct your LLM as follows in the chat interface: 
+
+```
+Read `docs/project-guide/go.md`
+```
+
+After reading, the LLM will respond:
+1. (optional) "I need more information..." followed by a list of questions or details needed. 
+  - LLM will continue asking until all needed information is clear.
+2. "The next step is ___."
+3. "Say 'go' when you're ready." 
+
+For efficiency, when you change modes, start a new LLM conversation. 
+
+### For LLMs
+
+**Modes**
+This Project-Guide offers a human-in-the-loop workflow for you to follow that can be dynamically reconfigured based on the project `mode`. Each `mode` defines a focused sequence of steps to guide you (the LLM) to help generate artifacts for some facet in the project lifecycle. This document is customized for default.
+
+**Approval Gate**
+When you have completed the steps, pause for the developer to review, correct, redirect, or ask questions about your work.  
+
+**Rules**
+- Work through each step methodically, presenting your work for approval before continuing a cycle. 
+- When the developer says "go" (or equivalent like "continue", "next", "proceed"), continue with the next action. 
+- If the next action is unclear, tell the developer you don't have a clear direction on what to do next, then suggest something. 
+- Never auto-advance past an approval gate—always wait for explicit confirmation. 
+- At approval gates, present the completed work and wait. Do **not** propose follow-up actions outside the current mode step — in particular, do not prompt for git operations (commits, pushes, PRs, branch creation), CI runs, or deploys unless the current step explicitly calls for them. The developer initiates these on their own schedule.
+- After compacting memory, re-read this guide to refresh your context.
+
+---
+
+## Project Essentials
+
+Must-know facts for future LLMs working on the project-guide project. These are things a smart newcomer could easily miss and waste time on. This content gets injected verbatim under a `## Project Essentials` section in every rendered mode, so entries below use `###` for subsections.
+
+### Workflow rules — pyve environment conventions
+
+This project uses `pyve` with **two separate environments**. Picking the wrong invocation form often "works" but leads to subtle drift. Use the canonical forms below:
+
+- **Runtime code (the `project_guide` package itself):** `pyve run python ...` or `pyve run project-guide ...`.
+- **Tests:** `pyve test [pytest args]` — **not** `pyve run pytest`. Pytest is not installed in the main `.venv/`; it lives in the dev testenv.
+- **Dev tools (ruff, mypy, pytest):** `pyve testenv run ruff check ...`, `pyve testenv run mypy ...`. These use `.pyve/testenv/venv/`.
+- **Install dev tools:** `pyve testenv --install -r requirements-dev.txt`. **Do not** run `pip install -e ".[dev]"` into the main venv — that pollutes the runtime environment with test-only dependencies and breaks the two-env isolation.
+
+If `pytest` fails with "not found" that is the signal to use `pyve test`, not to `pip install pytest` into the wrong venv.
+
+### Dogfooding rule — template source of truth
+
+This project uses itself (dogfooding). Template files live in **two places** that must not be confused:
+
+- **Source of truth:** `project_guide/templates/project-guide/` — the bundled templates that ship inside the Python package. **Edit these.**
+- **Installed copy:** `docs/project-guide/` — the rendered output from running `project-guide init` on this project. **Never hand-edit these.** They are regenerated by `project-guide mode` and `project-guide update`, and any hand-edits will be lost on the next sync.
+
+In particular, `docs/project-guide/go.md` is dynamically re-rendered by the `project-guide mode` command every time the mode changes. Never hand-edit `go.md`. After editing a source template, run `project-guide update` (while working in an editable install, e.g. `pyve run pip install -e .`) to propagate changes into the installed copy before re-rendering.
+
+### Architecture quirks
+
+- **v2 architecture is mode-driven Jinja2 templating,** not static file sync. The v1 "copy files to `docs/guides/`" pattern is deprecated; all new work targets `docs/project-guide/` via rendered templates.
+- **Phase K release lifecycle:** `archive_stories` mode + the `archive-stories` CLI command form a two-part pattern — the mode template walks the developer through the decision conversationally; the CLI performs the deterministic file move + re-render. Keep this split when adding similar lifecycle commands.
+- **Phase letters continue across archive boundaries.** When planning a new phase with `plan_phase` and `stories.md` is empty (post-archive), the `.archive/stories-vX.Y.Z.md` files must be read to determine the next letter. The rules are centralized in `project_guide/templates/project-guide/templates/modes/_phase-letters.md`.
+
+### `--no-input` contract (added v2.2.1)
+
+Any future interactive prompt added to a CLI command **must** use the `should_skip_input()` helper from `project_guide/runtime.py` to decide whether to read from stdin, and must use `_require_setting()` to fail loudly when a required setting has no default under `--no-input`. The contract and the exact error message format are pinned by `tests/test_cli.py::test_require_setting_contract_exit_code_and_message` — do not change that message lightly, as downstream tooling (e.g., pyve) may cite it.
+
+`init` currently has no prompts, but the plumbing (`skip_input = should_skip_input(no_input)` in `cli.py:init`) is already in place. The unused local is intentional — see the `# noqa: F841` comment.
+
+### Commit and version style
+
+- **One version bump per story** (code stories only — doc-only stories share the version with the preceding code story or bump to a `.N` doc release).
+- **Commit messages reference the story ID**: `"Story M.a: v2.3.0 project-essentials render hook"`.
+- **Direct commits to main** in `code_velocity` mode — no branches, no PRs.
+- **Bump version in three places** per story: `project_guide/version.py`, `pyproject.toml`, and `CHANGELOG.md` (new `## [X.Y.Z]` entry dated).
+
+### Approval gate discipline
+
+At approval gates, present the completed work and wait. **Do not prompt for, offer, or initiate git operations** (commits, pushes, PRs, branch creation), CI runs, or deploys unless the current step explicitly calls for them. This applies to every mode, not just `code_velocity`.
+
+**Why:** in the `code_velocity` cycle, the template lists "direct commits to main" and "commit messages reference story IDs" as conventions — those are *developer-lane* conventions describing what the developer does on their own schedule. They are not instructions for the LLM to offer or bundle commits. The `_header-common.md` **Rules** block makes this universal at read time. The `code_velocity` and `code_test_first` "Present" steps reinforce it with explicit "Do not propose commits, pushes, or bundling options. Do not offer 'want me to also...?' follow-ups" language.
+
+**How to apply:** when presenting a completed story, end with a concise status + suggested next story. Do not offer "commit first or continue?" options. Do not mention bundling commits. The developer decides; the LLM presents and waits.
+
+
+---
+
+# default mode (sequence)
+
+> Getting started -- full project lifecycle overview
+
+
+This is the default mode for new projects. It provides an overview of the full project lifecycle. For focused work, switch to a specific mode with `project-guide mode <name>`.
+
+---
+
+## Project Lifecycle
+
+| Step | Mode | What it does |
+|------|------|-------------|
+| 1 | `plan_concept` | Define the problem and solution space |
+| 2 | `plan_features` | Define requirements, inputs, outputs, behavior |
+| 3 | `plan_tech_spec` | Define architecture, modules, dependencies |
+| 4 | `plan_stories` | Break into phases and stories with checklists |
+| 5 | `project_scaffold` | Scaffold LICENSE, headers, manifest, README, CHANGELOG, .gitignore |
+| 6 | `code_velocity` | Implement stories with fast iteration |
+
+## Get Started
+
+To begin a new project, run:
+
+```bash
+project-guide mode plan_concept
+```
+
+## Suggesting the Next Step
+
+When this mode is set, read `docs/specs/stories.md` (if it exists) and check the status of every `### Story X.y: ... [<status>]` heading.
+
+### If all stories are `[Done]`
+
+The current phase is complete. There is no in-progress work to resume. Suggest **both** of the following next steps to the developer and explain the trade-off:
+
+> All stories in `stories.md` are marked `[Done]`. The current phase is finished. Two reasonable next steps:
+>
+> **Option A — `archive_stories` first, then `plan_phase`** (clean slate)
+> ```bash
+> project-guide mode archive_stories
+> ```
+> This moves the current `stories.md` to `docs/specs/.archive/stories-vX.Y.Z.md` and re-renders an empty `stories.md` (preserving the `## Future` section). Then `plan_phase` plans against an empty file. Phase letters continue across the archive boundary (`.archive/` is consulted to determine the next letter).
+>
+> *Use this when:* the completed phase is large enough that scrolling past it during planning is friction, or you want each phase as a self-contained file in `.archive/` for git history clarity.
+>
+> **Option B — `plan_phase` directly** (plan against history)
+> ```bash
+> project-guide mode plan_phase
+> ```
+> This appends the new phase to the existing `stories.md` alongside the completed phases.
+>
+> *Use this when:* the completed phases provide useful context that should remain visible during planning, or the project is still small enough that a single `stories.md` is comfortable to scroll.
+>
+> Which would you like?
+
+Wait for the developer to choose before changing modes.
+
+### If at least one story is non-`[Done]`
+
+The current phase still has in-progress, planned, or otherwise incomplete work. Use the existing project lifecycle suggestions above — direct the developer to the relevant coding mode (`code_velocity`, `code_test_first`) or, if planning artifacts are missing, to the appropriate planning mode.
+
+### If `stories.md` does not exist
+
+This is a fresh project. Direct the developer to `project-guide mode plan_concept` to begin the lifecycle.
+
+## All Available Modes
+
+### Planning (sequence)
+| Mode | Command | Output |
+|------|---------|--------|
+| **Concept** | `project-guide mode plan_concept` | `docs/specs/concept.md` |
+| **Features** | `project-guide mode plan_features` | `docs/specs/features.md` |
+| **Tech Spec** | `project-guide mode plan_tech_spec` | `docs/specs/tech-spec.md` + `docs/specs/project-essentials.md` (initial) |
+| **Stories** | `project-guide mode plan_stories` | `docs/specs/stories.md` |
+| **Phase** | `project-guide mode plan_phase` | Add a new phase to `stories.md` + append to `project-essentials.md` |
+
+### Scaffold (sequence)
+| Mode | Command | Purpose |
+|------|---------|---------|
+| **Project Scaffold** | `project-guide mode project_scaffold` | One-time project scaffolding |
+
+### Coding (cycle)
+| Mode | Command | Workflow |
+|------|---------|----------|
+| **Velocity** | `project-guide mode code_velocity` | Direct commits, fast iteration |
+| **Test-First** | `project-guide mode code_test_first` | TDD red-green-refactor cycle |
+| **Debug** | `project-guide mode debug` | Test-driven debugging |
+
+### Documentation (sequence)
+| Mode | Command | Output |
+|------|---------|--------|
+| **Branding** | `project-guide mode document_brand` | `docs/specs/brand-descriptions.md` |
+| **Landing Page** | `project-guide mode document_landing` | GitHub Pages + MkDocs docs |
+
+### Post-Release (sequence)
+| Mode | Command | Purpose |
+|------|---------|---------|
+| **Archive Stories** | `project-guide mode archive_stories` | Move completed `stories.md` to `.archive/` and re-render an empty one for the next phase |
+
+### Refactoring (cycle)
+| Mode | Command | Purpose |
+|------|---------|---------|
+| **Refactor Plan** | `project-guide mode refactor_plan` | Update `concept.md`/`features.md`/`tech-spec.md` for new features or legacy migration; terminal step refreshes `project-essentials.md` |
+| **Refactor Document** | `project-guide mode refactor_document` | Update README, brand descriptions, landing page, and MkDocs config |
+

{project_guide-2.2.3/project_guide/templates → project_guide-2.3.6/docs}/project-guide/templates/artifacts/concept.md

@@ -5,7 +5,7 @@ This document defines why the `{{project_name}}` project exists.
 - **Solution space**: solution statement, goals, scope, constraints
 - **Value mapping**: Pain point to solution mapping
 
-For requirements and behavior (what), see `features.md`. For implementation details (how), see `tech-spec.md`. For a breakdown of the implementation plan (step-by-step tasks), see `stories.md`.
+For requirements and behavior (what), see `features.md`. For implementation details (how), see `tech-spec.md`. For a breakdown of the implementation plan (step-by-step tasks), see `stories.md`. For project-specific must-know facts (workflow rules, hidden coupling, tool-wrapper conventions that the LLM would otherwise random-walk on), see `project-essentials.md`.
 
 ## Problem Space
  

{project_guide-2.2.3 → project_guide-2.3.6}/docs/project-guide/templates/artifacts/features.md

@@ -2,7 +2,7 @@
 
 This document defines **what** the `{{project_name}}` project does -- requirements, inputs, outputs, behavior -- without specifying **how** it is implemented. This is the source of truth for scope.
 
-For a high-level concept (why), see `concept.md`. For implementation details (how), see `tech-spec.md`. For a breakdown of the implementation plan (step-by-step tasks), see `stories.md`.
+For a high-level concept (why), see `concept.md`. For implementation details (how), see `tech-spec.md`. For a breakdown of the implementation plan (step-by-step tasks), see `stories.md`. For project-specific must-know facts that future LLMs need to avoid blunders, see `project-essentials.md`.
 
 ---
 

project_guide-2.3.6/docs/project-guide/templates/artifacts/project-essentials.md

@@ -0,0 +1,43 @@
+<!--
+This file captures must-know facts future LLMs need to avoid blunders when
+working on this project. Anything a smart newcomer could miss on day one and
+waste time on goes here.
+
+This content gets injected verbatim under a `## Project Essentials` section
+in every rendered `go.md`, so entries below should use `###` for subsections
+(not `##`, which would collide with the wrapper heading). Do NOT include a
+top-level `#` title — the wrapper provides it.
+
+What belongs here:
+
+- **Workflow rules — tool wrappers and environment conventions.** A common
+  source of "random walks" by LLMs: multiple invocation forms all *work*,
+  but only one is canonical. Capture which form to use so future LLMs don't
+  pick whatever happens to succeed first. Examples:
+    - Python invocation (`pyve run python ...` vs `python -m ...` vs
+      `.venv/bin/python ...`)
+    - Dev-tool installation (dedicated testenv vs `pip install -e ".[dev]"`
+      into the main venv — different isolation guarantees)
+    - Test invocation (`pyve test`, `poetry run pytest`, `make test` vs
+      bare `pytest`)
+
+- **Architecture quirks.** Source-of-truth vs generated/installed file
+  locations (edit the source, not the copy); build outputs that get
+  regenerated; files that look hand-edited but aren't.
+
+- **Domain conventions.** Money stored in cents, all timestamps UTC, IDs
+  are strings not ints, and similar non-obvious rules.
+
+- **Hidden coupling.** Files that mirror each other; auto-generated code;
+  regenerated outputs that look hand-edited.
+
+- **Dogfooding / meta notes.** If the project uses itself, capture the
+  rules that keep the dogfood loop safe.
+
+An empty file is acceptable — omit this file entirely, or leave the comment
+block above with no content below it. When empty, the rendered `go.md` for
+every mode will simply omit the "Project Essentials" section.
+
+The `plan_tech_spec`, `refactor_plan`, and `plan_phase` modes prompt for new
+entries at natural points in the project lifecycle.
+-->