182 lines
15 KiB
Markdown
182 lines
15 KiB
Markdown
# Context
|
|
|
|
## Domain terms
|
|
|
|
### Dispatch Policy Module
|
|
Module owning dispatch error mapping, fallback policy, timeout classification, and CLI exit mapping contract.
|
|
|
|
Canonical error kind set:
|
|
- `unknown_command`
|
|
- `native_failure`
|
|
- `native_timeout`
|
|
- `fallback_failure`
|
|
- `validation_error`
|
|
- `internal_error`
|
|
|
|
### Command Definition Module
|
|
Canonical command metadata Interface powering alias, catalog, and semantics generation.
|
|
|
|
### Query Runtime Context Module
|
|
Module owning query-time context resolution for `projectDir` and `ws`, including precedence and validation policy used by query adapters.
|
|
|
|
### Native Dispatch Adapter Module
|
|
Adapter Module that satisfies native query dispatch at the Dispatch Policy seam, so policy modules consume a focused dispatch Interface instead of closure-wired call sites.
|
|
|
|
### Query CLI Output Module
|
|
Module owning projection from dispatch results/errors to CLI `{ exitCode, stdoutChunks, stderrLines }` output contract.
|
|
|
|
### Query Execution Policy Module
|
|
Module owning query transport routing policy projection (`preferNative`, fallback policy, workstream subprocess forcing) at execution seam.
|
|
|
|
### Query Subprocess Adapter Module
|
|
Adapter Module owning subprocess execution contract for query commands (JSON/raw invocation, `@file:` indirection parsing, timeout/exit error projection).
|
|
|
|
### Query Command Resolution Module
|
|
Canonical command normalization and resolution Interface (`query-command-resolution-strategy`) used by internal query/transport paths after dead-wrapper convergence.
|
|
|
|
### Command Topology Module
|
|
Module owning command resolution, policy projection (`mutation`, `output_mode`), unknown-command diagnosis, and handler Adapter binding at one seam for query dispatch.
|
|
|
|
### Query Pre-Project Config Policy Module
|
|
Module policy that defines query-time behavior when `.planning/config.json` is absent: use built-in defaults for parity-sensitive query Interfaces, and emit parity-aligned empty model ids for pre-project model resolution surfaces.
|
|
|
|
---
|
|
|
|
## Recurring PR mistakes (distilled from CodeRabbit reviews, 2026-05-05)
|
|
|
|
### Tests — no source-grep
|
|
- **Rule**: never bind `readFileSync` result to a var then call `.includes()` / `.match()` / `.startsWith()` on it. CI runs `scripts/lint-no-source-grep.cjs` and exits 1.
|
|
- **Escape**: add `// allow-test-rule: <reason>` anywhere in the file to exempt the whole file. Use when reading product markdown or runtime output (not `.cjs` source).
|
|
- **Pattern to reach for instead**: call the exported function, capture stdout/JSON, assert on typed fields.
|
|
|
|
### Tests — no unescaped RegExp interpolation
|
|
- `new RegExp(\`prefix${someVar}\`)` — if `someVar` can contain `.` or other metacharacters (e.g. phase id `5.1`), the pattern is wrong. Always `escapeRegex(someVar)`. The `escapeRegex` utility is in `core.cjs` and already imported in most modules.
|
|
|
|
### Tests — no dead regex branches in `.includes()`
|
|
- `src.includes('foo.*bar')` is always false — `.*` is a regex metacharacter, not a wildcard in `includes`. Either use `new RegExp('foo.*bar').test(src)` or delete the branch.
|
|
|
|
### Tests — guard top-level `readFileSync` against ENOENT
|
|
- Module-level `const src = fs.readFileSync(...)` throws before any `test()` registers, aborting the runner with an unhandled exception instead of a named failure. Wrap in try/catch and rethrow with a helpful message.
|
|
|
|
### Changesets — `pr:` field must be the PR number, not the issue number
|
|
- The `pr:` key in `.changeset/*.md` frontmatter must reference the PR introducing the fix (e.g. `3142`), not the issue it closes (e.g. `3120`). Changelog tooling links to GitHub PRs by this value.
|
|
|
|
### Shell hooks — never interpolate `$VAR` into single-quoted JS strings
|
|
- `node -e "require('$HOOK_DIR/lib/foo.js')"` breaks silently if `$HOOK_DIR` contains a single quote (POSIX-legal). Pass paths via env vars: `GIT_CMD_LIB="$HOOK_DIR/lib/foo.js" node -e "require(process.env.GIT_CMD_LIB)"`.
|
|
|
|
### Shell guards — `[ -f .git ]` does not detect worktrees from main repo
|
|
- In the main repo `.git` is a directory, so `[ -f .git ]` is false and the entire guard is skipped. Use `git rev-parse --git-dir` and match `*.git/worktrees/*` in a `case` statement instead.
|
|
|
|
### Shell guards — absolute-path containment must use `root/` prefix, not glob
|
|
- `[[ "$PATH" != "$ROOT"* ]]` matches sibling prefixes (`/repo-extra` passes when `ROOT=/repo`). Use `[[ "$P" != "$ROOT" && "$P" != "$ROOT/"* ]]`. Also: check `[ -z "$ROOT" ]` and exit 1 before the containment test. Warn → fail-closed for security-relevant path checks.
|
|
|
|
### Docs — keep internal reference counts consistent
|
|
- When a heading says `(N shipped)` and a footnote says `N-1 top-level references`, update the footnote. CodeRabbit catches this every time.
|
|
|
|
---
|
|
|
|
## Workflow learnings (distilled from triage + PR cycle, 2026-05-05)
|
|
|
|
### Skill consolidation gap class — missing workflow files
|
|
- When a command absorbs a micro-skill as a flag (e.g. `capture --backlog`), the old command's process steps must be ported to a `get-shit-done/workflows/<name>.md` file. The routing wrapper in `commands/gsd/*.md` declares an `execution_context` `@`-reference to that workflow — if the file doesn't exist the agent loads nothing and has no steps to follow.
|
|
- **Detection**: `tests/bug-3135-capture-backlog-workflow.test.cjs` adds a broad regression — every `execution_context` `@`-reference in any `commands/gsd/*.md` must resolve to an existing file on disk. This test will catch all future gaps of this class immediately.
|
|
- **Prior art**: `reapply-patches.md` was the first gap found and fixed in PR #2824 itself. `add-backlog.md` was missed in the same PR and caught later in #3135. Run the regression test after every consolidation PR.
|
|
|
|
### CodeRabbit thread resolution — stale threads after allow-test-rule fixes
|
|
- After adding `// allow-test-rule:` to silence lint, CodeRabbit's existing inline threads remain open even though the acknowledged fix is in place. Resolve them via `resolveReviewThread` GraphQL mutation before merging — open threads block clean merge history and mislead future reviewers.
|
|
- Pattern: `gh api graphql -f query='mutation { resolveReviewThread(input:{threadId:"PRRT_..."}) { thread { isResolved } } }'`
|
|
|
|
### PR discipline — split unrelated changes into separate PRs
|
|
- A bug fix and a docs rewrite committed to the same branch produce a noisy diff and a PR that reviewers can't cleanly approve. Cherry-pick doc changes to a dedicated branch (`docs/`) immediately, then force-push the original branch to remove the commit. One concern per PR.
|
|
|
|
### INVENTORY.md must be updated alongside every workflow file addition/removal
|
|
- `docs/INVENTORY.md` tracks the shipped workflow count (`## Workflows (N shipped)`) and has one row per file. Adding or removing a workflow without updating INVENTORY produces an internally inconsistent doc.
|
|
- Also update `docs/INVENTORY-MANIFEST.json` — it is the machine-readable manifest and must stay in sync with the filesystem.
|
|
- When a flag absorbs a micro-skill, the old skill's `Invoked by` attribution in INVENTORY must move to the new parent (e.g. `add-todo.md` incorrectly claimed `/gsd-capture --backlog` until #3135 corrected it).
|
|
|
|
### README — keep root README as storyline only; all detail lives in docs/
|
|
- Root `README.md` should be ≤300 lines: hero, author note, 6-step loop, install, core command table, why-it-works bullets, config key dials, docs index, minimal troubleshooting.
|
|
- Every removed detail section needs a link to the canonical doc that covers it. All doc links must resolve before committing.
|
|
- Markdownlint rules to watch: MD001 (heading level skip — don't use `###` directly inside admonitions; use bold instead), MD040 (fenced code blocks must declare a language identifier).
|
|
|
|
### Issue triage — always check for existing work before filing as new
|
|
- Before writing an agent brief for a confirmed bug, check: (1) local branches (`git branch -a | grep <issue>`), (2) untracked/modified files on that branch, (3) stash, (4) open PRs with matching head branch. A crash may have left work 90% done — recover and commit rather than re-implementing.
|
|
|
|
### SDK-only verbs — golden-policy exemption required
|
|
- Any `gsd-sdk query` verb implemented only in the SDK native registry (no `gsd-tools.cjs` mirror) must be added to `NO_CJS_SUBPROCESS_REASON` in `sdk/src/golden/golden-policy.ts`. Without this entry the golden-policy test fails, treating the verb as a missing implementation rather than an intentional SDK-only path.
|
|
|
|
---
|
|
|
|
## Recurring findings from ADR-0002 PR review (2026-05-05)
|
|
|
|
### allowed-tools must include every tool the workflow uses
|
|
When a command delegates to a workflow via `execution_context`, the command's `allowed-tools` must cover every tool the workflow calls — including `Write` for file creation. The thin wrapper pattern makes this easy to miss: the process steps live in the workflow, but the tool grant lives in the command frontmatter. Missing a tool silently fails at runtime.
|
|
|
|
### User-supplied slug/path args always need sanitization before file path construction
|
|
Any workflow step that takes user input (subcommand argument, `$ARGUMENTS`, or parsed remainder) and constructs a `.planning/…/{SLUG}.md` path must sanitize first: strip non-`[a-z0-9-]` chars, reject `..`/`/`/`\`, enforce max length. Document the sanitization inline at the step, not just in `<security_notes>`. Steps that say "(already sanitized)" must trace back to an explicit sanitization guard — not just a preceding describe block.
|
|
|
|
### RESUME/fallback modes bypass sanitization guards written for primary modes
|
|
CLOSE and STATUS modes that document "(already sanitized)" do not automatically cover RESUME or default modes. Each mode that constructs a file path from user input needs its own guard — don't assume sibling modes share state.
|
|
|
|
### Shared helpers prevent lint/test disagreement
|
|
When a lint script and a test suite both implement the same constant (`CANONICAL_TOOLS`) or parser (`parseFrontmatter`, `executionContextRefs`), they will silently diverge. Extract to a `scripts/*-helpers.cjs` module required by both. A tool added to the lint's allowlist but not the test's (or vice versa) causes one layer to pass while the other fails.
|
|
|
|
### readFileSync outside test() crashes the runner before any test registers
|
|
Module-level or suite-registration-time `readFileSync` throws as an unhandled exception if the file is absent, aborting the runner with no test output. Move reads inside `test()` callbacks so failures surface as named test failures.
|
|
|
|
### Global regex with `g` flag carries `lastIndex` state between calls
|
|
A `const RE = /pattern/g` shared across functions retains `lastIndex` after `.test()` or `.exec()`. Use a non-global pattern for boolean checks (`/pattern/.test(s)`) and create a new `RegExp(pattern, 'g')` per iteration when you need `exec()` loops. Forgetting `lastIndex = 0` resets causes intermittent false negatives.
|
|
|
|
### ADR files need Status + Date headers
|
|
Every `docs/adr/NNNN-*.md` file must open with `- **Status:** Accepted` (or Proposed/Deprecated) and `- **Date:** YYYY-MM-DD` immediately after the title. Without them the ADR is undatable and untriageable when the list grows.
|
|
|
|
### Step names in workflow XML must use hyphens, not underscores
|
|
All workflow file names use hyphens; `<step name="...">` attributes inside those files must match: `extract-learnings` not `extract_learnings`. Tests asserting `content.includes('<step name=')` should tighten to the exact hyphenated name so renames are caught.
|
|
|
|
### INVENTORY-MANIFEST.json has two workflow lists — only families.workflows is canonical
|
|
`docs/INVENTORY-MANIFEST.json` has `families.workflows` (canonical, read by tooling) and a stale top-level `workflows` key (introduced by a node update script that wrote to the wrong key). Always update `families.workflows`. Delete any top-level `workflows` key if it appears.
|
|
|
|
### "Follow the X workflow" prose fragments are non-standard — use "Execute end-to-end."
|
|
After stripping prose @-refs, some command `<process>` blocks retained bolded "**Follow the X workflow**" fragments. ADR-0002 standard is `Execute end-to-end.` for single-workflow commands. Routing commands with flag dispatch use `execute the X workflow end-to-end.` in routing bullets (no bold, no redundant path).
|
|
|
|
---
|
|
|
|
## Recurring CodeRabbit review patterns (2026-05-05, PRs #3152/#3154/#3155)
|
|
|
|
### Changeset metadata drift (`pr:` points at issue instead of PR)
|
|
- In `.changeset/*.md`, reviewers repeatedly flag `pr:` values that accidentally reference issue ids.
|
|
- **Rule**: `pr:` must equal the GitHub PR number carrying the change.
|
|
- **Pre-flight check**: before push, verify each new changeset file against current branch PR number.
|
|
|
|
### Test diagnostics quality for command-output parsing
|
|
- Even when behavior is correct, CR requests clearer failure surfaces before `.map()` on parsed output.
|
|
- **Rule**: after `JSON.parse`, assert output object shape (e.g., `Array.isArray(output.phases)`) with raw-output-prefix diagnostics.
|
|
- This prevents opaque `TypeError` failures and shortens triage loops when CLI output shape changes.
|
|
|
|
### Merge gate discipline: CodeRabbit pass is necessary but not sufficient
|
|
- CI/checks can be green while unresolved review threads still block clean merge policy.
|
|
- **Rule**: always gate on all three together: required checks green, CodeRabbit pass, unresolved thread count = 0.
|
|
- Keep using GraphQL `reviewThreads` as authoritative unresolved state, not summary comments/check badge alone.
|
|
|
|
---
|
|
|
|
## SDK Runtime Bridge review synthesis (PR #3158, 2026-05-05)
|
|
|
|
### What we fixed
|
|
- Deepened one **SDK Runtime Bridge Module** seam (`sdk/src/query-runtime-bridge.ts`) for dispatch routing and observability.
|
|
- Replaced orphan event typing with a canonical union (`RuntimeBridgeEvent`).
|
|
- Made bridge observability non-intrusive: `onDispatchEvent` now runs behind a safe emitter so callback failures cannot alter dispatch outcomes.
|
|
- Corrected strict-mode event semantics: strict native-adapter rejection now reports `dispatchMode: 'native'` (no fake subprocess attempt).
|
|
- Preserved execution policy defaults by passing `allowFallbackToSubprocess` through as `undefined` when unset (no forced override in `GSDTools`).
|
|
- Fixed transport decision ordering: fallback-disabled guard now throws before emitting subprocess decision events.
|
|
- Added explicit invariant in `subprocessReason` for impossible states (fail loud on contract drift).
|
|
- Updated user-facing docs (`README.md`, `docs/CLI-TOOLS.md`, `docs/ARCHITECTURE.md`) and ADR narrative consistency.
|
|
|
|
### What we should not do again
|
|
- Do not let observability callbacks sit on the critical path without isolation.
|
|
- Do not emit structured events that claim a transport mode that never happened.
|
|
- Do not force option defaults at call sites when policy Modules already define defaults.
|
|
- Do not keep duplicate/inert exported types; expose one canonical union Interface.
|
|
- Do not emit decision events before guard checks that may reject the path.
|
|
- Do not leave architectural docs with ambiguous seam ownership between CLI and SDK paths.
|