get-tbd 0.1.30 → 0.2.1

package/dist/docs/guidelines/pnpm-monorepo-patterns.md

@@ -90,9 +90,10 @@ The architecture prioritizes fast iteration during early development while maint
 clear path to split packages later without breaking changes.
 
 The recommended stack uses **pnpm workspaces** for dependency management, **tsdown** for
-building ESM/CJS dual outputs with TypeScript declarations, **Changesets** for
-versioning and release automation, **publint** for validating package publishability,
-and **lefthook** for fast local git hooks.
+building ESM/CJS dual outputs with TypeScript declarations, **Changesets**
+(multi-package monorepos) or **tag-triggered OIDC publishing** (single-package repos)
+for versioning and release automation, **publint** for validating package
+publishability, and **lefthook** for fast local git hooks.
 This approach supports private development via GitHub Packages or direct GitHub
 installs, with a seamless transition to public npm publishing when ready.
 
@@ -671,7 +672,8 @@ package. Essential for any published package.
 
 #### Changesets
 
-**Status**: Strongly Recommended
+**Status**: Recommended for multi-package monorepos (for a single published package,
+prefer the tag-triggered approach below)
 
 **Details**:
 
@@ -729,8 +731,10 @@ Changesets provides:
 
    - Publishes to npm when that PR is merged
 
-**Assessment**: Changesets is the de facto standard for monorepo versioning.
-It integrates seamlessly with pnpm and GitHub Actions.
+**Assessment**: Changesets is the de facto standard for *multi-package* monorepo
+versioning and integrates seamlessly with pnpm and GitHub Actions.
+For a repo that publishes a single package, its per-PR ceremony rarely pays off — prefer
+the tag-triggered approach below (see the LLM-era note).
 
 **References**:
 
@@ -759,6 +763,19 @@ No NPM_TOKEN needed, no “Version Packages” PR workflow.
 3. Commit, tag (e.g., `v1.2.3`), and push
 4. GitHub Action publishes automatically on tag push
 
+> **When to prefer this over Changesets (LLM-era note):** For a **single published
+> package**, Changesets’ main wins (multi-package coordination and per-PR changelog
+> accumulation) mostly evaporate, while its ceremony (a `.changeset/*.md` per PR, a
+> bump-type decision per PR, the `changeset version` step, a “Version Packages” PR)
+> stays. When releases are cut by an agent/maintainer who assembles notes from clean
+> conventional commits at release time (see a release-notes template), tag-triggered
+> publishing is simpler and has fewer moving parts: clean commits → bump + `## X.Y.Z`
+> CHANGELOG section → tag → auto-publish.
+> `tbd` itself uses this approach (project-local `docs/publishing.md` for the per-repo
+> playbook; the workflow itself is the GitHub Action triggered by the `v*` tag).
+> Keep Changesets when you publish several interdependent packages or want contributors
+> to declare intent in each PR.
+
 **One-time setup**:
 
 1. Publish package manually once: `npm publish --access public`
@@ -3554,3 +3571,7 @@ ncu --dep dev --format group
 # Upgrade with peer dependency handling
 ncu --target minor -u && pnpm install --force
 ```
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/python-cli-patterns.md

@@ -83,3 +83,7 @@ Use `uv-dynamic-versioning` for git-based versions:
 4. Separate handlers from command definitions for testability
 5. Use TypedDict or dataclasses for type-safe options
 6. Test with Typer’s CliRunner for isolated, fast tests
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/python-modern-guidelines.md

@@ -182,3 +182,33 @@ class MyThing:
 str(MyThing(file_path="/tmp/file.txt", title="Something " + "blah " * 50, url="https://www.example.com", body="..."))
 # -> "MyThing(title='Something blah blah blah blah blah blah blah blah blah blah blah…', file_path=/tmp/file.txt, url=https://www.example.com)"
 ```
