feat!: add --strict and --output <format> (SARIF), remove --json/--ci/--max-warnings from check - #536
Conversation
Adds a linter-style --strict flag that escalates otherwise-advisory diagnostics into failures: rule-severity warnings (acting as --max-warnings 0 unless an explicit threshold is set), plus briefingWarnings, suppressionWarnings, and unparsedAdrs on check; truncatedBriefings and reused checkSummary findings on review-context; and result.errors on adr sync. Resolves via CLI flag, then a new strict key in .archgate/config.json, then off — mirroring the existing baseBranch precedent. Documents the severity-tier model and per-command semantics in a new ADR (ARCH-026), updates the CLI reference docs (with pt-br/nb mirrors), and adds test coverage across reporter, check, review-context, and adr sync. Signed-off-by: Rhuan Barreto <rhuan.barreto@gmail.com> Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughIntroduces configurable 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Deploying archgate-cli with
|
| Latest commit: |
a8c0933
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://3b2863a7.archgate-cli.pages.dev |
| Branch Preview URL: | https://claude-validated-crafting-ma.archgate-cli.pages.dev |
Code Coverage
Full HTML report available in workflow artifacts. Per-directory breakdown
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/public/llms-full.txt`:
- Around line 4220-4226: Add the strict configuration option to the “Reference:
Configuration” schema and field list, matching the documented boolean behavior
and default usage shown in the CLI guidance. Keep the existing configuration
reference structure and descriptions consistent while ensuring strict is
represented as a supported setting.
- Around line 4067-4076: Update the generated documentation’s strict-mode
wording near the CLI options and the corresponding section around the duplicated
default descriptions: replace broad references to “any warning” or “every
warning-shaped diagnostic” with “rule-severity warning,” and explicitly identify
advisory failures as limited to briefingWarnings, suppressionWarnings, and
unparsedAdrs. Keep the documented behavior aligned with src/commands/check.ts
and update both occurrences consistently.
In `@docs/src/content/docs/nb/reference/cli/adr.mdx`:
- Around line 291-296: Document the --strict precedence for archgate adr sync
alongside its options table: CLI --strict takes priority, then the strict key in
.archgate/config.json, with strict mode disabled by default. Use the existing
Norwegian terminology and explain that this configuration-based default applies
to adr sync.
In `@docs/src/content/docs/nb/reference/cli/check.mdx`:
- Around line 155-176: Update the final sentence about the explicit --strict
flag in the configuration section to state that it enables strict mode and
overrides a configured strict: false value. Do not imply that the flag can
disable strict mode or override a configured strict: true setting, since the CLI
exposes no --no-strict option.
In `@docs/src/content/docs/pt-br/reference/cli/adr.mdx`:
- Around line 291-296: Update the `--strict` entry in the `adr sync` options
table to document that its default can be configured through
`.archgate/config.json`, matching the precedence and wording used in `check.mdx`
and `review-context.mdx`; keep the existing strict-mode behavior description
intact.
In `@docs/src/content/docs/pt-br/reference/cli/check.mdx`:
- Around line 155-176: Atualize a documentação de configuração do modo estrito
para esclarecer que `strict: false` em `.archgate/config.json` desativa o modo
estrito por padrão, enquanto `--strict` apenas o habilita explicitamente e não
deve ser descrito como uma substituição de um valor configurado como `false`.
Aplique essa correção nas instruções compartilhadas por `archgate check`,
`archgate review-context` e `archgate adr sync`.
In `@docs/src/content/docs/reference/cli/adr.mdx`:
- Around line 291-296: Update the adr sync reference documentation around the
--strict option to document its project-wide .archgate/config.json strict
setting and precedence: CLI flag, then config value, otherwise off. Add an
equivalent Strict mode explanation or a cross-reference to the existing guidance
in check.mdx or review-context.mdx, while keeping the options table accurate.
In `@docs/src/content/docs/reference/cli/check.mdx`:
- Around line 155-176: Clarify the strict-mode configuration statement near the
`--strict` documentation to reflect the actual precedence: the boolean
`--strict` flag can enable strict mode over a disabled or absent config default,
but cannot disable a configured `strict: true` because no `--no-strict` option
exists. Update the wording without changing the documented behavior of `check`,
`review-context`, or `adr sync`.
In `@src/commands/check.ts`:
- Line 146: Update src/commands/check.ts lines 146-146 around buildSummary to
derive strict-triggered failure reasons after reporting and call logWarn()
before exitWith(1) when strict supplies the implicit zero-warning threshold or
advisory escalation. In src/engine/reporter.ts lines 315-322 and 406-411, remove
or relocate the strict-specific direct console.log diagnostics while retaining
the reporting data and ensuring engine logging uses the helper convention.
In `@src/engine/reporter.ts`:
- Around line 20-25: Update the documentation comment for briefingWarnings to
clarify that these findings do not affect pass in normal mode, but do affect it
when strict mode is enabled. Keep the existing behavior and the
strictAdvisoryExceeded documentation unchanged.
In `@tests/commands/adr/sync-strict.test.ts`:
- Around line 18-33: Replace the mock.module setup for the first-party registry
module with an import namespace for registry and spyOn calls targeting
registry.resolveSource and registry.shallowClone. Update the existing mock setup
and useMocks implementations to configure those spies, and restore both spies
after each test while preserving their current behavior.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: fc27c744-2de9-4c26-990d-044436f53763
📒 Files selected for processing (30)
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md.claude/agent-memory/archgate-developer/MEMORY.mddocs/public/llms-full.txtdocs/src/content/docs/nb/reference/cli/adr.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/nb/reference/cli/review-context.mdxdocs/src/content/docs/pt-br/reference/cli/adr.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/pt-br/reference/cli/review-context.mdxdocs/src/content/docs/reference/cli/adr.mdxdocs/src/content/docs/reference/cli/check.mdxdocs/src/content/docs/reference/cli/review-context.mdxsrc/commands/adr/sync.tssrc/commands/check.tssrc/commands/review-context.tssrc/engine/context.tssrc/engine/reporter.tssrc/formats/project-config.tssrc/helpers/project-config.tssrc/helpers/telemetry.tstests/commands/adr/sync-strict.test.tstests/commands/adr/sync.test.tstests/commands/check-action.test.tstests/commands/review-context.test.tstests/engine/reporter-strict.test.tstests/formats/project-config-fuzz.test.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tstests/integration/check-strict.test.tstests/integration/review-context-strict.test.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: Smoke Test (Windows) / Windows
- GitHub Check: Cloudflare Pages
🧰 Additional context used
📓 Path-based instructions (32)
tests/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
In test files, use
_resetPlatformCache()to simulate different platforms instead of mocking or mutatingprocess.platformdirectly.
tests/**/*.ts: Use Bun's built-inbun testrunner for all tests; test files use Bun's Jest-compatible API and native TypeScript execution.
Restore every captured environment variable withrestoreEnv(key, original)rather than assigningundefinedor a captured value directly.
New source files must have corresponding test files, and total line coverage must remain at or above 90%, enforced in CI.
Files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tstests/formats/project-config-fuzz.test.tstests/commands/adr/sync.test.tstests/commands/adr/sync-strict.test.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tstests/integration/review-context-strict.test.ts
{src,tests}/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/LEGAL-001-spdx-license-headers.md)
{src,tests}/**/*.ts: Every TypeScript source file insrc/andtests/must begin with// SPDX-License-Identifier: Apache-2.0followed by// Copyright 2026 Archgate.
If a TypeScript file has a shebang line (for example#!/usr/bin/env buninsrc/cli.ts), the SPDX license header must appear immediately after the shebang.
Use single-line//comments for the SPDX header; do not use block comments (/* */) or alternate license identifiers.
Files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tssrc/formats/project-config.tstests/formats/project-config-fuzz.test.tstests/commands/adr/sync.test.tssrc/helpers/telemetry.tstests/commands/adr/sync-strict.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tssrc/commands/check.tstests/integration/review-context-strict.test.tssrc/engine/context.tssrc/commands/adr/sync.tssrc/engine/reporter.tssrc/helpers/project-config.ts
tests/**/*.test.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-005-testing-standards.md)
tests/**/*.test.ts: Name test files<module-name>.test.tsand mirror thesrc/directory structure, such assrc/engine/runner.ts→tests/engine/runner.test.ts.
Use isolatedmkdtempdirectories for filesystem tests and remove them inafterEachorafterAll.
Test each module's public interface with descriptive behavior-oriented names; do not test private internals.
Mockos.homedir()rather thanHOME; environment overrides are valid only for code that readsBun.envat call time.
Close external SDK servers, clients, and transports withawait ...close()inafterEachorafterAll, managing their lifecycle in hooks.
Configuregit config user.emailanduser.namelocally immediately aftergit initand before any commit in temporary repositories.
Every runnable test must contain at least oneexpect()assertion; use explicit no-throw assertions and usetest.skiportest.todofor placeholders.
Mock HTTP requests by assigningglobalThis.fetch, and restore the mock inafterEach; do not mocknode:fetch.
Do not make network requests in unit tests.
Mock first-party modules withimport * as modandspyOn(mod, "fn"), restoring mocks after each test; reservemock.module()for third-party modules.
Wrap inlinespyOnormockImplementationusage intry/finallysomockRestore()always runs, or manage the spy in hooks.
SetBun.env.NODE_ENV = "test"before initializing Sentry, and never write tests to real user-scope paths; mock the writer oros.homedir()instead.
Inject small production thresholds in threshold tests, such asfileWarnThreshold: 5, instead of generating large fixtures.
Per-test timeout overrides must not be shorter than the globalbun test --timeout 60000setting.
Do not usenode:test; import the testing API frombun:test.
tests/**/*.test.ts: Usetest.each()when the same assertion logic runs against multiple independent inputs, so each case is independently named and reported.
Usedescribe.each()when...
Files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tstests/formats/project-config-fuzz.test.tstests/commands/adr/sync.test.tstests/commands/adr/sync-strict.test.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tstests/integration/review-context-strict.test.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-006-dependency-policy.md)
**/*.{ts,tsx}: Prefer Bun built-ins for file I/O, HTTP, globbing, testing, and subprocess execution; prefernode:built-in modules over npm alternatives when appropriate.
UseBun.spawnwith array-based arguments for all subprocess execution; do not useBun.$because it can hang on Windows.
Do not add npm packages for functionality already provided by Bun, such asglob,chalk, or utility libraries used for a single function.
Use Bun APIs such asBun.file()instead of Node.js-specific APIs such asfs.readFile()when Bun provides an equivalent.
Use relative imports with Bun's native module resolution; do not use TypeScript path aliases.
**/*.{ts,tsx}: Use TypeScript strict mode with ESNext and ES modules.
Prefer minimal dependencies and Bun built-ins where appropriate.
Files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tssrc/formats/project-config.tstests/formats/project-config-fuzz.test.tstests/commands/adr/sync.test.tssrc/helpers/telemetry.tstests/commands/adr/sync-strict.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tssrc/commands/check.tstests/integration/review-context-strict.test.tssrc/engine/context.tssrc/commands/adr/sync.tssrc/engine/reporter.tssrc/helpers/project-config.ts
**/*.{rules.ts,ts}
📄 CodeRabbit inference engine (.archgate/adrs/LEGAL-002-dependency-license-compatibility.md)
Newly encountered permissive licenses may be added to the LEGAL-002 allowlist in the rule implementation, with a comment explaining any override for packages whose package.json lacks a license field.
Files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tssrc/formats/project-config.tstests/formats/project-config-fuzz.test.tstests/commands/adr/sync.test.tssrc/helpers/telemetry.tstests/commands/adr/sync-strict.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tssrc/commands/check.tstests/integration/review-context-strict.test.tssrc/engine/context.tssrc/commands/adr/sync.tssrc/engine/reporter.tssrc/helpers/project-config.ts
**/*.test.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Tests should mirror the
src/structure, with fixtures located undertests/fixtures/.
Files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tstests/formats/project-config-fuzz.test.tstests/commands/adr/sync.test.tstests/commands/adr/sync-strict.test.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tstests/integration/review-context-strict.test.ts
**/*
📄 CodeRabbit inference engine (CLAUDE.md)
Run
bun run validatesuccessfully before considering any task complete; it performs linting, typechecking, formatting checks, tests, ADR checks, dead-export detection, and build checks.
Files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tssrc/formats/project-config.tstests/formats/project-config-fuzz.test.tsdocs/src/content/docs/nb/reference/cli/adr.mdxdocs/src/content/docs/reference/cli/adr.mdxdocs/src/content/docs/pt-br/reference/cli/adr.mdxtests/commands/adr/sync.test.tssrc/helpers/telemetry.tstests/commands/adr/sync-strict.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tssrc/commands/check.tsdocs/src/content/docs/nb/reference/cli/review-context.mdxtests/integration/review-context-strict.test.tsdocs/src/content/docs/nb/reference/cli/check.mdxsrc/engine/context.tssrc/commands/adr/sync.tsdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/public/llms-full.txtdocs/src/content/docs/reference/cli/check.mdxsrc/engine/reporter.tsdocs/src/content/docs/reference/cli/review-context.mdxsrc/helpers/project-config.tsdocs/src/content/docs/pt-br/reference/cli/review-context.mdx
**
⚙️ CodeRabbit configuration file
**: This project uses Archgate — an AI governance framework based on
Architecture Decision Records (ADRs). The ADRs in.archgate/adrs/
are the authoritative rules for this codebase. Each ADR has a companion
.rules.tsfile with automated checks that run viaarchgate check.When reviewing, you must:
- Treat ADR violations as blocking issues, not suggestions.
- Cite the specific ADR ID when flagging a violation (e.g., "Violates ARCH-006").
- Focus on semantic and contextual violations that automated rules cannot catch —
the.rules.tsfiles already cover syntactic/structural patterns.- If you are unsure whether something violates an ADR, flag it as a question
rather than approving it.
Files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tssrc/formats/project-config.tstests/formats/project-config-fuzz.test.tsdocs/src/content/docs/nb/reference/cli/adr.mdxdocs/src/content/docs/reference/cli/adr.mdxdocs/src/content/docs/pt-br/reference/cli/adr.mdxtests/commands/adr/sync.test.tssrc/helpers/telemetry.tstests/commands/adr/sync-strict.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tssrc/commands/check.tsdocs/src/content/docs/nb/reference/cli/review-context.mdxtests/integration/review-context-strict.test.tsdocs/src/content/docs/nb/reference/cli/check.mdxsrc/engine/context.tssrc/commands/adr/sync.tsdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/public/llms-full.txtdocs/src/content/docs/reference/cli/check.mdxsrc/engine/reporter.tsdocs/src/content/docs/reference/cli/review-context.mdxsrc/helpers/project-config.tsdocs/src/content/docs/pt-br/reference/cli/review-context.mdx
src/**/!(*platform).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
src/**/!(*platform).ts: Insrc/TypeScript source files, do not readprocess.platformdirectly; usesrc/helpers/platform.ts(isWindows(),isMacOS(),isLinux(),isWSL(),getPlatformInfo()) for all platform detection.
Use the centralized platform helper instead of duplicating OS/WSL detection logic inline anywhere insrc/TypeScript source.
When behavior differs between Linux and Windows, account for WSL by usingisWSL()rather than assuming `
Files:
src/formats/project-config.tssrc/helpers/telemetry.tssrc/commands/review-context.tssrc/commands/check.tssrc/engine/context.tssrc/commands/adr/sync.tssrc/engine/reporter.tssrc/helpers/project-config.ts
src/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-010-prefer-bun-built-in-json-parsing.md)
src/**/*.ts: Useawait Bun.file(path).json()when reading JSON files in Bun TypeScript source code; do not useJSON.parse(await Bun.file(path).text())orJSON.parse(fs.readFileSync(path, "utf-8"))for file reads.
UseBun.JSONC.parse()when reading files that may contain comments, such astsconfig.json, instead of plainJSON.parse()on file contents.
ReserveJSON.parse()for parsing JSON strings from non-file sources such as API responses or string variables; do not use it as the default for reading JSON files.
src/**/*.ts: Use exit codes 0 for success, 1 for expected failures, 2 for internal errors, and 130 for user cancellation; do not use other exit codes.
UselogError()fromsrc/helpers/log.tsfor user-facing errors; write errors to stderr, not stdout, and avoid directconsole.error()calls.
Provide actionable suggestions in user-facing error messages whenever possible.
Do not show stack traces for user-triggered errors; unexpected errors may include stack traces only whenDEBUGorTRACEis set.
Do not catch and swallow unexpected errors; caught errors must be logged or re-thrown.
Do not exit with code 0 when an operation fails; expected failures must use exit code 1.
Fall back toprocess.cwd()whenfindProjectRoot()returns null in commands that do not require.archgate/.
Handle Inquirer'sExitPromptErrorat the top-level error boundary as user cancellation: exit with code 130, do not log an error, and do not send it to Sentry.
Do not sendUserErroror user-cancellationExitPromptErrorinstances to Sentry from any error handler, includingbeforeSend.
UseexitWith()rather than bareprocess.exit()when terminating after command execution so telemetry and Sentry data are flushed.
src/**/*.ts: UsestyleText(format, text)fromnode:utilfor all colored CLI output; do not use raw ANSI escape codes or third-party color libraries.
Commands producing structured results must support--json; JSON output must contain ...
Files:
src/formats/project-config.tssrc/helpers/telemetry.tssrc/commands/review-context.tssrc/commands/check.tssrc/engine/context.tssrc/commands/adr/sync.tssrc/engine/reporter.tssrc/helpers/project-config.ts
src/formats/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Treat Zod schemas as the single source of truth; derive types with
z.infer<>, never define separate interfaces, usesafeParse(), and reuseAdrFrontmatterSchema.shape.*instead of duplicating enums.
Files:
src/formats/project-config.ts
docs/**/*.{mdx,astro,ts,mjs,json}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
The documentation site must be an Astro 5/Starlight project under
docs/, separate from the CLI project with its own package manifest, TypeScript configuration, lockfile, and build pipeline.
Files:
docs/src/content/docs/nb/reference/cli/adr.mdxdocs/src/content/docs/reference/cli/adr.mdxdocs/src/content/docs/pt-br/reference/cli/adr.mdxdocs/src/content/docs/nb/reference/cli/review-context.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdxdocs/src/content/docs/reference/cli/review-context.mdxdocs/src/content/docs/pt-br/reference/cli/review-context.mdx
docs/src/content/docs/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
docs/src/content/docs/**/*.mdx: Use MDX format for all documentation content pages underdocs/src/content/docs/.
Organize content under the five category prefixes:getting-started/,concepts/,guides/,reference/, andexamples/.
Every content page must includetitleanddescriptionfrontmatter.
Escape literal curly braces in MDX, such asadr://\{id\}; do not use bare{}in prose or code labels.
Keep reference pages accurate to the CLI source code and update them in the same change that modifies a corresponding CLI API.
docs/src/content/docs/**/*.mdx: Maintain 1:1 parity between root MDX pages and each configured locale: every root file must have a translation at the same relative path, and locale files must not be orphaned.
When English documentation is added or modified, update the corresponding Portuguese and Norwegian locale files in the same pull request.
Translate user-facing prose, headings, titles, descriptions, table text, admonitions, and Starlight component text props; keep code blocks, commands, paths, identifiers, technical terms, imports, component names, and link/href/slug values in English.
Preserve MDX structure, component imports, curly-brace escaping, and internal link paths; internal links must not contain locale prefixes such as/pt-br/.
Do not restructure the root content directory for translations; locale files must mirror the root content directory's relative paths.
Keep code blocks, CLI commands, file paths, and technical identifiers in English during translation.
Files:
docs/src/content/docs/nb/reference/cli/adr.mdxdocs/src/content/docs/reference/cli/adr.mdxdocs/src/content/docs/pt-br/reference/cli/adr.mdxdocs/src/content/docs/nb/reference/cli/review-context.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdxdocs/src/content/docs/reference/cli/review-context.mdxdocs/src/content/docs/pt-br/reference/cli/review-context.mdx
docs/**/*
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
docs/**/*: Do not include the docs build in the CLIvalidatepipeline; docs build failures must not block CLI development or CI.
Do not create content files outsidedocs/src/content/docs/, becausedocsLoader()expects that directory structure.
Install documentation dependencies from withindocs/usingcd docs && bun installor the docs convenience scripts, not from the repository root.
Files:
docs/src/content/docs/nb/reference/cli/adr.mdxdocs/src/content/docs/reference/cli/adr.mdxdocs/src/content/docs/pt-br/reference/cli/adr.mdxdocs/src/content/docs/nb/reference/cli/review-context.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/public/llms-full.txtdocs/src/content/docs/reference/cli/check.mdxdocs/src/content/docs/reference/cli/review-context.mdxdocs/src/content/docs/pt-br/reference/cli/review-context.mdx
docs/src/content/docs/nb/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Write Norwegian Bokmål translations, not Nynorsk, using informal
duand correct characters such as æ, ø, and å; do not remove accents or use unreviewed machine translation.
Files:
docs/src/content/docs/nb/reference/cli/adr.mdxdocs/src/content/docs/nb/reference/cli/review-context.mdxdocs/src/content/docs/nb/reference/cli/check.mdx
docs/src/content/docs/reference/cli/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
docs/src/content/docs/reference/cli/**/*.mdx: Every.mdxfile underdocs/src/content/docs/reference/cli/, exceptindex.mdx, must correspond to a top-level CLI command, and removed commands must have their orphaned pages deleted.
Document subcommands inline within the parent command's.mdxpage; do not create separate top-level pages such asadr-create.mdxorlogin-status.mdx.
Each top-level CLI reference page should follow the established structure: frontmatter withtitleanddescription, a one-line introduction, applicable subcommand and options tables, examples, and troubleshooting guidance where relevant.
Files:
docs/src/content/docs/reference/cli/adr.mdxdocs/src/content/docs/reference/cli/check.mdxdocs/src/content/docs/reference/cli/review-context.mdx
{src/commands/*/!(index).ts,src/commands/*/*/index.ts,docs/src/content/docs/reference/cli/*.mdx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
Every direct subcommand represented by
src/commands/<parent>/<sub>.tsorsrc/commands/<parent>/<sub>/index.tsmust have a corresponding heading indocs/src/content/docs/reference/cli/<parent>.mdx, and every heading matchingarchgate <parent> <sub>must correspond to an actual subcommand file. Matching is case-insensitive.
Files:
docs/src/content/docs/reference/cli/adr.mdxsrc/commands/adr/sync.tsdocs/src/content/docs/reference/cli/check.mdxdocs/src/content/docs/reference/cli/review-context.mdx
docs/src/content/docs/reference/cli/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
Document subcommands using a heading containing the exact command text
archgate <parent> <sub>; do not use non-standard heading formats.
Files:
docs/src/content/docs/reference/cli/adr.mdxdocs/src/content/docs/reference/cli/check.mdxdocs/src/content/docs/reference/cli/review-context.mdx
docs/src/content/docs/pt-br/reference/cli/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
Every English top-level CLI reference page must have a matching pt-br mirror at
docs/src/content/docs/pt-br/reference/cli/<name>.mdx.
Files:
docs/src/content/docs/pt-br/reference/cli/adr.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/pt-br/reference/cli/review-context.mdx
docs/src/content/docs/pt-br/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Write Brazilian Portuguese translations with correct diacritical marks, including characters such as ã, ç, é, í, ó, ú, â, ê, ô, and à; do not remove accents or use unreviewed machine translation.
Files:
docs/src/content/docs/pt-br/reference/cli/adr.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/pt-br/reference/cli/review-context.mdx
src/helpers/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-002-error-handling.md)
In helper files, use
logInfo()orlogWarn()instead of directconsole.log(),console.warn(), orconsole.info()calls.
Files:
src/helpers/telemetry.tssrc/helpers/project-config.ts
src/commands/!(index).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-001-command-structure.md)
Each top-level command module under
src/commands/must define exactly one command and export aregister*Command(program)function.
Files:
src/commands/review-context.tssrc/commands/check.ts
src/commands/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-001-command-structure.md)
src/commands/**/*.ts: Command files must remain thin: parse arguments, call engine or helper functions, and format output; business logic must reside insrc/engine/,src/helpers/, orsrc/formats/.
Commands must execute in-process and must not spawn child processes for subcommand execution.
Command modules must not call.parse(); command parsing is handled by the CLI entry point.
src/commands/**/*.ts: In Commander.js command files, options requiring type narrowing beyond plain strings MUST usenew Option()from@commander-js/extra-typingsand register it with.addOption(), rather than using.option().
Use.choices([... ] as const)for options accepting a fixed set of values, and do not add manual validation or unsafe casts for those choices.
Use.argParser((value) => ...)on anOptionfor options requiring type conversion; do not pass parser functions such asparseIntas the third argument to.option().
Useas constfor.choices()arrays and.default()values to preserve literal types.
Reuse existing type definitions for type-level usage, access narrowed options directly, and avoid casts such asopts.editor as SomeType.
src/commands/**/*.ts: All commands that operate on.archgate/project resources must use the sharedfindProjectRoot()fromsrc/helpers/paths.ts; directprocess.cwd()project-root resolution is prohibited except ininit.
Commands that require a project must userequireProjectRoot()fromsrc/helpers/paths.tsinstead of implementing their own missing-project guard. Commands that can operate without a project may usefindProjectRoot()and handlenullthemselves.
When usingfindProjectRoot()directly, check for anullresult and provide a helpful error before exiting.
Pass the resolvedprojectRoottoprojectPaths()when constructing derived project paths.
Do not define localfindProjectRoot()variants; use the shared implementation fromsrc/helpers/paths.ts.
src/commands/**/*.ts: Ev...
Files:
src/commands/review-context.tssrc/commands/check.tssrc/commands/adr/sync.ts
src/commands/{check,review-context}.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
src/commands/{check,review-context}.ts:archgate checkandarchgate review-contextMUST support a boolean--strictflag that escalates applicable advisory diagnostics to exit code 1.
Print the complete result payload before exiting non-zero for a strict-mode failure, and log a clear--strict-attributed message naming the findings that caused the failure.
Files:
src/commands/review-context.tssrc/commands/check.ts
src/{commands/check.ts,commands/review-context.ts,commands/adr/sync.ts}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
Resolve strict mode using CLI precedence over configuration:
opts.strict ?? getConfiguredStrict(projectRoot) ?? false.
Files:
src/commands/review-context.tssrc/commands/check.tssrc/commands/adr/sync.ts
src/commands/review-context.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
review-context --strictmust fail for truncated briefings or, with--run-checks,warningsExceeded/strictAdvisoryExceeded; it must not gate oncheckSummary.failedorruleErrors.
Files:
src/commands/review-context.ts
src/commands/check.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
checkmust fail under strict mode for rule-severity warnings, briefing warnings, suppression warnings, or unparsed ADRs, while preserving all findings in the result payload.
Files:
src/commands/check.ts
src/engine/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-002-error-handling.md)
In engine files, use
logInfo()orlogWarn()instead of directconsole.log(),console.warn(), orconsole.info()calls.Do not add unsanctioned subprocess sites or
child_processimports; AST subprocesses belong in the sanctioned AST support path and Git subprocesses belong ingit-files.ts.
src/engine/**/*.ts: In the rules engine, list files by matching glob patterns in memory against the git-tracked file set; do not walk the filesystem for normal listing.
Route new engine file listings throughlistMatchingFilesfor rule-facing sandboxed input ormatchTrackedFilesfor trusted ADR frontmatter patterns.
When the target is a git repository andrespectGitignoreis not false, pass the tracked set fromgetGitTrackedFilesto the matching path.
ShareRunCachesacross rule contexts inrunChecks; cache glob results by pattern and tracked mode and file text by absolute path using promises for in-flight deduplication.
Copy cached glob arrays before returning them to rule code so rule mutations cannot corrupt shared cache values.
Do not cachereadJSONresults because rules receive mutable objects and shared cached objects could leak mutations between rules.
Do not filter filesystem scan results against the tracked set as a substitute for in-memory matching.
Files:
src/engine/context.tssrc/engine/reporter.ts
src/{engine/**/*.ts,formats/rules.ts,helpers/rules-shim.ts}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-022-ast-aware-rule-context.md)
Expose exactly one catch-all
RuleContext.ast(path: string, language: AstLanguage, opts?: AstOptions): Promise<AstNode>method supporting TypeScript, JavaScript, Python, and Ruby; do not add per-language AST methods.
Files:
src/engine/context.tssrc/engine/reporter.ts
src/commands/adr/sync.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
src/commands/adr/sync.ts:archgate adr syncMUST support--strictand fail with exit code 1 whenresult.errors > 0, while remaining composable with--check'swithChanges > 0condition.
Keepadr sync'sresult.errorsas a sync-specific counter; do not fold it intoReportSummaryor conflate it with the existing--checkdrift condition.
Files:
src/commands/adr/sync.ts
src/engine/reporter.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
src/engine/reporter.ts: InbuildSummary()/getExitCode(), treat strict mode asmaxWarnings: 0only when--max-warningsis unset; an explicit--max-warningsvalue always takes precedence.
ComputestrictAdvisoryExceededcentrally frombriefingWarnings,suppressionWarnings, andunparsedAdrs, and have callers consume that result rather than reimplementing the condition.
Advisory findings must remain present in output when strict mode is disabled; strict mode may change only pass/fail and exit-code behavior.
Any new advisory-styleReportSummaryfield must be included in the centralizedstrictAdvisoryExceededcomputation.
Files:
src/engine/reporter.ts
src/helpers/project-config.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
Provide
getConfiguredStrict()to read thestrict: booleansetting from.archgate/config.json, following the existing configuration helper conventions.
Files:
src/helpers/project-config.ts
🧠 Learnings (16)
📚 Learning: 2026-07-15T22:55:51.978Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 476
File: tests/helpers/telemetry-config.test.ts:24-28
Timestamp: 2026-07-15T22:55:51.978Z
Learning: In this Bun/TypeScript codebase, when a unit under test spawns subprocesses via Bun.spawn (e.g., running `git credential ...`), prefer overriding relevant env vars (such as `HOME`, `GIT_CONFIG_GLOBAL`, `GIT_CONFIG_NOSYSTEM`) using `process.env` in the test and restoring them with the test utility (e.g., `restoreEnv` from `tests/test-utils.ts`). Avoid relying on `spyOn(os, 'homedir')` for this purpose, because it only affects in-process calls and does not change the environment inherited by subprocesses; env-var overrides should be used for subprocess-level isolation and must be applied at call time.
Applied to files:
tests/helpers/telemetry.test.tstests/helpers/project-config.test.ts
📚 Learning: 2026-07-15T22:56:35.415Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 476
File: tests/commands/clean.test.ts:61-62
Timestamp: 2026-07-15T22:56:35.415Z
Learning: When reviewing tests that rely on src/helpers/paths.ts `internalPath()`, note that `internalPath()` intentionally reads `Bun.env.HOME ?? Bun.env.USERPROFILE` at call time and only uses `os.homedir()` if neither env var is set. Therefore, don’t suggest changing tests to `spyOn(os, "homedir")` for this behavior; instead, use per-test `Bun.env.HOME` / `Bun.env.USERPROFILE` overrides (as applicable) so the tests control `internalPath()`’s inputs.
Applied to files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tstests/commands/adr/sync.test.tstests/commands/adr/sync-strict.test.ts
📚 Learning: 2026-07-25T00:05:58.884Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: tests/helpers/auth.test.ts:38-46
Timestamp: 2026-07-25T00:05:58.884Z
Learning: When reviewing the Archgate CLI repository’s GEN-004 “concise forward-only narration” comments, don’t rely only on the automated phrase-based narration checks. Those checks can pass even when the comment wording describes historical/transfer semantics rather than current behavior (e.g., saying a prior restore “leaked” a value or a later subprocess “inherited it”). Manually verify that the comment describes the code’s current, forward behavior; flag or adjust comments that imply past/historical state transfer even if GEN-004 enforcement passes.
Applied to files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tssrc/formats/project-config.tstests/formats/project-config-fuzz.test.tstests/commands/adr/sync.test.tssrc/helpers/telemetry.tstests/commands/adr/sync-strict.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tssrc/commands/check.tstests/integration/review-context-strict.test.tssrc/engine/context.tssrc/commands/adr/sync.tssrc/engine/reporter.tssrc/helpers/project-config.ts
📚 Learning: 2026-07-25T00:05:59.109Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: src/cli.ts:0-0
Timestamp: 2026-07-25T00:05:59.109Z
Learning: Code comments may include a concise issue/PR reference (per GEN-004) when it’s used to point readers to fuller rationale instead of inlining that rationale. During review, flag surrounding comment prose that reads like historical context or narrates refactors/relocations; a bare GEN-004-style reference is allowed and should not be flagged by itself.
Applied to files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tssrc/formats/project-config.tstests/formats/project-config-fuzz.test.tstests/commands/adr/sync.test.tssrc/helpers/telemetry.tstests/commands/adr/sync-strict.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tssrc/commands/check.tstests/integration/review-context-strict.test.tssrc/engine/context.tssrc/commands/adr/sync.tssrc/engine/reporter.tssrc/helpers/project-config.ts
📚 Learning: 2026-07-25T15:44:40.668Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-005-testing-standards.md:0-0
Timestamp: 2026-07-25T15:44:40.668Z
Learning: In Archgate CLI test code governed by ARCH-007, only allow `Bun.$` in test suites that are explicitly restricted to a single platform. Any cross-platform test that runs on Linux, macOS, and Windows must avoid `Bun.$` and instead use array-based `Bun.spawn`. For shared git setup used by tests, import and use the `git()` helper from `tests/test-utils.ts` rather than duplicating git setup logic.
Applied to files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tstests/formats/project-config-fuzz.test.tstests/commands/adr/sync.test.tstests/commands/adr/sync-strict.test.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tstests/integration/review-context-strict.test.ts
📚 Learning: 2026-07-25T22:03:14.216Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-002-error-handling.md:0-0
Timestamp: 2026-07-25T22:03:14.216Z
Learning: In Archgate boundary-wrapped CLI command actions (the handlers that rely on `handleCommandError()` for user-facing error output), expected-failure guards should signal user errors by throwing `new UserError(<message/details>)` rather than directly calling `logError()` followed by `exitWith(1)`. This keeps user-facing logging and the exit path centralized in `handleCommandError()`. For normal/computed command outcomes (e.g., `const exitCode = getExitCode(await runChecks(...))`), use `await exitWith(exitCode)` instead of calling `process.exit(exitCode)` so telemetry/Sentry flushing and outcome tagging still run.
Applied to files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tssrc/formats/project-config.tstests/formats/project-config-fuzz.test.tstests/commands/adr/sync.test.tssrc/helpers/telemetry.tstests/commands/adr/sync-strict.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tssrc/commands/check.tstests/integration/review-context-strict.test.tssrc/engine/context.tssrc/commands/adr/sync.tssrc/engine/reporter.tssrc/helpers/project-config.ts
📚 Learning: 2026-07-25T23:21:49.190Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 512
File: tests/engine/git-files.test.ts:98-100
Timestamp: 2026-07-25T23:21:49.190Z
Learning: When reviewing archgate/cli for ARCH-006 (per its ADR frontmatter), only enforce the production-dependency policy scoped to package.json. Do not treat test-only refactors or relocated `node:fs` fixture writes as an ARCH-006 violation (since ARCH-006 does not govern test-file I/O API selection). If there’s a broader/test-wide refactor that would migrate fixture writing to `Bun.write()`, evaluate it separately under the appropriate in-scope rule.
Applied to files:
tests/helpers/telemetry.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/commands/check-action.test.tstests/formats/project-config-fuzz.test.tstests/commands/adr/sync.test.tstests/commands/adr/sync-strict.test.tstests/engine/reporter-strict.test.tstests/integration/check-strict.test.tstests/integration/review-context-strict.test.ts
📚 Learning: 2026-07-02T16:03:33.031Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 446
File: src/helpers/session-context-opencode.ts:81-100
Timestamp: 2026-07-02T16:03:33.031Z
Learning: For synchronous helper functions that use Bun’s sqlite sync API (i.e., they must remain synchronous), it’s acceptable to use `existsSync` from `node:fs` to check whether the SQLite database file exists. Avoid using `Bun.file(path).exists()` for this purpose because it’s async and would force the helper to become async (no equivalent synchronous Bun alternative). If the DB file is missing, throw/return a clear, actionable "No database found" error (per ARCH-006) rather than letting the sqlite open fail with a generic DB-open error.
Applied to files:
src/helpers/telemetry.tssrc/helpers/project-config.ts
📚 Learning: 2026-06-11T12:50:28.661Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 406
File: .claude/agent-memory/archgate-developer/feedback_prefer_tests_over_adr_rules.md:8-18
Timestamp: 2026-06-11T12:50:28.661Z
Learning: In `archgate/cli`, for markdown files under `.claude/agent-memory/`, follow the established convention: use YAML frontmatter (with a `name:` field used as the document title) and do not require a top-level `#` (H1) heading. During code review, do not flag missing first-line/first-top-level H1 headings (e.g., MD041) for these agent-memory files since markdownlint is not part of the repo’s `bun run validate` lint pipeline (oxlint/oxfmt only).
Applied to files:
.claude/agent-memory/archgate-developer/MEMORY.md
📚 Learning: 2026-07-25T00:05:20.592Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: .claude/agent-memory/archgate-developer/project_test_isolation_gotchas.md:10-10
Timestamp: 2026-07-25T00:05:20.592Z
Learning: When reviewing documentation/agent-memory entries under `.claude/agent-memory/**`, do not enforce GEN-004’s “forward-only” comment/narrative requirement. These entries are allowed to keep historical/past-tense incident narratives and dated markers (e.g., `Found YYYY-MM-DD`) because the context is intended to help future agents evaluate edge cases. Outside this scope, GEN-004’s forward-only rule should still apply.
Applied to files:
.claude/agent-memory/archgate-developer/MEMORY.md
📚 Learning: 2026-07-25T22:03:22.236Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md:64-67
Timestamp: 2026-07-25T22:03:22.236Z
Learning: When reviewing CLI subcommand documentation, don’t rely solely on the companion ARCH-016 enforcement rule’s limited path coverage (it only checks `src/commands/<parent>/*.ts` and `src/commands/<parent>/*/index.ts`). Manually verify that subcommands documented by convention in deeper paths (e.g., `src/commands/<parent>/**/add.ts` or `src/commands/adr/domain/add.ts`) have the required documentation, since future nested subcommands can drift without automated detection (tracked by ARCH-015 / GitHub `#503`).
Applied to files:
src/commands/review-context.tssrc/commands/check.tssrc/commands/adr/sync.ts
📚 Learning: 2026-07-25T23:21:11.504Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 512
File: tests/engine/runner-ast-cache.test.ts:82-82
Timestamp: 2026-07-25T23:21:11.504Z
Learning: For Bun/TS tests under tests/engine, it’s acceptable (per ARCH-025) to validate a runtime-sized collection produced by a single operation by looping over items and making direct assertions like `expect(item).toBe(...)` inside the loop. Treat this as an approved alternative to boolean-collapse assertions such as `expect(items.every(predicate)).toBe(true)`. Do NOT conflate this with prohibited “manual loops” that create independent test cases (e.g., calling `test(...)`/`it(...)` inside a loop); that pattern should still be flagged.
Applied to files:
tests/engine/reporter-strict.test.ts
📚 Learning: 2026-07-11T13:03:15.386Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 467
File: .archgate/adrs/ARCH-011-consistent-project-root-resolution.md:0-0
Timestamp: 2026-07-11T13:03:15.386Z
Learning: For Markdown files formatted by oxfmt (especially ADRs), avoid inline code spans that contain escaped backticks, e.g. `\`...\`` inside a single `` `...` `` span. oxfmt may mis-parse these and, on re-format, can collapse spaces after later inline code spans on the same line, effectively removing any manually re-added spacing. Instead, rephrase the text so the message stays plain quoted text, and put any embedded command/fragment that needs code formatting (e.g., `archgate init`) in its own separate inline code span; keep surrounding punctuation/spacing outside the code span.
Applied to files:
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
📚 Learning: 2026-07-25T16:24:51.133Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-003-output-formatting.md:0-0
Timestamp: 2026-07-25T16:24:51.133Z
Learning: In Archgate ADRs (.archgate/adrs/*.md), omit quantitative claims (e.g., token savings, benchmarks, performance deltas) unless they are backed by a reproducible measurement and supported by a single cited reference. If you cannot satisfy both (reproducible measurement + exactly one cited reference), describe the benefit qualitatively and tie it to the relevant policy/requirements instead of using numeric estimates.
Applied to files:
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
📚 Learning: 2026-07-25T22:03:17.073Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-015-cli-command-documentation-coverage.md:17-18
Timestamp: 2026-07-25T22:03:17.073Z
Learning: When updating an ADR that documents rule discovery/enforcement behavior, ensure the ADR’s stated discovery contract matches the implementation in code. If the rule only discovers commands by scanning `src/commands/*.ts` and `src/commands/*/index.ts`, the ADR must not claim it also inspects command registration calls elsewhere (e.g., `src/cli.ts`). Any ADR language that changes the documented contract should be treated as a normative change to behavior and aligned with the corresponding implementation/issue, not as prose-only documentation compression.
Applied to files:
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
📚 Learning: 2026-07-26T13:09:49.888Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 533
File: .archgate/adrs/ARCH-020-glob-scan-include-dotfiles.md:0-0
Timestamp: 2026-07-26T13:09:49.888Z
Learning: In archgate/cli rule ADRs, `ctx.scopedFiles` is computed from the ADR frontmatter `files` glob patterns before the rule context is constructed. For ARCH-020-style rules, ensure the ADR `files` frontmatter correctly scopes the allowed paths (e.g., `files: ["src/**/*.ts"]`); then rule-specific `.ts`/file filters should assume the incoming file list is already restricted and avoid re-applying the same path-prefix restriction inside individual rules.
Applied to files:
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
🪛 LanguageTool
docs/src/content/docs/pt-br/reference/cli/adr.mdx
[grammar] ~324-~324: Possível erro de concordância.
Context: ...ash archgate adr sync --yes ``` Falhar o build se alguma importação não puder ser reso...
(ERRO_DE_CONCORDNCIA_DO_GÉNERO_MASCULINO_O)
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
[style] ~56-~56: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...her than re-deriving the condition. - DO print the full result payload before ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~57-~57: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...at was found, not just the failure. - DO extend --strict to a new advisory-s...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~58-~58: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...not a parallel condition elsewhere. - DO log a clear, --strict-attributed me...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~59-~59: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...lure, before calling exitWith(1). - DO treat adr sync's result.errors as...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~65-~65: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...licit --max-warnings always wins. - DON'T gate review-context --strict on ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~66-~66: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...is responsible for rule violations. - DON'T introduce a --no-strict negation...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~67-~67: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...hree resolution states without one. - DON'T drop an advisory finding from the ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/src/content/docs/pt-br/reference/cli/check.mdx
[uncategorized] ~19-~19: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ... | | --base [ref] | Comparar arquivos alterados c...
(ABREVIATIONS_PUNCTUATION)
[uncategorized] ~19-~19: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ... Comparar arquivos alterados contra uma ref base (auto-detecta quando omitido) ...
(ABREVIATIONS_PUNCTUATION)
[misspelling] ~19-~19: Esta é uma palavra só.
Context: ...arquivos alterados contra uma ref base (auto-detecta quando omitido) ...
(AUTO)
[style] ~24-~24: Evite abreviações de internet. Considere escrever “não” por extenso. Se quis dizer “n”, coloque entre aspas.
Context: ... | | --max-warnings <n> | Falhar (código 1) quando a contagem...
(INTERNET_ABBREVIATIONS)
[style] ~24-~24: Evite abreviações de internet. Considere escrever “não” por extenso. Se quis dizer “n”, coloque entre aspas.
Context: ... 1) quando a contagem de avisos exceder n. Use 0 para falhar com qualquer avis...
(INTERNET_ABBREVIATIONS)
[uncategorized] ~155-~155: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ... Elas são **consultivas e nunca afetam pass, a menos que --strict esteja definid...
(ABREVIATIONS_PUNCTUATION)
[uncategorized] ~157-~157: Esta conjunção deve ser separada por vírgulas e só deve ser utilizada no início duma frase para efeitos de estilo.
Context: ...onsequences, que nunca entram no resumo e portanto nunca têm limite; remova narrativa hist...
(VERB_COMMA_CONJUNCTION)
[uncategorized] ~159-~159: Esta locução deve ser separada por vírgulas, e só deve ser utilizada no início duma frase para efeitos de estilo.
Context: ...ção exceda o limite, e ela NÃO DEVE ser encurtada além disso. Registre o motivo na seção Compliance ...
(VERB_COMMA_CONJUNCTION)
[uncategorized] ~161-~161: Pontuação duplicada
Context: ... nunca alteram o código de saída. Passe --max-warnings <n> para fazer `archgate c...
(DOUBLE_PUNCTUATION_XML)
[style] ~161-~161: Evite abreviações de internet. Considere escrever “não” por extenso. Se quis dizer “n”, coloque entre aspas.
Context: ...ando a contagem total de avisos exceder n. --max-warnings 0 falha com qualquer...
(INTERNET_ABBREVIATIONS)
[uncategorized] ~161-~161: Pontuação duplicada
Context: ...a contagem total de avisos exceder n. --max-warnings 0 falha com qualquer aviso...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~161-~161: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ...ningsExceededda saída JSON étrueepasséfalse. ## Modo estrito --strict...
(ABREVIATIONS_PUNCTUATION)
[uncategorized] ~165-~165: Pontuação duplicada
Context: ...em uma única flag: ele se comporta como --max-warnings 0 para avisos de severidad...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~165-~165: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ...vos acima que, por padrão, nunca afetam pass. O campo strictAdvisoryExceeded da s...
(ABREVIATIONS_PUNCTUATION)
[uncategorized] ~169-~169: Pontuação duplicada
Context: ...archgate adr sync. Para evitar passar --strict` em toda invocação, defina um pad...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~175-~175: Pontuação duplicada
Context: ...n: ```json { "strict": true } ``` Um --strict` explícito na linha de comando se...
(DOUBLE_PUNCTUATION_XML)
docs/src/content/docs/pt-br/reference/cli/review-context.mdx
[uncategorized] ~17-~17: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ... | | --base [ref] | Comparar arquivos alterados co...
(ABREVIATIONS_PUNCTUATION)
[uncategorized] ~17-~17: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ... Comparar arquivos alterados contra uma ref base (auto-detecta quando omitido) ...
(ABREVIATIONS_PUNCTUATION)
[misspelling] ~17-~17: Esta é uma palavra só.
Context: ...arquivos alterados contra uma ref base (auto-detecta quando omitido) ...
(AUTO)
[uncategorized] ~31-~31: Pontuação duplicada
Context: ...visoryExceededreaproveitado étrue. --strict` não falha em violações de re...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~31-~31: Pontuação duplicada
Context: ...ear em violações de regra. Uma falha de --strict imprime o payload JSON completo ...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~33-~33: Pontuação duplicada
Context: ...-stricté resolvido da mesma forma quearchgate check --strict`: flag de linha de comando, depoi...
(DOUBLE_PUNCTUATION_XML)
- Document strict in the configuration reference (docs/reference/configuration.mdx, all 3 languages) — it was missing entirely from the .archgate/config.json schema page. - Document adr sync's --strict config precedence in adr.mdx (all 3 languages), matching the "Strict mode" sections already on check.mdx/review-context.mdx. - Fix imprecise strict-mode wording in check.mdx (all 3 languages): "every warning-shaped diagnostic" -> "rule-severity warning", and clarify that --strict has no --no-strict counterpart, so it can only turn strict mode on over an absent/false config default, never override a configured strict: true. - check.ts now logs a --strict-attributed reason via logWarn() before exiting, matching review-context.ts and adr/sync.ts and ARCH-026's documented pattern. - Update reporter.ts's stale briefingWarnings doc comment to note the strict exception. - Convert tests/commands/adr/sync-strict.test.ts from mock.module() to spyOn() for the first-party registry module, per ARCH-005. Signed-off-by: Rhuan Barreto <rhuan.barreto@gmail.com> Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
|
Addressed all 11 CodeRabbit findings in 56e12a9 (replied on each thread individually):
One finding partially declined with reasoning on its thread: keeping
|
Removes check's --json and --ci boolean flags and replaces them with a single typed --output <format> option (console/json/github/sarif). "ci" is renamed to "github" since it's GitHub Actions annotation syntax specifically, not a generic CI format. --output is additive to --json flags on other commands (adr list/sync/import), which are untouched, and is designed as the extensible pattern for future check output formats. Adds --output sarif: hand-built SARIF 2.1.0 output (src/engine/sarif.ts, zero new dependencies per ARCH-006) so GitHub Code Scanning/Code Quality can ingest check results in CI. Every rule violation becomes a SARIF result; advisory findings (briefing-budget, suppression, unparsed-ADR warnings) are included too as synthetic results under dedicated rule IDs, always at warning level. sarif and github are opt-in only, never auto-detected -- agent-context auto-detect still silently upgrades the default to compact json, unchanged from today. Updates ARCH-003 (Output Formatting) to document --output as the canonical selector, migrates every --json/--ci reference across check.mdx, review-context.mdx, telemetry.mdx, and the CI integration guide (English + pt-br + nb), and migrates all existing tests off the removed flags. BREAKING CHANGE: `archgate check --json` and `archgate check --ci` no longer exist. Use `archgate check --output json` and `archgate check --output github` instead. No other command's flags are affected. Signed-off-by: Rhuan Barreto <rhuan.barreto@gmail.com> Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
|
Added SARIF support for GitHub Code Scanning/Code Quality, in commit ac3edf0 (renumbered after a rebase onto the auto-regenerated This includes an intentional breaking change, scoped to
Migrated every
Example CI usage: - run: archgate check --output sarif > results.sarif
- uses: github/codeql-action/upload-sarif@7188fc363630916deb702c7fdcf4e481b751f97a # v4.37.1
with:
sarif_file: results.sarif |
There was a problem hiding this comment.
Actionable comments posted: 6
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/public/llms-full.txt (1)
4069-4077: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winRegenerate the aggregate documentation for the new
--outputinterface.This table still documents the removed
--jsonand--ciflags instead of--output console|json|github|sarif. The same stale commands remain in the CI guide and examples at Lines 974-975, 1009-1010, 1042-1052, 1152, 1175, 1199, 1220, 1231, 2040-2042, 4141, 4147, 4153, and 4741. Update the source pages and regeneratellms-full.txt; do not manually patch only this generated copy.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/public/llms-full.txt` around lines 4069 - 4077, Update the source documentation for the CLI options and all stale CI-guide/example commands to use the new --output console|json|github|sarif interface instead of --json and --ci, then regenerate the aggregate llms-full.txt documentation. Do not edit only the generated copy; ensure the regenerated table and referenced examples consistently reflect the new interface.docs/src/content/docs/reference/cli/adr.mdx (1)
326-330: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDocument both failure conditions of the combined command.
--check --strictalso fails when an imported ADR is outdated; the current text describes only strict-mode sync errors. State that it fails for upstream updates or unresolved/cloning/matching errors.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/src/content/docs/reference/cli/adr.mdx` around lines 326 - 330, Update the documentation for the combined `archgate adr sync --check --strict` command to state that the build fails both when imported ADRs are outdated due to upstream updates and when imports cannot be resolved, cloned, or matched to a local ADR.docs/src/content/docs/nb/reference/cli/check.mdx (1)
24-24: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winLimit “any warning” to rule warnings.
--strictescalates rule violations withseverity: "warning"plusbriefingWarnings,suppressionWarnings, andunparsedAdrs; it does not make every warning printed bycheckfail the run. This wording conflicts with the later precise explanation and misstates strict-mode behavior.
docs/src/content/docs/nb/reference/cli/check.mdx#L24-L24: say rule warnings, not every warning.docs/src/content/docs/nb/reference/cli/check.mdx#L72-L72: make the example description use the same scope.docs/src/content/docs/pt-br/reference/cli/check.mdx#L24-L24: say rule warnings, not every warning.docs/src/content/docs/pt-br/reference/cli/check.mdx#L72-L72: make the example description use the same scope.Based on learnings: "
check... MUST support a boolean--strictflag that escalates their applicable advisory diagnostics."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/src/content/docs/nb/reference/cli/check.mdx` at line 24, Update the --strict descriptions in docs/src/content/docs/nb/reference/cli/check.mdx lines 24-24 and 72-72, and docs/src/content/docs/pt-br/reference/cli/check.mdx lines 24-24 and 72-72, to state that strict mode escalates rule warnings plus briefingWarnings, suppressionWarnings, and unparsedAdrs—not every warning emitted by check. Keep the wording consistent across both locales and both references.Source: Learnings
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/src/content/docs/guides/ci-integration.mdx`:
- Around line 95-101: Update the SARIF workflow in
docs/src/content/docs/guides/ci-integration.mdx lines 95-101 to capture archgate
check’s exit status without immediately failing the job, run the upload-sarif
step with if: always(), then exit using the captured status. Apply the
equivalent correction in docs/src/content/docs/nb/guides/ci-integration.mdx
lines 94-101, preserving the existing workflow behavior and localized content.
In `@docs/src/content/docs/nb/reference/telemetry.mdx`:
- Line 14: Make the Norwegian telemetry disclosure consistent with
trackCheckResult() by explicitly stating that the selected output-format enum is
collected while other flag values are never sent. Update both affected locations
in docs/src/content/docs/nb/reference/telemetry.mdx:14 and
docs/src/content/docs/nb/reference/telemetry.mdx:68; do not stop collecting
output_format.
In `@docs/src/content/docs/reference/telemetry.mdx`:
- Line 14: Update the telemetry disclosure in
docs/src/content/docs/reference/telemetry.mdx at lines 14-14 and 68-68 to state
that check records the selected --output format, such as json, while never
capturing command output contents; replace the absolute “No flag values” wording
with this exception. Apply the equivalent clarification in Brazilian Portuguese
at docs/src/content/docs/pt-br/reference/telemetry.mdx lines 14-14 and 68-68.
In `@tests/commands/check-action.test.ts`:
- Around line 299-323: Restore process.stdout.isTTY in the finally block of the
test "--output console forces human-readable even under agent auto-detect" after
the temporary override. Capture its original descriptor or value before
Object.defineProperty and reinstate it during cleanup, alongside
restoreEnv("CI", origCI), so subsequent tests retain the original TTY behavior.
In `@tests/integration/check-base.test.ts`:
- Line 93: Update all three per-test timeout overrides in the integration tests
from 30,000ms to at least the mandated 60,000ms floor, preserving the existing
test structure and behavior.
- Around line 53-68: Extract the duplicated CROSS-001/CROSS-002 rule-definition
string used by the tests into a shared module-level constant, following the
existing WARNING_RULE pattern in check-max-warnings.test.ts. Replace both inline
rule strings with that constant while preserving their identical behavior.
---
Outside diff comments:
In `@docs/public/llms-full.txt`:
- Around line 4069-4077: Update the source documentation for the CLI options and
all stale CI-guide/example commands to use the new --output
console|json|github|sarif interface instead of --json and --ci, then regenerate
the aggregate llms-full.txt documentation. Do not edit only the generated copy;
ensure the regenerated table and referenced examples consistently reflect the
new interface.
In `@docs/src/content/docs/nb/reference/cli/check.mdx`:
- Line 24: Update the --strict descriptions in
docs/src/content/docs/nb/reference/cli/check.mdx lines 24-24 and 72-72, and
docs/src/content/docs/pt-br/reference/cli/check.mdx lines 24-24 and 72-72, to
state that strict mode escalates rule warnings plus briefingWarnings,
suppressionWarnings, and unparsedAdrs—not every warning emitted by check. Keep
the wording consistent across both locales and both references.
In `@docs/src/content/docs/reference/cli/adr.mdx`:
- Around line 326-330: Update the documentation for the combined `archgate adr
sync --check --strict` command to state that the build fails both when imported
ADRs are outdated due to upstream updates and when imports cannot be resolved,
cloned, or matched to a local ADR.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 3cf3429b-e15d-4707-bfc0-de3bc7a1f1f6
📒 Files selected for processing (34)
.archgate/adrs/ARCH-003-output-formatting.md.claude/agent-memory/archgate-developer/MEMORY.mddocs/public/llms-full.txtdocs/src/content/docs/guides/ci-integration.mdxdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/nb/reference/cli/adr.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/nb/reference/cli/review-context.mdxdocs/src/content/docs/nb/reference/configuration.mdxdocs/src/content/docs/nb/reference/telemetry.mdxdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/pt-br/reference/cli/adr.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/pt-br/reference/cli/review-context.mdxdocs/src/content/docs/pt-br/reference/configuration.mdxdocs/src/content/docs/pt-br/reference/telemetry.mdxdocs/src/content/docs/reference/cli/adr.mdxdocs/src/content/docs/reference/cli/check.mdxdocs/src/content/docs/reference/cli/review-context.mdxdocs/src/content/docs/reference/configuration.mdxdocs/src/content/docs/reference/telemetry.mdxsrc/commands/check.tssrc/engine/reporter.tssrc/engine/sarif.tssrc/helpers/telemetry.tstests/commands/adr/sync-strict.test.tstests/commands/check-action.test.tstests/commands/check.test.tstests/engine/sarif.test.tstests/integration/check-base.test.tstests/integration/check-max-warnings.test.tstests/integration/check-sarif.test.tstests/integration/check-strict.test.tstests/integration/check.test.ts
- --strict is now the single escalation switch: any rule-severity warning fails the run (warningsExceeded), and advisory findings fail via strictAdvisoryExceeded — no threshold flag to compose with - the zero-rules early return now collects corpus-wide advisory diagnostics (briefing budget, unparsed ADRs) and reports through the standard reporters in every --output format, so a prose-only or fully-unparseable ADR corpus can no longer pass --strict silently - drop the dead BuildReviewContextOptions.maxWarnings plumbing - SARIF CI docs: the upload-sarif step needs if: always() (check exits 1 on findings) and the security-events: write permission — examples fixed in en/pt-br/nb for check.mdx and ci-integration.mdx - ARCH-026 amended: flag removal, the corpus-scoped-advisories invariant for every check exit path, and updated alternatives BREAKING CHANGE: `archgate check --max-warnings <n>` no longer exists. Use `archgate check --strict` to fail on any warning; a tolerate-up-to-N warning budget is no longer offered. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
rhuanbarreto
changed the title
|
Round 3 — review follow-ups (
|
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/src/content/docs/nb/reference/cli/check.mdx (1)
154-154: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDocument the actual JSON fields for operational diagnostics.
Those diagnostics are emitted as top-level
briefingWarnings,suppressionWarnings, andunparsedAdrsin JSON output, not as ruleviolationsentries with"severity": "warning". Update the Norwegian page at line 154 to describe the real JSON shape.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/src/content/docs/nb/reference/cli/check.mdx` at line 154, Update the Norwegian CLI documentation sentence near the JSON-output description to state that operational diagnostics appear as top-level briefingWarnings, suppressionWarnings, and unparsedAdrs fields. Remove the incorrect claim that they are violations entries with severity "warning", while preserving the statement that they do not affect the exit code.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/src/content/docs/guides/ci-integration.mdx`:
- Around line 95-96: Add contents: read alongside security-events: write in the
permissions block of docs/src/content/docs/guides/ci-integration.mdx (lines
95-96), docs/src/content/docs/nb/guides/ci-integration.mdx (lines 95-96), and
docs/src/content/docs/pt-br/guides/ci-integration.mdx (lines 95-96) so the
copied SARIF workflows retain repository read access for actions/checkout.
In `@docs/src/content/docs/nb/reference/cli/check.mdx`:
- Line 23: Update the --strict option description in the CLI reference table to
say “enhver regelbasert advarsel” instead of “enhver advarsel,” while preserving
the existing summary-budget, suppression, and uninterpreted-ADR examples and the
link to strict mode.
- Around line 186-188: Correct the Bokmål prose in the strict-mode paragraph
around the --strict description: replace the incorrect forms “mislykker bygget”
and “ikke er tom”, remove the duplicated “som som”, and use grammatically
correct wording for “et sammendragsbudsjett-overskridelse”. Preserve the
documented strict-mode behavior and JSON field names.
In `@src/commands/check.ts`:
- Around line 86-94: Update the zero-rule path in the check command to collect
and include suppression diagnostics in emptyResult before calling buildSummary.
Ensure strict mode evaluates suppressionWarnings even when no rule ADR loads,
while preserving the existing briefingWarnings and unparsedAdrs fields.
---
Outside diff comments:
In `@docs/src/content/docs/nb/reference/cli/check.mdx`:
- Line 154: Update the Norwegian CLI documentation sentence near the JSON-output
description to state that operational diagnostics appear as top-level
briefingWarnings, suppressionWarnings, and unparsedAdrs fields. Remove the
incorrect claim that they are violations entries with severity "warning", while
preserving the statement that they do not affect the exit code.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: d78ae8bf-d514-44b5-8fee-aba5a2bba085
📒 Files selected for processing (18)
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.mddocs/src/content/docs/guides/ci-integration.mdxdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdxsrc/commands/check.tssrc/commands/review-context.tssrc/engine/context.tssrc/engine/reporter.tssrc/helpers/telemetry.tstests/commands/check-action.test.tstests/engine/reporter-strict.test.tstests/engine/reporter.test.tstests/helpers/telemetry.test.tstests/integration/check-max-warnings.test.tstests/integration/check-strict.test.ts
💤 Files with no reviewable changes (4)
- src/helpers/telemetry.ts
- tests/integration/check-max-warnings.test.ts
- src/engine/context.ts
- tests/helpers/telemetry.test.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (1)
- GitHub Check: Cloudflare Pages
🧰 Additional context used
📓 Path-based instructions (28)
tests/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
In test files, use
_resetPlatformCache()to simulate different platforms instead of mocking or mutatingprocess.platformdirectly.
tests/**/*.ts: Use Bun's built-inbun testrunner for all tests; test files use Bun's Jest-compatible API and native TypeScript execution.
Restore every captured environment variable withrestoreEnv(key, original)rather than assigningundefinedor a captured value directly.
New source files must have corresponding test files, and total line coverage must remain at or above 90%, enforced in CI.
Files:
tests/engine/reporter.test.tstests/engine/reporter-strict.test.tstests/commands/check-action.test.tstests/integration/check-strict.test.ts
{src,tests}/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/LEGAL-001-spdx-license-headers.md)
{src,tests}/**/*.ts: Every TypeScript source file insrc/andtests/must begin with// SPDX-License-Identifier: Apache-2.0followed by// Copyright 2026 Archgate.
If a TypeScript file has a shebang line (for example#!/usr/bin/env buninsrc/cli.ts), the SPDX license header must appear immediately after the shebang.
Use single-line//comments for the SPDX header; do not use block comments (/* */) or alternate license identifiers.
Files:
tests/engine/reporter.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/commands/check-action.test.tstests/integration/check-strict.test.tssrc/commands/check.tssrc/engine/reporter.ts
tests/**/*.test.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-005-testing-standards.md)
tests/**/*.test.ts: Name test files<module-name>.test.tsand mirror thesrc/directory structure, such assrc/engine/runner.ts→tests/engine/runner.test.ts.
Use isolatedmkdtempdirectories for filesystem tests and remove them inafterEachorafterAll.
Test each module's public interface with descriptive behavior-oriented names; do not test private internals.
Mockos.homedir()rather thanHOME; environment overrides are valid only for code that readsBun.envat call time.
Close external SDK servers, clients, and transports withawait ...close()inafterEachorafterAll, managing their lifecycle in hooks.
Configuregit config user.emailanduser.namelocally immediately aftergit initand before any commit in temporary repositories.
Every runnable test must contain at least oneexpect()assertion; use explicit no-throw assertions and usetest.skiportest.todofor placeholders.
Mock HTTP requests by assigningglobalThis.fetch, and restore the mock inafterEach; do not mocknode:fetch.
Do not make network requests in unit tests.
Mock first-party modules withimport * as modandspyOn(mod, "fn"), restoring mocks after each test; reservemock.module()for third-party modules.
Wrap inlinespyOnormockImplementationusage intry/finallysomockRestore()always runs, or manage the spy in hooks.
SetBun.env.NODE_ENV = "test"before initializing Sentry, and never write tests to real user-scope paths; mock the writer oros.homedir()instead.
Inject small production thresholds in threshold tests, such asfileWarnThreshold: 5, instead of generating large fixtures.
Per-test timeout overrides must not be shorter than the globalbun test --timeout 60000setting.
Do not usenode:test; import the testing API frombun:test.
tests/**/*.test.ts: Usetest.each()when the same assertion logic runs against multiple independent inputs, so each case is independently named and reported.
Usedescribe.each()when...
Files:
tests/engine/reporter.test.tstests/engine/reporter-strict.test.tstests/commands/check-action.test.tstests/integration/check-strict.test.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-006-dependency-policy.md)
**/*.{ts,tsx}: Prefer Bun built-ins for file I/O, HTTP, globbing, testing, and subprocess execution; prefernode:built-in modules over npm alternatives when appropriate.
UseBun.spawnwith array-based arguments for all subprocess execution; do not useBun.$because it can hang on Windows.
Do not add npm packages for functionality already provided by Bun, such asglob,chalk, or utility libraries used for a single function.
Use Bun APIs such asBun.file()instead of Node.js-specific APIs such asfs.readFile()when Bun provides an equivalent.
Use relative imports with Bun's native module resolution; do not use TypeScript path aliases.
**/*.{ts,tsx}: Use TypeScript strict mode with ESNext and ES modules.
Prefer minimal dependencies and Bun built-ins where appropriate.
Files:
tests/engine/reporter.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/commands/check-action.test.tstests/integration/check-strict.test.tssrc/commands/check.tssrc/engine/reporter.ts
**/*.{rules.ts,ts}
📄 CodeRabbit inference engine (.archgate/adrs/LEGAL-002-dependency-license-compatibility.md)
Newly encountered permissive licenses may be added to the LEGAL-002 allowlist in the rule implementation, with a comment explaining any override for packages whose package.json lacks a license field.
Files:
tests/engine/reporter.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/commands/check-action.test.tstests/integration/check-strict.test.tssrc/commands/check.tssrc/engine/reporter.ts
**/*.test.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Tests should mirror the
src/structure, with fixtures located undertests/fixtures/.
Files:
tests/engine/reporter.test.tstests/engine/reporter-strict.test.tstests/commands/check-action.test.tstests/integration/check-strict.test.ts
**/*
📄 CodeRabbit inference engine (CLAUDE.md)
Run
bun run validatesuccessfully before considering any task complete; it performs linting, typechecking, formatting checks, tests, ADR checks, dead-export detection, and build checks.
Files:
tests/engine/reporter.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tsdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/guides/ci-integration.mdxtests/commands/check-action.test.tstests/integration/check-strict.test.tsdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/nb/reference/cli/check.mdxsrc/commands/check.tssrc/engine/reporter.tsdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdx
**
⚙️ CodeRabbit configuration file
**: This project uses Archgate — an AI governance framework based on
Architecture Decision Records (ADRs). The ADRs in.archgate/adrs/
are the authoritative rules for this codebase. Each ADR has a companion
.rules.tsfile with automated checks that run viaarchgate check.When reviewing, you must:
- Treat ADR violations as blocking issues, not suggestions.
- Cite the specific ADR ID when flagging a violation (e.g., "Violates ARCH-006").
- Focus on semantic and contextual violations that automated rules cannot catch —
the.rules.tsfiles already cover syntactic/structural patterns.- If you are unsure whether something violates an ADR, flag it as a question
rather than approving it.
Files:
tests/engine/reporter.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tsdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/guides/ci-integration.mdxtests/commands/check-action.test.tstests/integration/check-strict.test.tsdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/nb/reference/cli/check.mdxsrc/commands/check.tssrc/engine/reporter.tsdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdx
src/**/!(*platform).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
src/**/!(*platform).ts: Insrc/TypeScript source files, do not readprocess.platformdirectly; usesrc/helpers/platform.ts(isWindows(),isMacOS(),isLinux(),isWSL(),getPlatformInfo()) for all platform detection.
Use the centralized platform helper instead of duplicating OS/WSL detection logic inline anywhere insrc/TypeScript source.
When behavior differs between Linux and Windows, account for WSL by usingisWSL()rather than assuming `
Files:
src/commands/review-context.tssrc/commands/check.tssrc/engine/reporter.ts
src/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-010-prefer-bun-built-in-json-parsing.md)
src/**/*.ts: Useawait Bun.file(path).json()when reading JSON files in Bun TypeScript source code; do not useJSON.parse(await Bun.file(path).text())orJSON.parse(fs.readFileSync(path, "utf-8"))for file reads.
UseBun.JSONC.parse()when reading files that may contain comments, such astsconfig.json, instead of plainJSON.parse()on file contents.
ReserveJSON.parse()for parsing JSON strings from non-file sources such as API responses or string variables; do not use it as the default for reading JSON files.
src/**/*.ts: Use exit codes 0 for success, 1 for expected failures, 2 for internal errors, and 130 for user cancellation; do not use other exit codes.
UselogError()fromsrc/helpers/log.tsfor user-facing errors; write errors to stderr, not stdout, and avoid directconsole.error()calls.
Provide actionable suggestions in user-facing error messages whenever possible.
Do not show stack traces for user-triggered errors; unexpected errors may include stack traces only whenDEBUGorTRACEis set.
Do not catch and swallow unexpected errors; caught errors must be logged or re-thrown.
Do not exit with code 0 when an operation fails; expected failures must use exit code 1.
Fall back toprocess.cwd()whenfindProjectRoot()returns null in commands that do not require.archgate/.
Handle Inquirer'sExitPromptErrorat the top-level error boundary as user cancellation: exit with code 130, do not log an error, and do not send it to Sentry.
Do not sendUserErroror user-cancellationExitPromptErrorinstances to Sentry from any error handler, includingbeforeSend.
UseexitWith()rather than bareprocess.exit()when terminating after command execution so telemetry and Sentry data are flushed.
src/**/*.ts: In TypeScript source files undersrc/, do not create barrel files: anindex.tscontaining onlyexport,export type, orimport typestatements and no executable logic is forbidden.index.tsfiles containing real log...
Files:
src/commands/review-context.tssrc/commands/check.tssrc/engine/reporter.ts
src/commands/!(index).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-001-command-structure.md)
Each top-level command module under
src/commands/must define exactly one command and export aregister*Command(program)function.
Files:
src/commands/review-context.tssrc/commands/check.ts
src/commands/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-001-command-structure.md)
src/commands/**/*.ts: Command files must remain thin: parse arguments, call engine or helper functions, and format output; business logic must reside insrc/engine/,src/helpers/, orsrc/formats/.
Commands must execute in-process and must not spawn child processes for subcommand execution.
Command modules must not call.parse(); command parsing is handled by the CLI entry point.
src/commands/**/*.ts: In Commander.js command files, options requiring type narrowing beyond plain strings MUST usenew Option()from@commander-js/extra-typingsand register it with.addOption(), rather than using.option().
Use.choices([... ] as const)for options accepting a fixed set of values, and do not add manual validation or unsafe casts for those choices.
Use.argParser((value) => ...)on anOptionfor options requiring type conversion; do not pass parser functions such asparseIntas the third argument to.option().
Useas constfor.choices()arrays and.default()values to preserve literal types.
Reuse existing type definitions for type-level usage, access narrowed options directly, and avoid casts such asopts.editor as SomeType.
src/commands/**/*.ts: All commands that operate on.archgate/project resources must use the sharedfindProjectRoot()fromsrc/helpers/paths.ts; directprocess.cwd()project-root resolution is prohibited except ininit.
Commands that require a project must userequireProjectRoot()fromsrc/helpers/paths.tsinstead of implementing their own missing-project guard. Commands that can operate without a project may usefindProjectRoot()and handlenullthemselves.
When usingfindProjectRoot()directly, check for anullresult and provide a helpful error before exiting.
Pass the resolvedprojectRoottoprojectPaths()when constructing derived project paths.
Do not define localfindProjectRoot()variants; use the shared implementation fromsrc/helpers/paths.ts.
src/commands/**/*.ts: Ev...
Files:
src/commands/review-context.tssrc/commands/check.ts
src/{commands/check.ts,commands/review-context.ts,commands/adr/sync.ts}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
src/{commands/check.ts,commands/review-context.ts,commands/adr/sync.ts}:check,review-context, andadr syncMUST support a boolean--strictflag that escalates their applicable advisory diagnostics into exit code 1.
Print the complete result payload before exiting non-zero because of strict mode.
Before a strict-mode failure, log a clearlogWarn()message attributing the failure to the relevant findings.
Do not add a--no-strictnegation flag.
Advisory findings must remain in the output payload when strict mode is disabled; strict mode changes pass/fail and exit behavior only.
Files:
src/commands/review-context.tssrc/commands/check.ts
src/{commands/check.ts,commands/review-context.ts,commands/adr/sync.ts,helpers/project-config.ts}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
Resolve strict mode as
opts.strict ?? getConfiguredStrict(projectRoot) ?? false, giving the CLI flag precedence over.archgate/config.json, with a default offalse.
Files:
src/commands/review-context.tssrc/commands/check.ts
src/commands/review-context.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
review-context --strictmust fail for truncated briefings and, with--run-checks, strict advisory or warning exceedance; it must not gate oncheckSummary.failedorruleErrors.
Files:
src/commands/review-context.ts
docs/**/*.{mdx,astro,ts,mjs,json}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
The documentation site must be an Astro 5/Starlight project under
docs/, separate from the CLI project with its own package manifest, TypeScript configuration, lockfile, and build pipeline.
Files:
docs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/guides/ci-integration.mdxdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdx
docs/src/content/docs/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
docs/src/content/docs/**/*.mdx: Use MDX format for all documentation content pages underdocs/src/content/docs/.
Organize content under the five category prefixes:getting-started/,concepts/,guides/,reference/, andexamples/.
Every content page must includetitleanddescriptionfrontmatter.
Escape literal curly braces in MDX, such asadr://\{id\}; do not use bare{}in prose or code labels.
Keep reference pages accurate to the CLI source code and update them in the same change that modifies a corresponding CLI API.
docs/src/content/docs/**/*.mdx: Maintain 1:1 parity between root MDX pages and each configured locale: every root file must have a translation at the same relative path, and locale files must not be orphaned.
When English documentation is added or modified, update the corresponding Portuguese and Norwegian locale files in the same pull request.
Translate user-facing prose, headings, titles, descriptions, table text, admonitions, and Starlight component text props; keep code blocks, commands, paths, identifiers, technical terms, imports, component names, and link/href/slug values in English.
Preserve MDX structure, component imports, curly-brace escaping, and internal link paths; internal links must not contain locale prefixes such as/pt-br/.
Do not restructure the root content directory for translations; locale files must mirror the root content directory's relative paths.
Keep code blocks, CLI commands, file paths, and technical identifiers in English during translation.
Files:
docs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/guides/ci-integration.mdxdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdx
docs/**/*
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
docs/**/*: Do not include the docs build in the CLIvalidatepipeline; docs build failures must not block CLI development or CI.
Do not create content files outsidedocs/src/content/docs/, becausedocsLoader()expects that directory structure.
Install documentation dependencies from withindocs/usingcd docs && bun installor the docs convenience scripts, not from the repository root.
Files:
docs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/guides/ci-integration.mdxdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdx
docs/src/content/docs/nb/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Write Norwegian Bokmål translations, not Nynorsk, using informal
duand correct characters such as æ, ø, and å; do not remove accents or use unreviewed machine translation.
Files:
docs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/nb/reference/cli/check.mdx
docs/src/content/docs/pt-br/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Write Brazilian Portuguese translations with correct diacritical marks, including characters such as ã, ç, é, í, ó, ú, â, ê, ô, and à; do not remove accents or use unreviewed machine translation.
Files:
docs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdx
src/commands/check.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
src/commands/check.ts:checkMUST collect corpus-wide advisory diagnostics on every exit path, including the zero-rules early return, so strict mode cannot omit briefing, suppression, or parse diagnostics.
Do not reintroduce--max-warnings <n>; strict warning escalation is deliberately binary.
Files:
src/commands/check.ts
src/engine/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-002-error-handling.md)
In engine files, use
logInfo()orlogWarn()instead of directconsole.log(),console.warn(), orconsole.info()calls.Do not add unsanctioned subprocess sites or
child_processimports; AST subprocesses belong in the sanctioned AST support path and Git subprocesses belong ingit-files.ts.
src/engine/**/*.ts: In the rules engine, list files by matching glob patterns in memory against the git-tracked file set; do not walk the filesystem for normal listing.
Route new engine file listings throughlistMatchingFilesfor rule-facing sandboxed input ormatchTrackedFilesfor trusted ADR frontmatter patterns.
When the target is a git repository andrespectGitignoreis not false, pass the tracked set fromgetGitTrackedFilesto the matching path.
ShareRunCachesacross rule contexts inrunChecks; cache glob results by pattern and tracked mode and file text by absolute path using promises for in-flight deduplication.
Copy cached glob arrays before returning them to rule code so rule mutations cannot corrupt shared cache values.
Do not cachereadJSONresults because rules receive mutable objects and shared cached objects could leak mutations between rules.
Do not filter filesystem scan results against the tracked set as a substitute for in-memory matching.
Files:
src/engine/reporter.ts
src/{engine/**/*.ts,formats/rules.ts,helpers/rules-shim.ts}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-022-ast-aware-rule-context.md)
Expose exactly one catch-all
RuleContext.ast(path: string, language: AstLanguage, opts?: AstOptions): Promise<AstNode>method supporting TypeScript, JavaScript, Python, and Ruby; do not add per-language AST methods.
Files:
src/engine/reporter.ts
src/engine/reporter.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
src/engine/reporter.ts:buildSummary()andgetExitCode()MUST centrally compute strict advisory pass/fail behavior; callers should consumestrictAdvisoryExceededrather than re-deriving it.
Under strict mode, rule-severity warnings,briefingWarnings,suppressionWarnings, andunparsedAdrsmust cause failure; these advisory diagnostics remain non-blocking by default.
When adding a new advisory-styleReportSummarydiagnostic, include it in thestrictAdvisoryExceededcomputation rather than introducing a parallel escalation condition.
Keepadr syncerrors as its own counter; do not foldresult.errorsintoReportSummaryor the four check advisory categories.
Files:
src/engine/reporter.ts
docs/src/content/docs/pt-br/reference/cli/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
Every English top-level CLI reference page must have a matching pt-br mirror at
docs/src/content/docs/pt-br/reference/cli/<name>.mdx.
Files:
docs/src/content/docs/pt-br/reference/cli/check.mdx
docs/src/content/docs/reference/cli/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
docs/src/content/docs/reference/cli/**/*.mdx: Every.mdxfile underdocs/src/content/docs/reference/cli/, exceptindex.mdx, must correspond to a top-level CLI command, and removed commands must have their orphaned pages deleted.
Document subcommands inline within the parent command's.mdxpage; do not create separate top-level pages such asadr-create.mdxorlogin-status.mdx.
Each top-level CLI reference page should follow the established structure: frontmatter withtitleanddescription, a one-line introduction, applicable subcommand and options tables, examples, and troubleshooting guidance where relevant.
Files:
docs/src/content/docs/reference/cli/check.mdx
{src/commands/*/!(index).ts,src/commands/*/*/index.ts,docs/src/content/docs/reference/cli/*.mdx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
Every direct subcommand represented by
src/commands/<parent>/<sub>.tsorsrc/commands/<parent>/<sub>/index.tsmust have a corresponding heading indocs/src/content/docs/reference/cli/<parent>.mdx, and every heading matchingarchgate <parent> <sub>must correspond to an actual subcommand file. Matching is case-insensitive.
Files:
docs/src/content/docs/reference/cli/check.mdx
docs/src/content/docs/reference/cli/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
Document subcommands using a heading containing the exact command text
archgate <parent> <sub>; do not use non-standard heading formats.
Files:
docs/src/content/docs/reference/cli/check.mdx
🧠 Learnings (12)
📚 Learning: 2026-07-11T13:03:15.386Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 467
File: .archgate/adrs/ARCH-011-consistent-project-root-resolution.md:0-0
Timestamp: 2026-07-11T13:03:15.386Z
Learning: For Markdown files formatted by oxfmt (especially ADRs), avoid inline code spans that contain escaped backticks, e.g. `\`...\`` inside a single `` `...` `` span. oxfmt may mis-parse these and, on re-format, can collapse spaces after later inline code spans on the same line, effectively removing any manually re-added spacing. Instead, rephrase the text so the message stays plain quoted text, and put any embedded command/fragment that needs code formatting (e.g., `archgate init`) in its own separate inline code span; keep surrounding punctuation/spacing outside the code span.
Applied to files:
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
📚 Learning: 2026-07-25T16:24:51.133Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-003-output-formatting.md:0-0
Timestamp: 2026-07-25T16:24:51.133Z
Learning: In Archgate ADRs (.archgate/adrs/*.md), omit quantitative claims (e.g., token savings, benchmarks, performance deltas) unless they are backed by a reproducible measurement and supported by a single cited reference. If you cannot satisfy both (reproducible measurement + exactly one cited reference), describe the benefit qualitatively and tie it to the relevant policy/requirements instead of using numeric estimates.
Applied to files:
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
📚 Learning: 2026-07-25T22:03:17.073Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-015-cli-command-documentation-coverage.md:17-18
Timestamp: 2026-07-25T22:03:17.073Z
Learning: When updating an ADR that documents rule discovery/enforcement behavior, ensure the ADR’s stated discovery contract matches the implementation in code. If the rule only discovers commands by scanning `src/commands/*.ts` and `src/commands/*/index.ts`, the ADR must not claim it also inspects command registration calls elsewhere (e.g., `src/cli.ts`). Any ADR language that changes the documented contract should be treated as a normative change to behavior and aligned with the corresponding implementation/issue, not as prose-only documentation compression.
Applied to files:
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
📚 Learning: 2026-07-26T13:09:49.888Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 533
File: .archgate/adrs/ARCH-020-glob-scan-include-dotfiles.md:0-0
Timestamp: 2026-07-26T13:09:49.888Z
Learning: In archgate/cli rule ADRs, `ctx.scopedFiles` is computed from the ADR frontmatter `files` glob patterns before the rule context is constructed. For ARCH-020-style rules, ensure the ADR `files` frontmatter correctly scopes the allowed paths (e.g., `files: ["src/**/*.ts"]`); then rule-specific `.ts`/file filters should assume the incoming file list is already restricted and avoid re-applying the same path-prefix restriction inside individual rules.
Applied to files:
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
📚 Learning: 2026-07-25T00:05:58.884Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: tests/helpers/auth.test.ts:38-46
Timestamp: 2026-07-25T00:05:58.884Z
Learning: When reviewing the Archgate CLI repository’s GEN-004 “concise forward-only narration” comments, don’t rely only on the automated phrase-based narration checks. Those checks can pass even when the comment wording describes historical/transfer semantics rather than current behavior (e.g., saying a prior restore “leaked” a value or a later subprocess “inherited it”). Manually verify that the comment describes the code’s current, forward behavior; flag or adjust comments that imply past/historical state transfer even if GEN-004 enforcement passes.
Applied to files:
tests/engine/reporter.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/commands/check-action.test.tstests/integration/check-strict.test.tssrc/commands/check.tssrc/engine/reporter.ts
📚 Learning: 2026-07-25T00:05:59.109Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: src/cli.ts:0-0
Timestamp: 2026-07-25T00:05:59.109Z
Learning: Code comments may include a concise issue/PR reference (per GEN-004) when it’s used to point readers to fuller rationale instead of inlining that rationale. During review, flag surrounding comment prose that reads like historical context or narrates refactors/relocations; a bare GEN-004-style reference is allowed and should not be flagged by itself.
Applied to files:
tests/engine/reporter.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/commands/check-action.test.tstests/integration/check-strict.test.tssrc/commands/check.tssrc/engine/reporter.ts
📚 Learning: 2026-07-25T15:44:40.668Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-005-testing-standards.md:0-0
Timestamp: 2026-07-25T15:44:40.668Z
Learning: In Archgate CLI test code governed by ARCH-007, only allow `Bun.$` in test suites that are explicitly restricted to a single platform. Any cross-platform test that runs on Linux, macOS, and Windows must avoid `Bun.$` and instead use array-based `Bun.spawn`. For shared git setup used by tests, import and use the `git()` helper from `tests/test-utils.ts` rather than duplicating git setup logic.
Applied to files:
tests/engine/reporter.test.tstests/engine/reporter-strict.test.tstests/commands/check-action.test.tstests/integration/check-strict.test.ts
📚 Learning: 2026-07-25T22:03:14.216Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-002-error-handling.md:0-0
Timestamp: 2026-07-25T22:03:14.216Z
Learning: In Archgate boundary-wrapped CLI command actions (the handlers that rely on `handleCommandError()` for user-facing error output), expected-failure guards should signal user errors by throwing `new UserError(<message/details>)` rather than directly calling `logError()` followed by `exitWith(1)`. This keeps user-facing logging and the exit path centralized in `handleCommandError()`. For normal/computed command outcomes (e.g., `const exitCode = getExitCode(await runChecks(...))`), use `await exitWith(exitCode)` instead of calling `process.exit(exitCode)` so telemetry/Sentry flushing and outcome tagging still run.
Applied to files:
tests/engine/reporter.test.tssrc/commands/review-context.tstests/engine/reporter-strict.test.tstests/commands/check-action.test.tstests/integration/check-strict.test.tssrc/commands/check.tssrc/engine/reporter.ts
📚 Learning: 2026-07-25T23:21:11.504Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 512
File: tests/engine/runner-ast-cache.test.ts:82-82
Timestamp: 2026-07-25T23:21:11.504Z
Learning: For Bun/TS tests under tests/engine, it’s acceptable (per ARCH-025) to validate a runtime-sized collection produced by a single operation by looping over items and making direct assertions like `expect(item).toBe(...)` inside the loop. Treat this as an approved alternative to boolean-collapse assertions such as `expect(items.every(predicate)).toBe(true)`. Do NOT conflate this with prohibited “manual loops” that create independent test cases (e.g., calling `test(...)`/`it(...)` inside a loop); that pattern should still be flagged.
Applied to files:
tests/engine/reporter.test.tstests/engine/reporter-strict.test.ts
📚 Learning: 2026-07-25T23:21:49.190Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 512
File: tests/engine/git-files.test.ts:98-100
Timestamp: 2026-07-25T23:21:49.190Z
Learning: When reviewing archgate/cli for ARCH-006 (per its ADR frontmatter), only enforce the production-dependency policy scoped to package.json. Do not treat test-only refactors or relocated `node:fs` fixture writes as an ARCH-006 violation (since ARCH-006 does not govern test-file I/O API selection). If there’s a broader/test-wide refactor that would migrate fixture writing to `Bun.write()`, evaluate it separately under the appropriate in-scope rule.
Applied to files:
tests/engine/reporter.test.tstests/engine/reporter-strict.test.tstests/commands/check-action.test.tstests/integration/check-strict.test.ts
📚 Learning: 2026-07-25T22:03:22.236Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md:64-67
Timestamp: 2026-07-25T22:03:22.236Z
Learning: When reviewing CLI subcommand documentation, don’t rely solely on the companion ARCH-016 enforcement rule’s limited path coverage (it only checks `src/commands/<parent>/*.ts` and `src/commands/<parent>/*/index.ts`). Manually verify that subcommands documented by convention in deeper paths (e.g., `src/commands/<parent>/**/add.ts` or `src/commands/adr/domain/add.ts`) have the required documentation, since future nested subcommands can drift without automated detection (tracked by ARCH-015 / GitHub `#503`).
Applied to files:
src/commands/review-context.tssrc/commands/check.ts
📚 Learning: 2026-07-15T22:56:35.415Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 476
File: tests/commands/clean.test.ts:61-62
Timestamp: 2026-07-15T22:56:35.415Z
Learning: When reviewing tests that rely on src/helpers/paths.ts `internalPath()`, note that `internalPath()` intentionally reads `Bun.env.HOME ?? Bun.env.USERPROFILE` at call time and only uses `os.homedir()` if neither env var is set. Therefore, don’t suggest changing tests to `spyOn(os, "homedir")` for this behavior; instead, use per-test `Bun.env.HOME` / `Bun.env.USERPROFILE` overrides (as applicable) so the tests control `internalPath()`’s inputs.
Applied to files:
tests/commands/check-action.test.ts
🪛 LanguageTool
docs/src/content/docs/pt-br/reference/cli/check.mdx
[uncategorized] ~19-~19: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ... | | --base [ref] | Comparar arquivos alterados co...
(ABREVIATIONS_PUNCTUATION)
[uncategorized] ~19-~19: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ... Comparar arquivos alterados contra uma ref base (auto-detecta quando omitido) ...
(ABREVIATIONS_PUNCTUATION)
[misspelling] ~19-~19: Esta é uma palavra só.
Context: ...arquivos alterados contra uma ref base (auto-detecta quando omitido) ...
(AUTO)
[uncategorized] ~182-~182: Pontuação duplicada
Context: ... nunca alteram o código de saída. Passe --strict para escalá-los para falhas — ve...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~186-~186: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ...ningsExceededda saída JSON étrueepasséfalse`), e separadamente falha a bu...
(ABREVIATIONS_PUNCTUATION)
[style] ~186-~186: Para conferir mais clareza ao seu texto, prefira mover o advérbio.
Context: ...da JSON é true e pass é false), e separadamente falha a build quando briefingWarnings, `suppr...
(COLOCAÇÃO_ADVÉRBIO)
[uncategorized] ~186-~186: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ...vos acima que, por padrão, nunca afetam pass. O campo strictAdvisoryExceeded da s...
(ABREVIATIONS_PUNCTUATION)
[uncategorized] ~188-~188: Pontuação duplicada
Context: ...pus de ADRs só de prosa ainda falha com --strict diante de um estouro de orçament...
(DOUBLE_PUNCTUATION_XML)
docs/src/content/docs/reference/cli/check.mdx
[uncategorized] ~20-~20: The official name of this software platform is spelled with a capital “H”.
Context: ...ut format: console (default), json, github, or sarif. See [SARIF output](#sarif...
(GITHUB)
🔇 Additional comments (14)
tests/engine/reporter-strict.test.ts (1)
49-157: LGTM!tests/engine/reporter.test.ts (1)
77-104: LGTM!Also applies to: 346-346, 356-370
tests/integration/check-strict.test.ts (1)
137-137: LGTM!Also applies to: 151-192
src/engine/reporter.ts (1)
19-26: LGTM!Also applies to: 36-37, 91-97, 162-196, 302-311, 430-435
src/commands/check.ts (1)
35-78: LGTM!Also applies to: 152-188, 198-219
src/commands/review-context.ts (1)
33-40: LGTM!Also applies to: 57-57, 80-105
docs/src/content/docs/guides/ci-integration.mdx (1)
10-10: LGTM!Also applies to: 45-45, 212-212, 235-235, 259-259, 280-280, 291-291
docs/src/content/docs/nb/guides/ci-integration.mdx (1)
45-45: LGTM!Also applies to: 235-235, 259-259, 280-280, 291-291
docs/src/content/docs/pt-br/guides/ci-integration.mdx (1)
45-45: LGTM!Also applies to: 235-235, 259-259, 280-280, 291-291
docs/src/content/docs/pt-br/reference/cli/check.mdx (1)
16-23: LGTM!Also applies to: 33-37, 65-120, 154-154, 176-198
docs/src/content/docs/reference/cli/check.mdx (1)
16-23: LGTM!Also applies to: 33-37, 65-120, 154-154, 176-198
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md (1)
18-20: LGTM!Also applies to: 31-34, 38-50, 56-70, 76-95, 101-112, 120-122
tests/commands/check-action.test.ts (1)
207-222: LGTM!docs/src/content/docs/nb/reference/cli/check.mdx (1)
33-37: LGTM!Also applies to: 65-68, 80-123, 176-182, 184-185, 190-198
always() also fires for cancelled jobs; success() || failure() covers the pass and violation cases without resurrecting cancelled runs. Applied to check.mdx and ci-integration.mdx in en/pt-br/nb. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
- telemetry docs (en/pt-br/nb): disclose that --output's selected format (a fixed enum) is recorded, replacing the absolute 'no flag values' claim - ci-integration docs (en/pt-br/nb): add contents: read to the SARIF workflow permissions block (declaring any permission resets the rest to none, breaking checkout) - check docs (en/pt-br/nb): --strict option table says rule-severity warning, matching the CLI description and ARCH-026's exclusion of operational logWarn() sites; nb Bokmål grammar fixes in the strict-mode prose - ARCH-026 + docs: scope the every-exit-path collection contract to the ADR-corpus diagnostics (briefing budget, unparsed ADRs) — suppression warnings derive from rule violations and cannot exist when no rules run - check-base.test.ts: extract the duplicated cross-file rule into CROSS_FILE_RULE; raise per-test timeouts to the 60s floor Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md:
- Around line 44-48: The per-command failure semantics in ARCH-026 must
explicitly apply only when --strict is enabled. Update the “Per-command
semantics” heading or each relevant failure statement for check, review-context,
and adr sync to distinguish strict-mode exit failures from default advisory
behavior, while preserving the existing conditions and non-strict outcomes.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 363d9477-b2d0-48ed-9c26-1fd9a4d6ca6a
📒 Files selected for processing (11)
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.mddocs/src/content/docs/guides/ci-integration.mdxdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/nb/reference/telemetry.mdxdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/pt-br/reference/telemetry.mdxdocs/src/content/docs/reference/cli/check.mdxdocs/src/content/docs/reference/telemetry.mdxtests/integration/check-base.test.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: Analyze (java-kotlin)
- GitHub Check: Cloudflare Pages
🧰 Additional context used
📓 Path-based instructions (17)
docs/**/*.{mdx,astro,ts,mjs,json}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
The documentation site must be an Astro 5/Starlight project under
docs/, separate from the CLI project with its own package manifest, TypeScript configuration, lockfile, and build pipeline.
Files:
docs/src/content/docs/reference/telemetry.mdxdocs/src/content/docs/pt-br/reference/telemetry.mdxdocs/src/content/docs/nb/reference/telemetry.mdxdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/guides/ci-integration.mdxdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdx
docs/src/content/docs/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
docs/src/content/docs/**/*.mdx: Use MDX format for all documentation content pages underdocs/src/content/docs/.
Organize content under the five category prefixes:getting-started/,concepts/,guides/,reference/, andexamples/.
Every content page must includetitleanddescriptionfrontmatter.
Escape literal curly braces in MDX, such asadr://\{id\}; do not use bare{}in prose or code labels.
Keep reference pages accurate to the CLI source code and update them in the same change that modifies a corresponding CLI API.
docs/src/content/docs/**/*.mdx: Maintain 1:1 parity between root MDX pages and each configured locale: every root file must have a translation at the same relative path, and locale files must not be orphaned.
When English documentation is added or modified, update the corresponding Portuguese and Norwegian locale files in the same pull request.
Translate user-facing prose, headings, titles, descriptions, table text, admonitions, and Starlight component text props; keep code blocks, commands, paths, identifiers, technical terms, imports, component names, and link/href/slug values in English.
Preserve MDX structure, component imports, curly-brace escaping, and internal link paths; internal links must not contain locale prefixes such as/pt-br/.
Do not restructure the root content directory for translations; locale files must mirror the root content directory's relative paths.
Keep code blocks, CLI commands, file paths, and technical identifiers in English during translation.
Files:
docs/src/content/docs/reference/telemetry.mdxdocs/src/content/docs/pt-br/reference/telemetry.mdxdocs/src/content/docs/nb/reference/telemetry.mdxdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/guides/ci-integration.mdxdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdx
docs/**/*
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
docs/**/*: Do not include the docs build in the CLIvalidatepipeline; docs build failures must not block CLI development or CI.
Do not create content files outsidedocs/src/content/docs/, becausedocsLoader()expects that directory structure.
Install documentation dependencies from withindocs/usingcd docs && bun installor the docs convenience scripts, not from the repository root.
Files:
docs/src/content/docs/reference/telemetry.mdxdocs/src/content/docs/pt-br/reference/telemetry.mdxdocs/src/content/docs/nb/reference/telemetry.mdxdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/guides/ci-integration.mdxdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdx
**/*
📄 CodeRabbit inference engine (CLAUDE.md)
Run
bun run validatesuccessfully before considering any task complete; it performs linting, typechecking, formatting checks, tests, ADR checks, dead-export detection, and build checks.
Files:
docs/src/content/docs/reference/telemetry.mdxdocs/src/content/docs/pt-br/reference/telemetry.mdxdocs/src/content/docs/nb/reference/telemetry.mdxdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/guides/ci-integration.mdxtests/integration/check-base.test.tsdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdx
**
⚙️ CodeRabbit configuration file
**: This project uses Archgate — an AI governance framework based on
Architecture Decision Records (ADRs). The ADRs in.archgate/adrs/
are the authoritative rules for this codebase. Each ADR has a companion
.rules.tsfile with automated checks that run viaarchgate check.When reviewing, you must:
- Treat ADR violations as blocking issues, not suggestions.
- Cite the specific ADR ID when flagging a violation (e.g., "Violates ARCH-006").
- Focus on semantic and contextual violations that automated rules cannot catch —
the.rules.tsfiles already cover syntactic/structural patterns.- If you are unsure whether something violates an ADR, flag it as a question
rather than approving it.
Files:
docs/src/content/docs/reference/telemetry.mdxdocs/src/content/docs/pt-br/reference/telemetry.mdxdocs/src/content/docs/nb/reference/telemetry.mdxdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/guides/ci-integration.mdxtests/integration/check-base.test.tsdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdxdocs/src/content/docs/nb/reference/cli/check.mdxdocs/src/content/docs/reference/cli/check.mdx
docs/src/content/docs/pt-br/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Write Brazilian Portuguese translations with correct diacritical marks, including characters such as ã, ç, é, í, ó, ú, â, ê, ô, and à; do not remove accents or use unreviewed machine translation.
Files:
docs/src/content/docs/pt-br/reference/telemetry.mdxdocs/src/content/docs/pt-br/guides/ci-integration.mdxdocs/src/content/docs/pt-br/reference/cli/check.mdx
docs/src/content/docs/nb/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Write Norwegian Bokmål translations, not Nynorsk, using informal
duand correct characters such as æ, ø, and å; do not remove accents or use unreviewed machine translation.
Files:
docs/src/content/docs/nb/reference/telemetry.mdxdocs/src/content/docs/nb/guides/ci-integration.mdxdocs/src/content/docs/nb/reference/cli/check.mdx
tests/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
In test files, use
_resetPlatformCache()to simulate different platforms instead of mocking or mutatingprocess.platformdirectly.
tests/**/*.ts: Use Bun's built-inbun testrunner for all tests; test files use Bun's Jest-compatible API and native TypeScript execution.
Restore every captured environment variable withrestoreEnv(key, original)rather than assigningundefinedor a captured value directly.
New source files must have corresponding test files, and total line coverage must remain at or above 90%, enforced in CI.
Files:
tests/integration/check-base.test.ts
{src,tests}/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/LEGAL-001-spdx-license-headers.md)
{src,tests}/**/*.ts: Every TypeScript source file insrc/andtests/must begin with// SPDX-License-Identifier: Apache-2.0followed by// Copyright 2026 Archgate.
If a TypeScript file has a shebang line (for example#!/usr/bin/env buninsrc/cli.ts), the SPDX license header must appear immediately after the shebang.
Use single-line//comments for the SPDX header; do not use block comments (/* */) or alternate license identifiers.
Files:
tests/integration/check-base.test.ts
tests/**/*.test.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-005-testing-standards.md)
tests/**/*.test.ts: Name test files<module-name>.test.tsand mirror thesrc/directory structure, such assrc/engine/runner.ts→tests/engine/runner.test.ts.
Use isolatedmkdtempdirectories for filesystem tests and remove them inafterEachorafterAll.
Test each module's public interface with descriptive behavior-oriented names; do not test private internals.
Mockos.homedir()rather thanHOME; environment overrides are valid only for code that readsBun.envat call time.
Close external SDK servers, clients, and transports withawait ...close()inafterEachorafterAll, managing their lifecycle in hooks.
Configuregit config user.emailanduser.namelocally immediately aftergit initand before any commit in temporary repositories.
Every runnable test must contain at least oneexpect()assertion; use explicit no-throw assertions and usetest.skiportest.todofor placeholders.
Mock HTTP requests by assigningglobalThis.fetch, and restore the mock inafterEach; do not mocknode:fetch.
Do not make network requests in unit tests.
Mock first-party modules withimport * as modandspyOn(mod, "fn"), restoring mocks after each test; reservemock.module()for third-party modules.
Wrap inlinespyOnormockImplementationusage intry/finallysomockRestore()always runs, or manage the spy in hooks.
SetBun.env.NODE_ENV = "test"before initializing Sentry, and never write tests to real user-scope paths; mock the writer oros.homedir()instead.
Inject small production thresholds in threshold tests, such asfileWarnThreshold: 5, instead of generating large fixtures.
Per-test timeout overrides must not be shorter than the globalbun test --timeout 60000setting.
Do not usenode:test; import the testing API frombun:test.
tests/**/*.test.ts: Usetest.each()when the same assertion logic runs against multiple independent inputs, so each case is independently named and reported.
Usedescribe.each()when...
Files:
tests/integration/check-base.test.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-006-dependency-policy.md)
**/*.{ts,tsx}: Prefer Bun built-ins for file I/O, HTTP, globbing, testing, and subprocess execution; prefernode:built-in modules over npm alternatives when appropriate.
UseBun.spawnwith array-based arguments for all subprocess execution; do not useBun.$because it can hang on Windows.
Do not add npm packages for functionality already provided by Bun, such asglob,chalk, or utility libraries used for a single function.
Use Bun APIs such asBun.file()instead of Node.js-specific APIs such asfs.readFile()when Bun provides an equivalent.
Use relative imports with Bun's native module resolution; do not use TypeScript path aliases.
**/*.{ts,tsx}: Use TypeScript strict mode with ESNext and ES modules.
Prefer minimal dependencies and Bun built-ins where appropriate.
Files:
tests/integration/check-base.test.ts
**/*.{rules.ts,ts}
📄 CodeRabbit inference engine (.archgate/adrs/LEGAL-002-dependency-license-compatibility.md)
Newly encountered permissive licenses may be added to the LEGAL-002 allowlist in the rule implementation, with a comment explaining any override for packages whose package.json lacks a license field.
Files:
tests/integration/check-base.test.ts
**/*.test.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Tests should mirror the
src/structure, with fixtures located undertests/fixtures/.
Files:
tests/integration/check-base.test.ts
docs/src/content/docs/pt-br/reference/cli/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
Every English top-level CLI reference page must have a matching pt-br mirror at
docs/src/content/docs/pt-br/reference/cli/<name>.mdx.
Files:
docs/src/content/docs/pt-br/reference/cli/check.mdx
docs/src/content/docs/reference/cli/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
docs/src/content/docs/reference/cli/**/*.mdx: Every.mdxfile underdocs/src/content/docs/reference/cli/, exceptindex.mdx, must correspond to a top-level CLI command, and removed commands must have their orphaned pages deleted.
Document subcommands inline within the parent command's.mdxpage; do not create separate top-level pages such asadr-create.mdxorlogin-status.mdx.
Each top-level CLI reference page should follow the established structure: frontmatter withtitleanddescription, a one-line introduction, applicable subcommand and options tables, examples, and troubleshooting guidance where relevant.
Files:
docs/src/content/docs/reference/cli/check.mdx
{src/commands/*/!(index).ts,src/commands/*/*/index.ts,docs/src/content/docs/reference/cli/*.mdx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
Every direct subcommand represented by
src/commands/<parent>/<sub>.tsorsrc/commands/<parent>/<sub>/index.tsmust have a corresponding heading indocs/src/content/docs/reference/cli/<parent>.mdx, and every heading matchingarchgate <parent> <sub>must correspond to an actual subcommand file. Matching is case-insensitive.
Files:
docs/src/content/docs/reference/cli/check.mdx
docs/src/content/docs/reference/cli/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
Document subcommands using a heading containing the exact command text
archgate <parent> <sub>; do not use non-standard heading formats.
Files:
docs/src/content/docs/reference/cli/check.mdx
🧠 Learnings (9)
📚 Learning: 2026-07-11T13:03:15.386Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 467
File: .archgate/adrs/ARCH-011-consistent-project-root-resolution.md:0-0
Timestamp: 2026-07-11T13:03:15.386Z
Learning: For Markdown files formatted by oxfmt (especially ADRs), avoid inline code spans that contain escaped backticks, e.g. `\`...\`` inside a single `` `...` `` span. oxfmt may mis-parse these and, on re-format, can collapse spaces after later inline code spans on the same line, effectively removing any manually re-added spacing. Instead, rephrase the text so the message stays plain quoted text, and put any embedded command/fragment that needs code formatting (e.g., `archgate init`) in its own separate inline code span; keep surrounding punctuation/spacing outside the code span.
Applied to files:
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
📚 Learning: 2026-07-25T16:24:51.133Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-003-output-formatting.md:0-0
Timestamp: 2026-07-25T16:24:51.133Z
Learning: In Archgate ADRs (.archgate/adrs/*.md), omit quantitative claims (e.g., token savings, benchmarks, performance deltas) unless they are backed by a reproducible measurement and supported by a single cited reference. If you cannot satisfy both (reproducible measurement + exactly one cited reference), describe the benefit qualitatively and tie it to the relevant policy/requirements instead of using numeric estimates.
Applied to files:
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
📚 Learning: 2026-07-25T22:03:17.073Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-015-cli-command-documentation-coverage.md:17-18
Timestamp: 2026-07-25T22:03:17.073Z
Learning: When updating an ADR that documents rule discovery/enforcement behavior, ensure the ADR’s stated discovery contract matches the implementation in code. If the rule only discovers commands by scanning `src/commands/*.ts` and `src/commands/*/index.ts`, the ADR must not claim it also inspects command registration calls elsewhere (e.g., `src/cli.ts`). Any ADR language that changes the documented contract should be treated as a normative change to behavior and aligned with the corresponding implementation/issue, not as prose-only documentation compression.
Applied to files:
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
📚 Learning: 2026-07-26T13:09:49.888Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 533
File: .archgate/adrs/ARCH-020-glob-scan-include-dotfiles.md:0-0
Timestamp: 2026-07-26T13:09:49.888Z
Learning: In archgate/cli rule ADRs, `ctx.scopedFiles` is computed from the ADR frontmatter `files` glob patterns before the rule context is constructed. For ARCH-020-style rules, ensure the ADR `files` frontmatter correctly scopes the allowed paths (e.g., `files: ["src/**/*.ts"]`); then rule-specific `.ts`/file filters should assume the incoming file list is already restricted and avoid re-applying the same path-prefix restriction inside individual rules.
Applied to files:
.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md
📚 Learning: 2026-07-25T00:05:58.884Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: tests/helpers/auth.test.ts:38-46
Timestamp: 2026-07-25T00:05:58.884Z
Learning: When reviewing the Archgate CLI repository’s GEN-004 “concise forward-only narration” comments, don’t rely only on the automated phrase-based narration checks. Those checks can pass even when the comment wording describes historical/transfer semantics rather than current behavior (e.g., saying a prior restore “leaked” a value or a later subprocess “inherited it”). Manually verify that the comment describes the code’s current, forward behavior; flag or adjust comments that imply past/historical state transfer even if GEN-004 enforcement passes.
Applied to files:
tests/integration/check-base.test.ts
📚 Learning: 2026-07-25T00:05:59.109Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: src/cli.ts:0-0
Timestamp: 2026-07-25T00:05:59.109Z
Learning: Code comments may include a concise issue/PR reference (per GEN-004) when it’s used to point readers to fuller rationale instead of inlining that rationale. During review, flag surrounding comment prose that reads like historical context or narrates refactors/relocations; a bare GEN-004-style reference is allowed and should not be flagged by itself.
Applied to files:
tests/integration/check-base.test.ts
📚 Learning: 2026-07-25T15:44:40.668Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-005-testing-standards.md:0-0
Timestamp: 2026-07-25T15:44:40.668Z
Learning: In Archgate CLI test code governed by ARCH-007, only allow `Bun.$` in test suites that are explicitly restricted to a single platform. Any cross-platform test that runs on Linux, macOS, and Windows must avoid `Bun.$` and instead use array-based `Bun.spawn`. For shared git setup used by tests, import and use the `git()` helper from `tests/test-utils.ts` rather than duplicating git setup logic.
Applied to files:
tests/integration/check-base.test.ts
📚 Learning: 2026-07-25T22:03:14.216Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-002-error-handling.md:0-0
Timestamp: 2026-07-25T22:03:14.216Z
Learning: In Archgate boundary-wrapped CLI command actions (the handlers that rely on `handleCommandError()` for user-facing error output), expected-failure guards should signal user errors by throwing `new UserError(<message/details>)` rather than directly calling `logError()` followed by `exitWith(1)`. This keeps user-facing logging and the exit path centralized in `handleCommandError()`. For normal/computed command outcomes (e.g., `const exitCode = getExitCode(await runChecks(...))`), use `await exitWith(exitCode)` instead of calling `process.exit(exitCode)` so telemetry/Sentry flushing and outcome tagging still run.
Applied to files:
tests/integration/check-base.test.ts
📚 Learning: 2026-07-25T23:21:49.190Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 512
File: tests/engine/git-files.test.ts:98-100
Timestamp: 2026-07-25T23:21:49.190Z
Learning: When reviewing archgate/cli for ARCH-006 (per its ADR frontmatter), only enforce the production-dependency policy scoped to package.json. Do not treat test-only refactors or relocated `node:fs` fixture writes as an ARCH-006 violation (since ARCH-006 does not govern test-file I/O API selection). If there’s a broader/test-wide refactor that would migrate fixture writing to `Bun.write()`, evaluate it separately under the appropriate in-scope rule.
Applied to files:
tests/integration/check-base.test.ts
🪛 LanguageTool
docs/src/content/docs/reference/telemetry.mdx
[uncategorized] ~14-~14: The official name of this software platform is spelled with a capital “H”.
Context: ...at — a fixed choice of console/json/github/sarif — never free-form flag values)...
(GITHUB)
[uncategorized] ~68-~68: The official name of this software platform is spelled with a capital “H”.
Context: ... format (a fixed enum: console/json/github/sarif); we never record user-provide...
(GITHUB)
docs/src/content/docs/pt-br/reference/cli/check.mdx
[uncategorized] ~19-~19: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ... | | --base [ref] | Comparar arquivos alterados co...
(ABREVIATIONS_PUNCTUATION)
[uncategorized] ~19-~19: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ... Comparar arquivos alterados contra uma ref base (auto-detecta quando omitido) ...
(ABREVIATIONS_PUNCTUATION)
[misspelling] ~19-~19: Esta é uma palavra só.
Context: ...arquivos alterados contra uma ref base (auto-detecta quando omitido) ...
(AUTO)
[uncategorized] ~188-~188: Pontuação duplicada
Context: ...pus de ADRs só de prosa ainda falha com --strict diante de um estouro de orçament...
(DOUBLE_PUNCTUATION_XML)
docs/src/content/docs/reference/cli/check.mdx
[uncategorized] ~20-~20: The official name of this software platform is spelled with a capital “H”.
Context: ...ut format: console (default), json, github, or sarif. See [SARIF output](#sarif...
(GITHUB)
🔇 Additional comments (10)
docs/src/content/docs/guides/ci-integration.mdx (1)
45-45: LGTM!Also applies to: 96-110, 236-236, 260-260, 281-281, 292-292
docs/src/content/docs/nb/guides/ci-integration.mdx (1)
45-45: LGTM!Also applies to: 96-110, 236-236, 260-260, 281-281, 292-292
docs/src/content/docs/nb/reference/cli/check.mdx (1)
16-23: LGTM!Also applies to: 114-120, 186-188
docs/src/content/docs/nb/reference/telemetry.mdx (1)
14-14: LGTM!Also applies to: 68-68
docs/src/content/docs/pt-br/guides/ci-integration.mdx (1)
45-45: LGTM!Also applies to: 96-110, 236-236, 260-260, 281-281, 292-292
docs/src/content/docs/pt-br/reference/cli/check.mdx (1)
16-23: LGTM!Also applies to: 114-120, 188-198
docs/src/content/docs/pt-br/reference/telemetry.mdx (1)
14-14: LGTM!Also applies to: 68-68
docs/src/content/docs/reference/cli/check.mdx (1)
16-23: LGTM!Also applies to: 114-120, 188-198
docs/src/content/docs/reference/telemetry.mdx (1)
14-14: LGTM!Also applies to: 68-68
tests/integration/check-base.test.ts (1)
17-32: LGTM!Also applies to: 67-67, 91-91, 109-109, 129-129, 178-178
…ting-matsumoto Signed-off-by: Rhuan Barreto <rhuan@barreto.work> # Conflicts: # .claude/agent-memory/archgate-developer/MEMORY.md # src/commands/check.ts # src/commands/review-context.ts # tests/commands/check-action.test.ts # tests/helpers/telemetry.test.ts # tests/integration/check-max-warnings.test.ts # tests/integration/check.test.ts
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
The per-command bullets read as unconditional failure mandates, contradicting the ADR's own default-advisory model. The heading now scopes them to strict mode; Decision trimmed back under the briefing budget. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (6)
docs/public/llms-full.txt (1)
4253-4279: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winQualify the exit-code guidance for strict mode.
The CI guide still says at Line 1128 that warnings never affect the exit code and only error violations can return 1. With configured or explicit
--strict, rule warnings and selected advisory findings can fail the command; distinguish default behavior from strict behavior there and in duplicate sections.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/public/llms-full.txt` around lines 4253 - 4279, Update the CI exit-code guidance and its duplicate sections to distinguish default behavior from configured or explicit --strict behavior. State that warnings normally do not affect the exit code, while strict mode can fail on rule-severity warnings and the documented advisory findings, and ensure the guidance matches the Strict mode section’s warningsExceeded and strictAdvisoryExceeded behavior.src/commands/check.ts (1)
81-83: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winRemove the historical compatibility narration.
Describe the current defaulting behavior only; “matches the pre-
--output” narrates prior behavior.As per coding guidelines, project-authored comments must “describe current behavior only” and “never narrate history, relocations, refactors, or how the code came to be.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/commands/check.ts` around lines 81 - 83, Update the comment near the output defaulting logic to describe only the current behavior: explicit --output takes precedence, omitted output defaults to console, and agent context auto-selects compact JSON. Remove the historical reference to pre---output behavior.Source: Coding guidelines
src/commands/adr/sync.ts (1)
52-58: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winAwait manifest persistence.
Discarding
Bun.write()allows the command to report success or exit before.archgate/imports.jsonis written. MakesaveImportsManifestasync and await it at its call site so write failures reachhandleCommandError().🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/commands/adr/sync.ts` around lines 52 - 58, Make saveImportsManifest asynchronous and await Bun.write so manifest persistence completes and write failures propagate. Update its call site to await saveImportsManifest before reporting command success, allowing failures to reach handleCommandError().src/engine/reporter.ts (1)
304-320: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winUse the engine logging abstraction for new strict output.
These new direct console calls violate ARCH-003’s engine-output rule.
src/engine/reporter.ts#L304-L320: emit strict console diagnostics throughlogInfo()/logWarn().src/engine/reporter.ts#L406-L410: emit the strict GitHub diagnostic through the approved output abstraction while preserving the annotation payload.As per coding guidelines, engine files must use
logInfo()orlogWarn()instead of directconsole.log()calls.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/engine/reporter.ts` around lines 304 - 320, Replace the direct console.log calls in the strict diagnostics blocks around src/engine/reporter.ts lines 304-320 with the engine logging abstraction, using logInfo() or logWarn() as appropriate while preserving both messages. Also update the strict GitHub diagnostic around src/engine/reporter.ts lines 406-410 to use the approved logging abstraction without changing its annotation payload.Sources: Coding guidelines, Path instructions
tests/commands/review-context.test.ts (1)
223-228: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winAvoid independent assertions in a loop.
Project the domain names and assert the collection directly, or use
test.each()for separate cases; do not run assertions insidefor.As per coding guidelines, “Do not register tests or run independent assertions inside
for/.forEachloops.”🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@tests/commands/review-context.test.ts` around lines 223 - 228, Replace the assertion inside the for loop over domains in the review-context test with a collection-level assertion by projecting each domain’s validated name and comparing the resulting array to the expected values. Preserve the existing domains array validation and expectKeys checks while removing independent assertions from the loop.Source: Coding guidelines
tests/commands/adr/sync.test.ts (1)
32-35: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winUse spies for the first-party registry module.
src/helpers/registryshould be imported as a namespace and haveresolveSource/shallowClonestubbed withspyOn; mock the spies withmockRestore()instead of usingmock.module()for this first-party module.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@tests/commands/adr/sync.test.ts` around lines 32 - 35, Update the registry setup in the sync tests to import the first-party module as a namespace, then stub its resolveSource and shallowClone methods with spyOn. Remove the mock.module override and restore both spies with mockRestore() during test cleanup.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/public/llms-full.txt`:
- Around line 1042-1082: Remove the obsolete `archgate check --json` and
`archgate check --ci` entries from the “Useful flags” documentation section,
replacing them with the current `--output` usage where appropriate. Update the
source documentation that generates this aggregate file, then regenerate
`docs/public/llms-full.txt` so it no longer advertises the removed options.
In `@src/engine/context.ts`:
- Around line 255-258: Update the zero-rule path in the context summary flow
around buildSummary so loadResults.length === 0 does not return EMPTY_SUMMARY
unconditionally. Build that summary using the diagnostics collected by check,
while preserving strict-mode corpus-wide briefing and unparsed-ADR advisories
and the existing behavior when diagnostics are absent.
In `@tests/commands/adr/sync-strict.test.ts`:
- Line 173: Await every rejected-promise assertion in the async tests by adding
the required await to each .rejects expectation. Apply this consistently at
tests/commands/adr/sync-strict.test.ts lines 173, 192, 228, and 266;
tests/commands/adr/sync.test.ts lines 209, 278, 286, and 433; all listed
reject-promise expectations in tests/commands/check-action.test.ts lines
191-193, 208-210, 240-242, 256-258, 267-269, 337-339, 377-379, 387-389, 397-399,
441-443, 505-507, and 518-520; and tests/helpers/project-config.test.ts lines
52-54, 58-60, 64-66, 70-72, 77-79, and 95-97.
---
Outside diff comments:
In `@docs/public/llms-full.txt`:
- Around line 4253-4279: Update the CI exit-code guidance and its duplicate
sections to distinguish default behavior from configured or explicit --strict
behavior. State that warnings normally do not affect the exit code, while strict
mode can fail on rule-severity warnings and the documented advisory findings,
and ensure the guidance matches the Strict mode section’s warningsExceeded and
strictAdvisoryExceeded behavior.
In `@src/commands/adr/sync.ts`:
- Around line 52-58: Make saveImportsManifest asynchronous and await Bun.write
so manifest persistence completes and write failures propagate. Update its call
site to await saveImportsManifest before reporting command success, allowing
failures to reach handleCommandError().
In `@src/commands/check.ts`:
- Around line 81-83: Update the comment near the output defaulting logic to
describe only the current behavior: explicit --output takes precedence, omitted
output defaults to console, and agent context auto-selects compact JSON. Remove
the historical reference to pre---output behavior.
In `@src/engine/reporter.ts`:
- Around line 304-320: Replace the direct console.log calls in the strict
diagnostics blocks around src/engine/reporter.ts lines 304-320 with the engine
logging abstraction, using logInfo() or logWarn() as appropriate while
preserving both messages. Also update the strict GitHub diagnostic around
src/engine/reporter.ts lines 406-410 to use the approved logging abstraction
without changing its annotation payload.
In `@tests/commands/adr/sync.test.ts`:
- Around line 32-35: Update the registry setup in the sync tests to import the
first-party module as a namespace, then stub its resolveSource and shallowClone
methods with spyOn. Remove the mock.module override and restore both spies with
mockRestore() during test cleanup.
In `@tests/commands/review-context.test.ts`:
- Around line 223-228: Replace the assertion inside the for loop over domains in
the review-context test with a collection-level assertion by projecting each
domain’s validated name and comparing the resulting array to the expected
values. Preserve the existing domains array validation and expectKeys checks
while removing independent assertions from the loop.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 82c3b211-be2c-4a2f-b4ea-a10af5e82f4c
📒 Files selected for processing (22)
.claude/agent-memory/archgate-developer/MEMORY.mddocs/public/llms-full.txtsrc/commands/adr/sync.tssrc/commands/check.tssrc/commands/review-context.tssrc/engine/context.tssrc/engine/reporter.tssrc/engine/sarif.tssrc/helpers/project-config.tssrc/helpers/telemetry.tstests/commands/adr/sync-strict.test.tstests/commands/adr/sync.test.tstests/commands/check-action.test.tstests/commands/review-context.test.tstests/engine/reporter-strict.test.tstests/engine/reporter.test.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tstests/integration/check-base.test.tstests/integration/check-sarif.test.tstests/integration/check-strict.test.tstests/integration/check.test.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: Smoke Test (Windows) / Windows
- GitHub Check: Cloudflare Pages
🧰 Additional context used
📓 Path-based instructions (27)
tests/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
In test files, use
_resetPlatformCache()to simulate different platforms instead of mocking or mutatingprocess.platformdirectly.
tests/**/*.ts: Use Bun's built-inbun testrunner for all tests; do not use Jest, Vitest, or custom assertions.
Mirror thesrc/directory structure intests/, and name test files<module-name>.test.ts.
Usemkdtempfor filesystem-test isolation, keep writes inside the temporary directory, and clean up temporary resources inafterEachorafterAll.
Test each module's public interface with descriptive names; do not test private internals.
Every runnable test must contain anexpect()assertion; usetest.skiportest.todofor placeholders and do not leave assertion-less or silently skipped tests.
Restore every captured environment variable withrestoreEnv(key, original)rather than assigning the captured value directly.
Mockos.homedir()via an imported module namespace andspyOn; do not overrideHOMEto control home-directory resolution. Environment overrides are valid only for code that readsBun.envat call time.
Mock first-party modules withimport * as modplusspyOn, restore them withmock.restore(), and never usemock.module()or an-implproduction split for first-party modules.
For HTTP mocking, saveglobalThis.fetchbefore replacing it and restore the direct assignment inafterEach; do not usemock.module("node:fetch").
Tests must not hit the network or touch real user-scope paths or other real state.
Wrap inlinespyOnormockImplementationlifecycles intry/finally, or manage them in hooks, somockRestore()always executes.
Close external SDK instances, servers, clients, and transports inafterEachorafterAll, not in test bodies.
Configuregit user.emailanduser.namelocally aftergit initand before committing in temporary repositories; never rely on global Git identity.
Inject small threshold values into threshold tests instead of generating thousands of file...
Files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tstests/engine/reporter.test.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tstests/commands/check-action.test.tstests/integration/check-sarif.test.tstests/integration/check.test.tstests/integration/check-strict.test.ts
{src,tests}/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/LEGAL-001-spdx-license-headers.md)
{src,tests}/**/*.ts: Every TypeScript source file insrc/andtests/must begin with// SPDX-License-Identifier: Apache-2.0followed by// Copyright 2026 Archgate.
If a TypeScript file has a shebang line (for example#!/usr/bin/env buninsrc/cli.ts), the SPDX license header must appear immediately after the shebang.
Use single-line//comments for the SPDX header; do not use block comments (/* */) or alternate license identifiers.
Files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tssrc/helpers/project-config.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tssrc/helpers/telemetry.tstests/engine/reporter.test.tssrc/commands/review-context.tssrc/engine/context.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tssrc/engine/sarif.tstests/commands/check-action.test.tssrc/commands/check.tssrc/commands/adr/sync.tstests/integration/check-sarif.test.tstests/integration/check.test.tssrc/engine/reporter.tstests/integration/check-strict.test.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-006-dependency-policy.md)
**/*.{ts,tsx}: Prefer Bun built-ins for file I/O, HTTP, globbing, testing, and subprocess execution; prefernode:built-in modules over npm alternatives when appropriate.
UseBun.spawnwith array-based arguments for all subprocess execution; do not useBun.$because it can hang on Windows.
Do not add npm packages for functionality already provided by Bun, such asglob,chalk, or utility libraries used for a single function.
Use Bun APIs such asBun.file()instead of Node.js-specific APIs such asfs.readFile()when Bun provides an equivalent.
Use relative imports with Bun's native module resolution; do not use TypeScript path aliases.
**/*.{ts,tsx}: Use TypeScript strict mode with ESNext and ES modules.
Prefer minimal dependencies and Bun built-ins where appropriate.
Files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tssrc/helpers/project-config.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tssrc/helpers/telemetry.tstests/engine/reporter.test.tssrc/commands/review-context.tssrc/engine/context.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tssrc/engine/sarif.tstests/commands/check-action.test.tssrc/commands/check.tssrc/commands/adr/sync.tstests/integration/check-sarif.test.tstests/integration/check.test.tssrc/engine/reporter.tstests/integration/check-strict.test.ts
**/*.{rules.ts,ts}
📄 CodeRabbit inference engine (.archgate/adrs/LEGAL-002-dependency-license-compatibility.md)
Newly encountered permissive licenses may be added to the LEGAL-002 allowlist in the rule implementation, with a comment explaining any override for packages whose package.json lacks a license field.
Files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tssrc/helpers/project-config.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tssrc/helpers/telemetry.tstests/engine/reporter.test.tssrc/commands/review-context.tssrc/engine/context.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tssrc/engine/sarif.tstests/commands/check-action.test.tssrc/commands/check.tssrc/commands/adr/sync.tstests/integration/check-sarif.test.tstests/integration/check.test.tssrc/engine/reporter.tstests/integration/check-strict.test.ts
**/*.test.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Tests should mirror the
src/structure, with fixtures located undertests/fixtures/.
Files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tstests/engine/reporter.test.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tstests/commands/check-action.test.tstests/integration/check-sarif.test.tstests/integration/check.test.tstests/integration/check-strict.test.ts
**/*
📄 CodeRabbit inference engine (CLAUDE.md)
Run
bun run validatesuccessfully before considering any task complete; it performs linting, typechecking, formatting checks, tests, ADR checks, dead-export detection, and build checks.
Files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tssrc/helpers/project-config.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tssrc/helpers/telemetry.tstests/engine/reporter.test.tssrc/commands/review-context.tssrc/engine/context.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tssrc/engine/sarif.tstests/commands/check-action.test.tssrc/commands/check.tssrc/commands/adr/sync.tstests/integration/check-sarif.test.tstests/integration/check.test.tssrc/engine/reporter.tstests/integration/check-strict.test.tsdocs/public/llms-full.txt
tests/engine/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-022-ast-aware-rule-context.md)
Cover AST base-revision behavior, per-language parsing, throw-versus-null semantics, comment extraction, original-source locations, Ruby character offsets, LF-normalized block comments, and Python isolation behavior.
Files:
tests/engine/reporter-strict.test.tstests/engine/reporter.test.ts
tests/**/*.test.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-025-idiomatic-bun-test-parametrization-and-matchers.md)
tests/**/*.test.ts: Usetest.each()for the same assertion logic against multiple independent inputs, anddescribe.each()when each input requires a group of related tests. Do not register tests or run independent assertions insidefor/.forEachloops.
Use array rows for positionaltest.each()arguments and object rows for named fields, with descriptive title placeholders such as%s,%p,%d, or$field.
Assert derived facts with specific matchers rather than collapsing booleans into.toBe(true)or.toBe(false): compare values directly with.toBe()/.toEqual(), use.toContain()or.toMatch()for membership and substrings,.toBeInstanceOf(Array)for array checks,.toHaveLength()for counts, and.find()with.toBeDefined()/.toBeUndefined()for predicate existence checks.
Do not precompute a boolean solely for assertion; assert directly on the underlying values so failures expose the expected and received values.
When converting a loop totest.each()ordescribe.each(), preserve every assertion that ran per iteration; do not drop or merge assertions across cases.
Files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tstests/engine/reporter.test.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tstests/commands/check-action.test.tstests/integration/check-sarif.test.tstests/integration/check.test.tstests/integration/check-strict.test.ts
{src,tests,lint,scripts,shims}/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/GEN-004-concise-forward-only-code-comments.md)
{src,tests,lint,scripts,shims}/**/*.ts: Project-authored TypeScript comments must be concise, describe current behavior only, and never narrate history, relocations, refactors, or how the code came to be.
A contiguous run of whole-line comments must contain at most five lines of narrative prose; longer rationale belongs in an ADR, agent-memory file, issue, or PR with a pointer. Tests and fixtures follow the same limit.
Use structural TSDoc tags such as@param,@returns,@throws,@example, and@seefor structured documentation; tagged sections are exempt from the five-line narrative bound, while@remarks,@description,@summary,@notes,@todo, and@fixmeremain counted as prose.
Files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tssrc/helpers/project-config.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tssrc/helpers/telemetry.tstests/engine/reporter.test.tssrc/commands/review-context.tssrc/engine/context.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tssrc/engine/sarif.tstests/commands/check-action.test.tssrc/commands/check.tssrc/commands/adr/sync.tstests/integration/check-sarif.test.tstests/integration/check.test.tssrc/engine/reporter.tstests/integration/check-strict.test.ts
tests/**/*-strict.test.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
Strict-mode behavior MUST be covered by tests for reporter severity composition,
check,review-context, andadr sync, including configuration precedence and the default advisory-nonblocking behavior.
Files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync-strict.test.tstests/integration/check-strict.test.ts
**
⚙️ CodeRabbit configuration file
**: This project uses Archgate — an AI governance framework based on
Architecture Decision Records (ADRs). The ADRs in.archgate/adrs/
are the authoritative rules for this codebase. Each ADR has a companion
.rules.tsfile with automated checks that run viaarchgate check.When reviewing, you must:
- Treat ADR violations as blocking issues, not suggestions.
- Cite the specific ADR ID when flagging a violation (e.g., "Violates ARCH-006").
- Focus on semantic and contextual violations that automated rules cannot catch —
the.rules.tsfiles already cover syntactic/structural patterns.- If you are unsure whether something violates an ADR, flag it as a question
rather than approving it.
Files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tssrc/helpers/project-config.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tssrc/helpers/telemetry.tstests/engine/reporter.test.tssrc/commands/review-context.tssrc/engine/context.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tssrc/engine/sarif.tstests/commands/check-action.test.tssrc/commands/check.tssrc/commands/adr/sync.tstests/integration/check-sarif.test.tstests/integration/check.test.tssrc/engine/reporter.tstests/integration/check-strict.test.tsdocs/public/llms-full.txt
src/**/!(*platform).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
src/**/!(*platform).ts: Insrc/TypeScript source files, do not readprocess.platformdirectly; usesrc/helpers/platform.ts(isWindows(),isMacOS(),isLinux(),isWSL(),getPlatformInfo()) for all platform detection.
Use the centralized platform helper instead of duplicating OS/WSL detection logic inline anywhere insrc/TypeScript source.
When behavior differs between Linux and Windows, account for WSL by usingisWSL()rather than assuming `
Files:
src/helpers/project-config.tssrc/helpers/telemetry.tssrc/commands/review-context.tssrc/engine/context.tssrc/engine/sarif.tssrc/commands/check.tssrc/commands/adr/sync.tssrc/engine/reporter.ts
src/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-010-prefer-bun-built-in-json-parsing.md)
src/**/*.ts: Useawait Bun.file(path).json()when reading JSON files in Bun TypeScript source code; do not useJSON.parse(await Bun.file(path).text())orJSON.parse(fs.readFileSync(path, "utf-8"))for file reads.
UseBun.JSONC.parse()when reading files that may contain comments, such astsconfig.json, instead of plainJSON.parse()on file contents.
ReserveJSON.parse()for parsing JSON strings from non-file sources such as API responses or string variables; do not use it as the default for reading JSON files.
src/**/*.ts: Use exit codes 0 for success, 1 for expected failures, 2 for internal errors, and 130 for user cancellation; do not use other exit codes.
UselogError()fromsrc/helpers/log.tsfor user-facing errors; write errors to stderr, not stdout, and avoid directconsole.error()calls.
Provide actionable suggestions in user-facing error messages whenever possible.
Do not show stack traces for user-triggered errors; unexpected errors may include stack traces only whenDEBUGorTRACEis set.
Do not catch and swallow unexpected errors; caught errors must be logged or re-thrown.
Do not exit with code 0 when an operation fails; expected failures must use exit code 1.
Fall back toprocess.cwd()whenfindProjectRoot()returns null in commands that do not require.archgate/.
Handle Inquirer'sExitPromptErrorat the top-level error boundary as user cancellation: exit with code 130, do not log an error, and do not send it to Sentry.
Do not sendUserErroror user-cancellationExitPromptErrorinstances to Sentry from any error handler, includingbeforeSend.
UseexitWith()rather than bareprocess.exit()when terminating after command execution so telemetry and Sentry data are flushed.
src/**/*.ts: In TypeScript source files undersrc/, do not create barrel files: anindex.tscontaining onlyexport,export type, orimport typestatements and no executable logic is forbidden.index.tsfiles containing real log...
Files:
src/helpers/project-config.tssrc/helpers/telemetry.tssrc/commands/review-context.tssrc/engine/context.tssrc/engine/sarif.tssrc/commands/check.tssrc/commands/adr/sync.tssrc/engine/reporter.ts
src/helpers/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-002-error-handling.md)
In helper files, use
logInfo()orlogWarn()instead of directconsole.log(),console.warn(), orconsole.info()calls.
Files:
src/helpers/project-config.tssrc/helpers/telemetry.ts
src/{commands/check.ts,commands/review-context.ts,commands/adr/sync.ts,helpers/project-config.ts}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
Resolve strict mode as
opts.strict ?? getConfiguredStrict(projectRoot) ?? false, giving the CLI flag precedence over.archgate/config.jsonand defaulting tofalse.
Files:
src/helpers/project-config.tssrc/commands/review-context.tssrc/commands/check.tssrc/commands/adr/sync.ts
src/commands/!(index).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-001-command-structure.md)
Each top-level command module under
src/commands/must define exactly one command and export aregister*Command(program)function.
Files:
src/commands/review-context.tssrc/commands/check.ts
src/commands/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-001-command-structure.md)
src/commands/**/*.ts: Command files must remain thin: parse arguments, call engine or helper functions, and format output; business logic must reside insrc/engine/,src/helpers/, orsrc/formats/.
Commands must execute in-process and must not spawn child processes for subcommand execution.
Command modules must not call.parse(); command parsing is handled by the CLI entry point.
src/commands/**/*.ts: In Commander.js command files, options requiring type narrowing beyond plain strings MUST usenew Option()from@commander-js/extra-typingsand register it with.addOption(), rather than using.option().
Use.choices([... ] as const)for options accepting a fixed set of values, and do not add manual validation or unsafe casts for those choices.
Use.argParser((value) => ...)on anOptionfor options requiring type conversion; do not pass parser functions such asparseIntas the third argument to.option().
Useas constfor.choices()arrays and.default()values to preserve literal types.
Reuse existing type definitions for type-level usage, access narrowed options directly, and avoid casts such asopts.editor as SomeType.
src/commands/**/*.ts: All commands that operate on.archgate/project resources must use the sharedfindProjectRoot()fromsrc/helpers/paths.ts; directprocess.cwd()project-root resolution is prohibited except ininit.
Commands that require a project must userequireProjectRoot()fromsrc/helpers/paths.tsinstead of implementing their own missing-project guard. Commands that can operate without a project may usefindProjectRoot()and handlenullthemselves.
When usingfindProjectRoot()directly, check for anullresult and provide a helpful error before exiting.
Pass the resolvedprojectRoottoprojectPaths()when constructing derived project paths.
Do not define localfindProjectRoot()variants; use the shared implementation fromsrc/helpers/paths.ts.
src/commands/**/*.ts: Ev...
Files:
src/commands/review-context.tssrc/commands/check.tssrc/commands/adr/sync.ts
src/{commands/check.ts,commands/review-context.ts,commands/adr/sync.ts}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
archgate check,archgate review-context, andarchgate adr syncMUST support a boolean--strictflag that escalates their applicable advisory diagnostics into exit code 1.
Files:
src/commands/review-context.tssrc/commands/check.tssrc/commands/adr/sync.ts
src/commands/review-context.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
review-context --strictMUST fail for non-emptytruncatedBriefings, or, with--run-checks, whencheckSummary.warningsExceededorcheckSummary.strictAdvisoryExceededis true; it MUST NOT gate oncheckSummary.failedorruleErrors.
Files:
src/commands/review-context.ts
src/commands/{check.ts,review-context.ts,adr/sync.ts}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
src/commands/{check.ts,review-context.ts,adr/sync.ts}: A strict-driven failure MUST log a clear message vialogWarn()identifying the finding(s) responsible before callingexitWith(1).
Commands MUST print the complete result payload before exiting non-zero under strict mode.
Files:
src/commands/review-context.tssrc/commands/check.tssrc/commands/adr/sync.ts
src/engine/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-002-error-handling.md)
In engine files, use
logInfo()orlogWarn()instead of directconsole.log(),console.warn(), orconsole.info()calls.Expose exactly one
ctx.ast(path, language, opts?)method fromRuleContext, supportingtypescript,javascript,python, andruby; do not add per-language AST methods.
src/engine/**/*.ts: The rules engine must list files by matching globs in memory against the git-tracked file set, rather than walking the filesystem.
runChecksmust share per-run caches across rule contexts: cache glob results by pattern and tracked mode, cache file text by absolute path using promises, copy cached glob arrays before returning them, and do not cache mutablereadJSONresults.
Do not filter filesystem scan results against the tracked set as a substitute for in-memory matching, and do not hardcode ignore directories; Git's ignore-aware file listing is authoritative.
Files:
src/engine/context.tssrc/engine/sarif.tssrc/engine/reporter.ts
src/engine/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-022-ast-aware-rule-context.md)
src/engine/**/*.{ts,tsx}: TypeScript and JavaScript AST parsing must reuse the in-processmeriyahparser through one sharedparseTsOrJsSourcehelper used by bothrule-scanner.tsandctx.ast().
Python and Ruby AST parsing must use their standard-library facilities through guardedBun.spawnsubprocesses; no third-party parser may be introduced.
InsidecreateRuleContext(), perform guardrails in order: path safety, language plausibility, interpreter availability probe, then guarded AST subprocess invocation.
Rule code must not accessBun.spawn,child_process, or other subprocess/filesystem primitives directly;ctx.ast()is the only sanctioned AST subprocess door.
Use array-based subprocess arguments only; Python AST invocation must include the mandatory-Iisolation flag, and interpreter probing must use the platform-specific candidate order and cache its result per check.
ctx.ast()must throw on missing interpreters, parse failures, missing base revisions, or files absent at base; it must never returnnullor another sentinel.fileAtBase()is the exception and may returnnull.
ast(path, language, { rev: "base" })andfileAtBase(path)must read the merge base used by the current change-set comparison; git operations remain ingit-files.ts, with no new subprocess site.
AST paths must apply the existing sandbox and reject symlink escapes at every path component below the project root; checks must use booleanlstatrather thanrealpathcomparisons.
Validate the requested language against the file extension and/or leading content before invoking any interpreter.
Support opt-in{ comments: true }by returning structuredCommentTokenvalues with delimiter-stripped content and source locations; omit comments unless explicitly requested.
Preserve language-native AST shapes rather than normalizing Python or Ruby trees into ESTree; document that AST vocabulary and node locations differ by language.
For TypeScript and JavaScript comments...
Files:
src/engine/context.tssrc/engine/sarif.tssrc/engine/reporter.ts
src/commands/check.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
src/commands/check.ts:checkMUST collectbriefingWarningsandunparsedAdrson every exit path, including the zero-rules early return;suppressionWarningsremain violation-scoped.
The former--max-warnings <n>option MUST NOT be reintroduced; strict escalation is deliberately binary.
Files:
src/commands/check.ts
{src/commands/*/!(index).ts,src/commands/*/*/index.ts,docs/src/content/docs/reference/cli/*.mdx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
Every direct subcommand represented by
src/commands/<parent>/<sub>.tsorsrc/commands/<parent>/<sub>/index.tsmust have a corresponding heading indocs/src/content/docs/reference/cli/<parent>.mdx, and every heading matchingarchgate <parent> <sub>must correspond to an actual subcommand file. Matching is case-insensitive.
Files:
src/commands/adr/sync.ts
src/commands/adr/sync.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
adr sync --strictMUST fail whenresult.errors > 0, while remaining composable with the existing--checkfailure condition (withChanges > 0).
Files:
src/commands/adr/sync.ts
src/engine/reporter.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-026-strict-mode-and-check-severity-tiers.md)
src/engine/reporter.ts:buildSummary()andgetExitCode()MUST centrally compute strict pass/fail behavior, includingstrictAdvisoryExceeded; callers must consume that result rather than re-deriving the condition.
Under strict mode, the advisory categories are rule-severitywarning,briefingWarnings,suppressionWarnings, andunparsedAdrs; any applicable advisory finding must cause failure while remaining present in the result payload.
New advisory-styleReportSummarydiagnostics MUST be added to thestrictAdvisoryExceededcomputation inbuildSummary(), rather than handled through a separate condition.
Files:
src/engine/reporter.ts
docs/**/*
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
docs/**/*: Do not include the docs build in the CLIvalidatepipeline; docs build failures must not block CLI development or CI.
Do not create content files outsidedocs/src/content/docs/, becausedocsLoader()expects that directory structure.
Install documentation dependencies from withindocs/usingcd docs && bun installor the docs convenience scripts, not from the repository root.
Files:
docs/public/llms-full.txt
🧠 Learnings (12)
📚 Learning: 2026-07-25T00:05:58.884Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: tests/helpers/auth.test.ts:38-46
Timestamp: 2026-07-25T00:05:58.884Z
Learning: When reviewing the Archgate CLI repository’s GEN-004 “concise forward-only narration” comments, don’t rely only on the automated phrase-based narration checks. Those checks can pass even when the comment wording describes historical/transfer semantics rather than current behavior (e.g., saying a prior restore “leaked” a value or a later subprocess “inherited it”). Manually verify that the comment describes the code’s current, forward behavior; flag or adjust comments that imply past/historical state transfer even if GEN-004 enforcement passes.
Applied to files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tssrc/helpers/project-config.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tssrc/helpers/telemetry.tstests/engine/reporter.test.tssrc/commands/review-context.tssrc/engine/context.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tssrc/engine/sarif.tstests/commands/check-action.test.tssrc/commands/check.tssrc/commands/adr/sync.tstests/integration/check-sarif.test.tstests/integration/check.test.tssrc/engine/reporter.tstests/integration/check-strict.test.ts
📚 Learning: 2026-07-25T00:05:59.109Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: src/cli.ts:0-0
Timestamp: 2026-07-25T00:05:59.109Z
Learning: Code comments may include a concise issue/PR reference (per GEN-004) when it’s used to point readers to fuller rationale instead of inlining that rationale. During review, flag surrounding comment prose that reads like historical context or narrates refactors/relocations; a bare GEN-004-style reference is allowed and should not be flagged by itself.
Applied to files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tssrc/helpers/project-config.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tssrc/helpers/telemetry.tstests/engine/reporter.test.tssrc/commands/review-context.tssrc/engine/context.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tssrc/engine/sarif.tstests/commands/check-action.test.tssrc/commands/check.tssrc/commands/adr/sync.tstests/integration/check-sarif.test.tstests/integration/check.test.tssrc/engine/reporter.tstests/integration/check-strict.test.ts
📚 Learning: 2026-07-25T15:44:40.668Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-005-testing-standards.md:0-0
Timestamp: 2026-07-25T15:44:40.668Z
Learning: In Archgate CLI test code governed by ARCH-007, only allow `Bun.$` in test suites that are explicitly restricted to a single platform. Any cross-platform test that runs on Linux, macOS, and Windows must avoid `Bun.$` and instead use array-based `Bun.spawn`. For shared git setup used by tests, import and use the `git()` helper from `tests/test-utils.ts` rather than duplicating git setup logic.
Applied to files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tstests/engine/reporter.test.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tstests/commands/check-action.test.tstests/integration/check-sarif.test.tstests/integration/check.test.tstests/integration/check-strict.test.ts
📚 Learning: 2026-07-25T22:03:14.216Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-002-error-handling.md:0-0
Timestamp: 2026-07-25T22:03:14.216Z
Learning: In Archgate boundary-wrapped CLI command actions (the handlers that rely on `handleCommandError()` for user-facing error output), expected-failure guards should signal user errors by throwing `new UserError(<message/details>)` rather than directly calling `logError()` followed by `exitWith(1)`. This keeps user-facing logging and the exit path centralized in `handleCommandError()`. For normal/computed command outcomes (e.g., `const exitCode = getExitCode(await runChecks(...))`), use `await exitWith(exitCode)` instead of calling `process.exit(exitCode)` so telemetry/Sentry flushing and outcome tagging still run.
Applied to files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tssrc/helpers/project-config.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tssrc/helpers/telemetry.tstests/engine/reporter.test.tssrc/commands/review-context.tssrc/engine/context.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tssrc/engine/sarif.tstests/commands/check-action.test.tssrc/commands/check.tssrc/commands/adr/sync.tstests/integration/check-sarif.test.tstests/integration/check.test.tssrc/engine/reporter.tstests/integration/check-strict.test.ts
📚 Learning: 2026-07-25T23:21:11.504Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 512
File: tests/engine/runner-ast-cache.test.ts:82-82
Timestamp: 2026-07-25T23:21:11.504Z
Learning: For Bun/TS tests under tests/engine, it’s acceptable (per ARCH-025) to validate a runtime-sized collection produced by a single operation by looping over items and making direct assertions like `expect(item).toBe(...)` inside the loop. Treat this as an approved alternative to boolean-collapse assertions such as `expect(items.every(predicate)).toBe(true)`. Do NOT conflate this with prohibited “manual loops” that create independent test cases (e.g., calling `test(...)`/`it(...)` inside a loop); that pattern should still be flagged.
Applied to files:
tests/engine/reporter-strict.test.tstests/engine/reporter.test.ts
📚 Learning: 2026-07-25T23:21:49.190Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 512
File: tests/engine/git-files.test.ts:98-100
Timestamp: 2026-07-25T23:21:49.190Z
Learning: When reviewing archgate/cli for ARCH-006 (per its ADR frontmatter), only enforce the production-dependency policy scoped to package.json. Do not treat test-only refactors or relocated `node:fs` fixture writes as an ARCH-006 violation (since ARCH-006 does not govern test-file I/O API selection). If there’s a broader/test-wide refactor that would migrate fixture writing to `Bun.write()`, evaluate it separately under the appropriate in-scope rule.
Applied to files:
tests/engine/reporter-strict.test.tstests/commands/adr/sync.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tstests/engine/reporter.test.tstests/integration/check-base.test.tstests/commands/adr/sync-strict.test.tstests/commands/check-action.test.tstests/integration/check-sarif.test.tstests/integration/check.test.tstests/integration/check-strict.test.ts
📚 Learning: 2026-07-15T22:56:35.415Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 476
File: tests/commands/clean.test.ts:61-62
Timestamp: 2026-07-15T22:56:35.415Z
Learning: When reviewing tests that rely on src/helpers/paths.ts `internalPath()`, note that `internalPath()` intentionally reads `Bun.env.HOME ?? Bun.env.USERPROFILE` at call time and only uses `os.homedir()` if neither env var is set. Therefore, don’t suggest changing tests to `spyOn(os, "homedir")` for this behavior; instead, use per-test `Bun.env.HOME` / `Bun.env.USERPROFILE` overrides (as applicable) so the tests control `internalPath()`’s inputs.
Applied to files:
tests/commands/adr/sync.test.tstests/commands/review-context.test.tstests/helpers/project-config.test.tstests/helpers/telemetry.test.tstests/commands/adr/sync-strict.test.tstests/commands/check-action.test.ts
📚 Learning: 2026-07-02T16:03:33.031Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 446
File: src/helpers/session-context-opencode.ts:81-100
Timestamp: 2026-07-02T16:03:33.031Z
Learning: For synchronous helper functions that use Bun’s sqlite sync API (i.e., they must remain synchronous), it’s acceptable to use `existsSync` from `node:fs` to check whether the SQLite database file exists. Avoid using `Bun.file(path).exists()` for this purpose because it’s async and would force the helper to become async (no equivalent synchronous Bun alternative). If the DB file is missing, throw/return a clear, actionable "No database found" error (per ARCH-006) rather than letting the sqlite open fail with a generic DB-open error.
Applied to files:
src/helpers/project-config.tssrc/helpers/telemetry.ts
📚 Learning: 2026-07-15T22:55:51.978Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 476
File: tests/helpers/telemetry-config.test.ts:24-28
Timestamp: 2026-07-15T22:55:51.978Z
Learning: In this Bun/TypeScript codebase, when a unit under test spawns subprocesses via Bun.spawn (e.g., running `git credential ...`), prefer overriding relevant env vars (such as `HOME`, `GIT_CONFIG_GLOBAL`, `GIT_CONFIG_NOSYSTEM`) using `process.env` in the test and restoring them with the test utility (e.g., `restoreEnv` from `tests/test-utils.ts`). Avoid relying on `spyOn(os, 'homedir')` for this purpose, because it only affects in-process calls and does not change the environment inherited by subprocesses; env-var overrides should be used for subprocess-level isolation and must be applied at call time.
Applied to files:
tests/helpers/project-config.test.tstests/helpers/telemetry.test.ts
📚 Learning: 2026-07-25T22:03:22.236Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md:64-67
Timestamp: 2026-07-25T22:03:22.236Z
Learning: When reviewing CLI subcommand documentation, don’t rely solely on the companion ARCH-016 enforcement rule’s limited path coverage (it only checks `src/commands/<parent>/*.ts` and `src/commands/<parent>/*/index.ts`). Manually verify that subcommands documented by convention in deeper paths (e.g., `src/commands/<parent>/**/add.ts` or `src/commands/adr/domain/add.ts`) have the required documentation, since future nested subcommands can drift without automated detection (tracked by ARCH-015 / GitHub `#503`).
Applied to files:
src/commands/review-context.tssrc/commands/check.tssrc/commands/adr/sync.ts
📚 Learning: 2026-06-11T12:50:28.661Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 406
File: .claude/agent-memory/archgate-developer/feedback_prefer_tests_over_adr_rules.md:8-18
Timestamp: 2026-06-11T12:50:28.661Z
Learning: In `archgate/cli`, for markdown files under `.claude/agent-memory/`, follow the established convention: use YAML frontmatter (with a `name:` field used as the document title) and do not require a top-level `#` (H1) heading. During code review, do not flag missing first-line/first-top-level H1 headings (e.g., MD041) for these agent-memory files since markdownlint is not part of the repo’s `bun run validate` lint pipeline (oxlint/oxfmt only).
Applied to files:
.claude/agent-memory/archgate-developer/MEMORY.md
📚 Learning: 2026-07-25T00:05:20.592Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: .claude/agent-memory/archgate-developer/project_test_isolation_gotchas.md:10-10
Timestamp: 2026-07-25T00:05:20.592Z
Learning: When reviewing documentation/agent-memory entries under `.claude/agent-memory/**`, do not enforce GEN-004’s “forward-only” comment/narrative requirement. These entries are allowed to keep historical/past-tense incident narratives and dated markers (e.g., `Found YYYY-MM-DD`) because the context is intended to help future agents evaluate edge cases. Outside this scope, GEN-004’s forward-only rule should still apply.
Applied to files:
.claude/agent-memory/archgate-developer/MEMORY.md
🪛 OpenGrep (1.25.0)
src/commands/adr/sync.ts
[ERROR] 95-95: Dynamic command passed to child_process.exec/execSync. Use child_process.execFile or spawn with an argument array instead.
(coderabbit.command-injection.exec-js)
🔇 Additional comments (1)
.claude/agent-memory/archgate-developer/MEMORY.md (1)
20-21: LGTM!Also applies to: 33-35, 36-36
review-context --run-checks returned a hard-coded empty summary when no
rule ADR loaded, so --strict missed briefing overruns and unparsed ADRs
that check itself reports on the same corpus. The zero-rules branch now
mirrors check: collect the ADR-corpus diagnostics and build the summary
through buildSummary({ strict }), replacing the EMPTY_SUMMARY constant.
Adds a prose-only-corpus regression test.
Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
…s assertions Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
1 participant
Summary
--strict(new, oncheck,review-context,adr sync): treats otherwise-advisory diagnostics as failures. Oncheckit fails on any rule-severity warning and onbriefingWarnings/suppressionWarnings/unparsedAdrs; onreview-contextit fails ontruncatedBriefingsand, with--run-checks, on the reusedcheckSummaryfindings (deliberately not on ordinary rule violations —checkstays the compliance gate); onadr syncit fails onresult.errors. Resolves CLI flag →strictkey in.archgate/config.json→ off. Documented in new ADR ARCH-026.--output <format>(breaking,checkonly): replaces the--json/--ciboolean flags with a single typed option —console(default) |json|github(Actions annotations) |sarif. Agent-context auto-detect still upgrades the default to compactjson;github/sarifare opt-in only.--output sarif(new): SARIF 2.1.0 for GitHub Code Scanning/Code Quality — rule violations plus advisory findings as synthetic-rule results. No new dependency (hand-built insrc/engine/sarif.ts).--max-warningsremoved (breaking,checkonly):--strictis the single escalation switch; the tolerate-up-to-N warning budget is gone.checknow collects corpus-wide advisory diagnostics even when norules: trueADR loads, so a prose-only or fully-unparseable corpus can't silently pass--strict.if: always()+security-events: write).Breaking changes
archgate check --jsonarchgate check --output jsonarchgate check --ciarchgate check --output githubarchgate check --max-warnings <n>archgate check --strict(zero-tolerance only)No other command's flags are affected.
Test plan
bun run validate(lint, typecheck, format, 1873 tests,archgate check49/49, knip, build check) passes cleanreporter-strict,check-strict(incl. zero-rules + removed-flag rejection),review-context-strict,sync-strict,sarifunit +check-sarifintegration tests