docs: fix stale codegraph check flag names across README and guides (#1984) - #2193
Conversation
…1984) Found while fixing #1842 (recommended-practices.md's identical staleness) that the same stale/fabricated codegraph check predicate flags extend to 7 more files: - README.md - docs/contributing/harness-engineering.md - docs/use-cases/harness-engineering.md - docs/use-cases/titan-paradigm.md - docs/guides/ai-agent-guide.md - docs/examples/CLI.md - docs/examples/MCP.md - docs/roadmap/BACKLOG.md (only the "DONE" summary; the strikethrough original feature request is left as historical record) Renamed: --no-new-cycles -> --cycles, --max-blast-radius -> --blast-radius, --no-boundary-violations -> --boundaries. Removed entirely (not renamed): --max-complexity, which never existed as a check predicate at all -- there is no complexity-threshold gate wired into checkData/runPredicates. Also surfaced --signatures, a real predicate that was never documented anywhere. docs/examples/CLI.md and docs/examples/MCP.md additionally had sample output in a format that no longer matches the real renderer at all (a "✓ name (value) — description" / "Result: PASS (exit code N)" style, and a "checks" JSON array with "detail" fields) -- rewrote those specific blocks to match the actual [PASS]/[FAIL] console format and predicates/summary JSON shape (verified against src/presentation/check.ts and src/features/check.ts directly). Generalized tests/unit/docs-check-flags.test.ts (originally #1842-only) to cover all 7 newly-fixed docs, deriving the valid flag set from command.options in src/cli/commands/check.ts so a future rename fails here instead of silently drifting again. docs/use-cases/harness-engineering.md, docs/use-cases/titan-paradigm.md, and docs/guides/ai-agent-guide.md are checked for stale-flag absence only, not the stricter valid-flags-only scan, since they legitimately illustrate proposed/not-yet-built predicates (e.g. --floating-promises) and reference other commands' own "Key flags" rows. Closes #1984 docs check acknowledged: this IS the docs fix
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| codegraph check --cycles # Fail if staged changes introduce cycles | ||
| codegraph check --blast-radius 50 # Fail if blast radius exceeds limit | ||
| codegraph check --boundaries # Fail on architecture boundary violations | ||
| codegraph check --signatures # Fail if an exported declaration's line was modified |
There was a problem hiding this comment.
When these examples are run without --staged or a positional ref, codegraph check selects manifesto mode and ignores the predicate options, so the documented cycle, blast-radius, boundary, and signature gates are not enforced. The same issue occurs in the non-staged predicate examples in docs/contributing/harness-engineering.md and docs/use-cases/harness-engineering.md.
There was a problem hiding this comment.
Fixed — added --staged to every standalone predicate example across README.md, docs/contributing/harness-engineering.md, and docs/use-cases/harness-engineering.md (the 3 files named), plus 2 more instances the same pattern applied to in docs/examples/CLI.md that weren't in your inline comment. One case (use-cases/harness-engineering.md's "detect all existing boundary violations for cleanup") genuinely intends a whole-codebase check, which is manifesto mode (bare codegraph check, reading manifesto.boundaries from .codegraphrc.json) rather than the --boundaries diff predicate — fixed that example to show the correct invocation for that intent instead of just adding --staged, since --staged/--boundaries together would only check the diff, not "all existing" violations.
Greptile SummaryCorrects stale
Confidence Score: 5/5The PR appears safe to merge. No blocking failure remains. Important Files Changed
Reviews (4): Last reviewed commit: "fix: add remaining missing --staged inst..." | Re-trigger Greptile |
codegraph check's diff predicates (--cycles, --blast-radius,
--boundaries, --signatures) only take effect when isDiffMode is true
(ref argument or --staged passed) -- src/cli/commands/check.ts:
"if (!isDiffMode && !opts.rules) { await runManifesto(...); return; }".
Without --staged/ref, these examples would silently run manifesto mode
instead, completely ignoring the documented flag and leaving the
intended gate unenforced.
Added --staged to every standalone predicate example across README.md,
docs/contributing/harness-engineering.md, docs/use-cases/harness-engineering.md,
and docs/examples/CLI.md (including two more the same pattern applied
to beyond what Greptile's inline comments named).
One case (docs/use-cases/harness-engineering.md's "detect all existing
boundary violations for cleanup" example) genuinely intends a
whole-codebase check rather than a diff -- that's manifesto mode
(bare `codegraph check`, reading manifesto.boundaries from
.codegraphrc.json), not the --boundaries diff predicate, so fixed the
example to show the correct invocation for that intent instead of just
adding --staged.
docs check acknowledged: this IS the docs fix
| | **Deterministic guardrails** | Agent introduces cycles, boundary violations, high blast radius | `codegraph check --staged` with configurable predicates | | ||
| | **Remediation-focused errors** | Agent can't self-correct from opaque error messages | `check` output includes what violated, where, and how to fix | | ||
| | **Mechanical architecture** | Bad patterns compound exponentially without enforcement | `check --no-boundary-violations` + `.codegraphrc.json` boundary rules | | ||
| | **Mechanical architecture** | Bad patterns compound exponentially without enforcement | `check --boundaries` + `.codegraphrc.json` boundary rules | |
There was a problem hiding this comment.
When a user follows the documented check --boundaries invocation, the absence of --staged or a positional ref selects manifesto mode and returns before consuming the boundaries predicate, so changed-code boundary violations are not checked despite the table presenting this as their enforcement mechanism. The same incomplete invocation appears in the architecture-boundary feature row in docs/use-cases/titan-paradigm.md.
There was a problem hiding this comment.
Fixed both — docs/use-cases/harness-engineering.md's "Mechanical architecture" row and docs/use-cases/titan-paradigm.md's "Architecture boundary rules" feature row both said check --boundaries with no --staged/ref, same manifesto-mode gap. Did an exhaustive final sweep across every file this issue touches (grepped for every --cycles/--blast-radius/--boundaries/--signatures occurrence not already followed by 'staged') and confirmed no other instance is missing --staged/ref — the remaining bare flag mentions are flag-name-only prose references (e.g. 'Available predicates: --cycles, --blast-radius ...'), not full command invocations, matching the established #1842 precedent in recommended-practices.md.
Two more instances of the same pattern Greptile caught in round 1, missed because they were in a different section of files already touched: docs/use-cases/harness-engineering.md's "Mechanical architecture" harness-practice-mapping row, and docs/use-cases/titan-paradigm.md's "Architecture boundary rules" feature-table row. Both said `check --boundaries` with no --staged/ref, which silently runs manifesto mode instead per src/cli/commands/check.ts's isDiffMode gate. Did an exhaustive final sweep across every file this issue touched confirming no other bare predicate-flag invocation is missing --staged/ref (the remaining bare `--cycles`/`--blast-radius <n>` mentions are flag-name-only prose references, not full command invocations, matching the established #1842 precedent). docs check acknowledged: this IS the docs fix
1 similar comment
1 participant
Summary
Verification
Closes #1984