+
+## Releasing (tag-triggered, no changesets)
+
+For publishing Python packages to PyPI, follow the
+[`simple-modern-uv`](https://github.com/jlevy/simple-modern-uv) template’s model — it is
+the standard for tbd’s Python projects.
+The same clean principles as the TypeScript guidance apply: no changesets, releases cut
+from clean conventional commits.
+
+- **Dynamic versioning from the git tag** via
+  [`uv-dynamic-versioning`](https://github.com/ninoseki/uv-dynamic-versioning) — the tag
+  *is* the version (no manual `version =` bump in `pyproject.toml`, no version commit).
+- **Release/tag-triggered publish**: a `publish.yml` workflow runs on
+  `on: release: types: [published]` (or a `v*` tag), builds with `uv build`, and
+  publishes with `uv publish --trusted-publishing always` — **PyPI Trusted Publishing
+  (OIDC), no API token**.
+- **Supply-chain cool-off in CI**: set `UV_EXCLUDE_NEWER` to a 14-days-ago cutoff so the
+  build never resolves a brand-new (potentially yanked/compromised) release.
+- **Release notes** are written per `release-notes-guidelines` from the commits since
+  the last tag — there is no per-PR changeset file.
+- Expose the version at runtime with `importlib.metadata.version("<pkg>")`.
+
+So a release is just: clean commits → create the GitHub release/tag `vX.Y.Z` → CI builds
+and publishes.
+See `template/docs/publishing.md` in `simple-modern-uv` for the first-time
+Trusted Publisher setup.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/python-rules.md

@@ -258,3 +258,7 @@ These are general rules that *must* be followed on this project for Python code.
 - Exported/public variables, functions, or methods SHOULD have concise docstrings.
   Internal/local variables, functions, and methods DO NOT need docstrings unless their
   purpose is not obvious.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/release-notes-guidelines.md

@@ -138,3 +138,7 @@ Before finalizing release notes:
 
 **Full commit history**: https://github.com/org/repo/compare/v0.1.12...v0.1.13
 ```
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/supply-chain-hardening.md

@@ -52,7 +52,7 @@ planned upgrade.
 | pnpm 11+ | `minimumReleaseAge: 20160` in `pnpm-workspace.yaml` (pnpm 11 ignores `NPM_CONFIG_*`; env prefix is `PNPM_CONFIG_*`) |
 | uv | `UV_EXCLUDE_NEWER="14 days"` |
 | pip 26.1+ | `PIP_UPLOADED_PRIOR_TO="P14D"` |
-| Cargo / Go | no native gate: commit the lockfile, pass `--locked` (Cargo) / keep `go.sum` + `-mod=readonly` (Go), and require human review before re-resolving; gate automated bumps with Renovate/Dependabot release-age policy |
+| Cargo / Go | no native gate: commit the lockfile, pass `--locked` (Cargo) / keep `go.sum` and `-mod=readonly` (Go), and require human review before re-resolving; gate automated bumps with Renovate/Dependabot release-age policy |
 
 At upgrade-decision time, `npm-check-updates --cooldown 14` (pin the `ncu` version)
 gates which upgrades are even offered.
@@ -75,8 +75,8 @@ To check one version’s age: `npm view <pkg> time.<ver>`.
 5. **Don’t update for its own sake.** The safest update is the one you skip — each bump
    is fresh attack surface.
    Bump only for a concrete reason ("show me the commit we need"); prefer fewer,
-   vendored/pinned dependencies; let audits + CVE monitoring tell you when a real update
-   is warranted.
+   vendored/pinned dependencies; let audits and CVE monitoring tell you when a real
+   update is warranted.
 6. **No unpinned zero-install runners.** Avoid `npx` / `pnpm dlx` / `bunx` / `uvx` /
    `go run <remote>` without an explicit `@version` pin and a review of the resolved
    `package@version` — they fetch and execute the latest code, bypassing the cool-off.
@@ -208,10 +208,10 @@ Reviewed <date>.`
 
 ## What This Does and Doesn’t Cover
 
-A cool-off + disabled scripts neutralizes the dominant **fast-yanked-incident** pattern.
-It does **not** stop: long-lived typosquats that survive past the window; a lockfile
-that already captured a bad version; payloads that fire on import/build rather than
-install; or **publish-pipeline compromises** (the May 2026 @antv worm shipped from
+A cool-off plus disabled scripts neutralizes the dominant **fast-yanked-incident**
+pattern. It does **not** stop: long-lived typosquats that survive past the window; a
+lockfile that already captured a bad version; payloads that fire on import/build rather
+than install; or **publish-pipeline compromises** (the May 2026 @antv worm shipped from
 legitimate CI with a forged “verified” provenance badge — a green badge is not proof).
 Those need lockfile review, typosquat checks, build-time controls, and — if you publish
 packages — the publish-side controls in the guidebook’s `hardening-ci-cd.md` (OIDC
@@ -235,3 +235,7 @@ provenance monitoring).
   StepSecurity, Socket, Unit 42).
 - Monorepo enforcement: `tbd guidelines pnpm-monorepo-patterns`,
   `tbd guidelines bun-monorepo-patterns`.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/tbd-sync-troubleshooting.md

@@ -163,7 +163,8 @@ The `.tbd/.gitignore` file contains a `!workspaces/` negation pattern to prevent
 - Conflicting changes at field level
 
 **Solutions:**
-1. Check attic for conflict details: `ls .tbd/data-sync-worktree/.tbd/data-sync/attic/`
+1. Check attic for conflict details:
+   `ls "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree/.tbd/data-sync/attic/"`
 2. Review conflict files to understand what was lost
 3. Manually merge if needed
 4. Re-import with fresh workspace if appropriate
@@ -195,7 +196,7 @@ The `.tbd/.gitignore` file contains a `!workspaces/` negation pattern to prevent
 1. Run `tbd doctor --fix` to auto-repair
 2. If that fails, manually repair:
    ```bash
-   rm -rf .tbd/data-sync-worktree
+   rm -rf "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree"
    git worktree prune
    tbd doctor --fix
    ```
@@ -204,7 +205,8 @@ The `.tbd/.gitignore` file contains a `!workspaces/` negation pattern to prevent
 ### Worktree shows “detached HEAD”
 
 **Symptoms:**
-- `git -C .tbd/data-sync-worktree status` shows detached HEAD
+- `git -C "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree" status`
+  shows detached HEAD
 - Commits not going to tbd-sync branch
 
 **Solutions:**
@@ -224,7 +226,7 @@ tbd sync --status
 tbd workspace list
 
 # View worktree branch
-git -C .tbd/data-sync-worktree branch
+git -C "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree" branch
 
 # Compare local vs remote
 git log tbd-sync --oneline -5
@@ -258,3 +260,7 @@ tbd sync
 - `--no-outbox`: Skip automatic import from outbox on success
 
 See `tbd shortcut sync-failure-recovery` for the full workflow.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/typescript-cli-tool-rules.md

@@ -7,17 +7,17 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 
 **Last Updated**: 2026-05-21
 
-**Tracks**: Commander.js `^15.0.0` (ESM-only, requires Node v22.12.0+),
-picocolors `^1.1.1` (stable; no recent changes), Node.js 24 LTS / Node 26 Current.
+**Tracks**: Commander.js `^15.0.0` (ESM-only, requires Node v22.12.0+), picocolors
+`^1.1.1` (stable; no recent changes), Node.js 24 LTS / Node 26 Current.
 Commander 14 moves to security-only maintenance until May 2027.
 
 **Related**:
 
 - [TypeScript Rules](./typescript-rules.md)
 - [Supply-Chain Mitigation](./pnpm-monorepo-patterns.md#supply-chain-mitigation) —
-  follow the 14-day package-age rule for every CLI dependency. Bundlers and
-  CLI dependencies that execute at install time (`postinstall` scripts) are a
-  primary attack surface.
+  follow the 14-day package-age rule for every CLI dependency.
+  Bundlers and CLI dependencies that execute at install time (`postinstall` scripts) are
+  a primary attack surface.
 
 These rules apply to all CLI tools, command-line scripts, and terminal utilities.
 Examples may be inspired by modern TypeScript repos, but guidance here is intentionally
@@ -107,9 +107,9 @@ generic and reusable across projects.
 ## Commander.js Patterns
 
 - **Use Commander.js for all CLI tools:** Import from `commander` and follow established
-  patterns for command registration and option handling. **Target Commander 15+
-  (ESM-only, requires Node v22.12.0+).** Commander 14 is security-maintenance
-  only until May 2027; do not start new projects on it.
+  patterns for command registration and option handling.
+  **Target Commander 15+ (ESM-only, requires Node v22.12.0+).** Commander 14 is
+  security-maintenance only until May 2027; do not start new projects on it.
 
 - **Apply colored help globally, not per-command:** Use Commander v14+ `configureHelp()`
   with style functions, applied recursively to all commands at program initialization.
@@ -565,30 +565,29 @@ When supporting environment variables, especially those used by SDK libraries (l
 `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.), also support `.env` loading so CLIs work
 seamlessly in local dev and in remote environments.
 
-- **Prefer Node.js native `--env-file` for Node ≥20.6**: Production-ready on
-  Node 24 LTS. Pass `--env-file=.env.local --env-file=.env` on the CLI
-  invocation; later files do not override earlier ones, so list higher-priority
-  first. No dependency required:
+- **Prefer Node.js native `--env-file` for Node ≥20.6**: Production-ready on Node 24
+  LTS. Pass `--env-file=.env.local --env-file=.env` on the CLI invocation; later files
+  do not override earlier ones, so list higher-priority first.
+  No dependency required:
 
   ```bash
   node --env-file=.env.local --env-file=.env ./dist/bin.js
   ```
 
-  Make this the default for new projects. Reserve `dotenv` for advanced needs
-  (variable expansion, multiline values, custom precedence logic, or runtime
-  conditional loading from inside the CLI).
+  Make this the default for new projects.
+  Reserve `dotenv` for advanced needs (variable expansion, multiline values, custom
+  precedence logic, or runtime conditional loading from inside the CLI).
 
-- **Use `dotenv` only when needed:** Add `dotenv` only if your CLI must load
-  env files programmatically — e.g., it reads them after parsing command-line
-  flags, performs variable expansion, or supports custom file paths the user
-  cannot pre-bake into the `node` invocation.
+- **Use `dotenv` only when needed:** Add `dotenv` only if your CLI must load env files
+  programmatically — e.g., it reads them after parsing command-line flags, performs
+  variable expansion, or supports custom file paths the user cannot pre-bake into the
+  `node` invocation.
 
-- **Load `.env.local` and `.env` automatically (recommended):** Whichever
-  mechanism you use, support both `.env.local` (higher priority, gitignored)
-  and `.env` (lower priority, committed defaults only).
+- **Load `.env.local` and `.env` automatically (recommended):** Whichever mechanism you
+  use, support both `.env.local` (higher priority, gitignored) and `.env` (lower
+  priority, committed defaults only).
 
-- **Manual `dotenv` loading:** When you do need `dotenv`, load with explicit
-  precedence:
+- **Manual `dotenv` loading:** When you do need `dotenv`, load with explicit precedence:
 
   ```ts
   import dotenv from 'dotenv';
@@ -739,3 +738,7 @@ runtimes, Cloudflare Workers, etc.).
 
 - **Make scripts composable:** Design scripts to work well in pipelines and automation.
   Consider how they’ll be used in CI/CD and shell scripts.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/typescript-code-coverage.md

@@ -7,8 +7,8 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 
 **Last Updated**: 2026-05-21
 
-**Tracks**: Vitest `^4.1.7`, `@vitest/coverage-v8` `^4.1.7`. Vitest 5.0 is in
-beta — do not adopt yet.
+**Tracks**: Vitest `^4.1.7`, `@vitest/coverage-v8` `^4.1.7`. Vitest 5.0 is in beta — do
+not adopt yet.
 
 **Related**:
 
@@ -86,16 +86,16 @@ Low branch coverage often indicates untested error paths and edge cases.
 pnpm add -D vitest@^4.1 @vitest/coverage-v8@^4.1
 ```
 
-Follow the [14-day package-age rule](./pnpm-monorepo-patterns.md#supply-chain-mitigation)
-on every upgrade: use `ncu --cooldown 14` or
-`pnpm install --frozen-lockfile`.
+Follow the
+[14-day package-age rule](./pnpm-monorepo-patterns.md#supply-chain-mitigation) on every
+upgrade: use `ncu --cooldown 14` or `pnpm install --frozen-lockfile`.
 
 ### Vitest 4.x changes that affect coverage
 
 - **`coverage.all` was removed** in Vitest 4. Use `coverage.include` and
   `coverage.exclude` to define exactly which files are reported.
-- Coverage reporters and v8 provider now ship as part of `@vitest/coverage-v8`
-  aligned with the Vitest major version — pin them together.
+- Coverage reporters and v8 provider now ship as part of `@vitest/coverage-v8` aligned
+  with the Vitest major version — pin them together.
 
 ### Example Configuration
 
@@ -194,3 +194,7 @@ Vitest automatically fails when thresholds are not met if configured.
 - **Don’t test implementation details**: Focus on public APIs and behavior
 - **Don’t ignore branch coverage**: TypeScript’s type system creates many branches
 - **Don’t exclude too much**: Be selective about exclusions
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/typescript-rules.md

@@ -9,9 +9,9 @@ alwaysApply: true
 
 **Last Updated**: 2026-05-21
 
-**Tracks**: TypeScript `^6.0.3` (stable). TypeScript 7.0 Beta
-(`@typescript/native-preview`, binary `tsgo`) is available but **not yet
-production-ready** — do not adopt for shipped builds.
+**Tracks**: TypeScript `^6.0.3` (stable).
+TypeScript 7.0 Beta (`@typescript/native-preview`, binary `tsgo`) is available but **not
+yet production-ready** — do not adopt for shipped builds.
 
 **Related**:
 
@@ -21,9 +21,9 @@ production-ready** — do not adopt for shipped builds.
 - [TypeScript Code Coverage](./typescript-code-coverage.md)
 - [pnpm Monorepo Patterns](./pnpm-monorepo-patterns.md) and
   [Bun Monorepo Patterns](./bun-monorepo-patterns.md)
-- [Supply-Chain Mitigation](./pnpm-monorepo-patterns.md#supply-chain-mitigation) —
-  the 14-day package-age rule applies to every TypeScript dependency
-  (`zod`, `commander`, `vitest`, `eslint`, type packages, etc.).
+- [Supply-Chain Mitigation](./pnpm-monorepo-patterns.md#supply-chain-mitigation) — the
+  14-day package-age rule applies to every TypeScript dependency (`zod`, `commander`,
+  `vitest`, `eslint`, type packages, etc.).
 
 ## Coding Style
 
@@ -424,3 +424,7 @@ production-ready** — do not adopt for shipped builds.
   import { writeFile } from 'atomically';
   await writeFile(filePath, content);
   ```
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/typescript-sorting-patterns.md

@@ -232,3 +232,7 @@ items.sort(
     .result(),
 );
 ```
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/typescript-yaml-handling-rules.md

@@ -8,9 +8,9 @@ globs: "*.ts"
 
 **Last Updated**: 2026-05-21
 
-**Tracks**: `yaml@^2.8.4` (latest stable; 2026-05-02). The `yaml@3.0.0-1`
-release is tagged `next` (pre-release) — do not adopt yet. Zod 4.x is the
-recommended validation companion.
+**Tracks**: `yaml@^2.8.4` (latest stable; 2026-05-02). The `yaml@3.0.0-1` release is
+tagged `next` (pre-release) — do not adopt yet.
+Zod 4.x is the recommended validation companion.
 
 **Related**:
 
@@ -205,3 +205,7 @@ const output = `---\n${stringifyYaml(data)}---\n\n${content}`;
 
 - For general TypeScript rules, see `tbd guidelines typescript-rules`
 - For error handling patterns, see `tbd guidelines error-handling-rules`
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/agent-handoff.md

@@ -57,3 +57,7 @@ References: packages/llm-pricing/ - see scripts/generate-llms-data.ts and src/_g
 
 Setup: Run `pnpm install` after pulling (new dependencies added).
 ```
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/checkout-third-party-repo.md

@@ -48,3 +48,7 @@ need.
 - The `attic/` directory is gitignored—cloned repos won’t pollute your project
 - You can clone multiple repos into attic/ as needed
 - Delete cloned repos when done to save disk space
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/code-cleanup-all.md

@@ -88,3 +88,7 @@ cycle afterwords, fixing all build or test issues.
     - Batch database queries instead of individual fetches in loops
 
     - Consolidate nested sequential queries into single `Promise.all` call
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/code-cleanup-docstrings.md

@@ -75,3 +75,7 @@ export function formatContextMarkdown(
 4. Review existing docstrings and remove any that are redundant or obvious
 
 5. Run linting to ensure no syntax errors
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/code-cleanup-tests.md

@@ -56,3 +56,7 @@ Keep tests that:
 4. Remove trivial tests while preserving meaningful coverage
 
 5. Run the full test suite to ensure no regressions
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/code-review-and-commit.md

@@ -42,3 +42,7 @@ Create a to-do list with the following items then perform all of them:
      CI watch.
    - Only proceed when you see all checks have passed.
    - Confirm to the user that CI has passed.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/coding-spike.md

@@ -52,3 +52,7 @@ Create a to-do list with the following items then perform all of them:
    ```
 
 9. Report findings and recommend next steps.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/create-or-update-pr-simple.md

@@ -55,3 +55,7 @@ Create a to-do list with the following items then perform all of them:
    - Only proceed when you see all checks have passed in the final summary.
 
 8. Confirm to the user that CI has passed and the PR is ready for review.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/create-or-update-pr-with-validation-plan.md

@@ -74,3 +74,7 @@ Create a to-do list with the following items then perform all of them:
    - Only proceed when you see all checks have passed in the final summary.
 
 8. Confirm to the user that CI has passed and the PR is ready for review.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/implement-beads.md

@@ -28,3 +28,7 @@ Create a to-do list with the following items then perform all of them:
 4. Repeat this for all beads where you know how to fix them.
    If unsure about a bead, let the user know at the end of all work which beads had
    problems.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/merge-upstream.md

@@ -28,3 +28,7 @@ Merge upstream changes from origin/main into the current branch.
 6. **Verify**: Run formatting, linting, and tests
    - Fix any issues introduced by the merge
    - Commit the merge result
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/new-architecture-doc.md

@@ -29,3 +29,7 @@ Create a to-do list with the following items then perform all of them:
    If designing new architecture, iterate with the user on the design.
 
 5. Summarize the architecture and ask the user to review.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/new-guideline.md

@@ -122,3 +122,7 @@ description: Best practices for designing TypeScript APIs including naming, type
 | `{lang}-{topic}-rules` | `typescript-cli-tool-rules` | Specialized patterns |
 | `{domain}-rules` | `convex-rules` | Framework/platform rules |
 | `general-{topic}-rules` | `general-testing-rules` | Language-agnostic rules |
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/new-plan-spec.md

@@ -47,3 +47,7 @@ Create a to-do list with the following items then perform all of them:
 
 5. To list beads linked to a spec, use `tbd list --spec` (see `tbd list --help` for
    details on filtering and path matching).
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/new-qa-playbook.md

@@ -57,3 +57,7 @@ Create a to-do list with the following items then perform all of them:
    - Mark phases ✅/❌ in the status table after each run
    - Add test results with dates in the “Test Results” section
    - Archive or update playbooks when they become stale
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/new-research-brief.md

@@ -28,3 +28,7 @@ Create a to-do list with the following items then perform all of them:
    Ask the user for guidance when you need clarification or hit decision points.
 
 5. Summarize findings and ask the user to review.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/new-shortcut.md

@@ -77,3 +77,7 @@ For official shortcuts added to `packages/tbd/docs/shortcuts/standard/`:
 - **Guidelines**: Rules to reference (knowledge)
 
 See `tbd shortcut new-guideline` for creating guidelines.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/new-validation-plan.md

@@ -85,3 +85,7 @@ This serves as both a testing checklist and a summary for PR reviewers, showing:
    - Both
 
 6. **Summarize** what’s validated vs what remains for the user to review.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/plan-implementation-with-beads.md

@@ -54,3 +54,7 @@ If unclear, ask the user if they want you to create a spec first using
 - **Blocker** (`tbd dep add`): Sequential ordering.
   A bead cannot start until its blockers are complete.
   Use for tasks that genuinely depend on prior work.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/precommit-process.md

@@ -62,3 +62,7 @@ Create a to-do list with the following items then perform all of them:
    (See `tbd guidelines commit-conventions` for details.)
    If all checks pass, commit directly.
    Only ask the user if there are unresolved problems.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/review-code-python.md

@@ -32,3 +32,7 @@ Create a to-do list with the following items then perform all of them:
    - List Python-specific issues found (if any) with file:line references
    - Suggest specific fixes
    - Note any Python patterns that should be addressed
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/review-code-typescript.md

@@ -32,3 +32,7 @@ Create a to-do list with the following items then perform all of them:
    - List TypeScript-specific issues found (if any) with file:line references
    - Suggest specific fixes
    - Note any TypeScript patterns that should be addressed
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/review-code.md

@@ -107,3 +107,7 @@ Create a to-do list with the following items then perform all of them:
    - Otherwise, present the review and ask:
      - **Fix issues**: Create tbd beads for issues and begin fixing
      - **Report only**: Just output the review (no changes)
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/review-github-pr.md

@@ -139,3 +139,7 @@ Create a to-do list with the following items then perform all of them:
     - List any beads created (if fixing with beads)
     - Confirm CI status
     - Provide the PR URL
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/revise-all-architecture-docs.md

@@ -20,3 +20,7 @@ Run `tbd prime` for more on using tbd and current status.
 4. Work through each child bead, close when done
 
 5. Close epic with summary
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->