docs(adrs): resolve all nine open documentation issues from the #501 review - #545
Conversation
…02 and ARCH-012 ARCH-001's main().catch prescription and Good Example now show the real three-branch handler and command boundary from src/cli.ts; ARCH-002 routes unexpected errors to the boundary instead of a natural crash; ARCH-012's Decision and pattern name handleCommandError() as the boundary mechanism. Refs #502 Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
… registration ARCH-016's rule discovers command groups recursively, so module-backed subcommands at any depth (adr domain add/list/remove) require full-path headings in the top-level parent's reference page; orphan detection is scoped to paths whose parent chain is group directories, leaving in-module subcommands (session-context editors' list/show) to review. ARCH-015's rule cross-checks register*Command calls in src/cli.ts against the module layout in both directions. adr.mdx (en/nb/pt-br) documents the domain subcommands under their own headings. Refs #503 Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
…24 accounts ARCH-022 names parseJsModule as the parse primitive shared by the scanner and ctx.ast()'s parseTsOrJsSource wrapper, and states the entry-point delegation; ARCH-024 describes scanImportedRuleSource() as the pure pass-through it is. The new convergence suite runs one payload corpus through both entry points and asserts deeply-equal results. Refs #508 Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
…03, LEGAL-002 ARCH-004 drops the unverified tree-shaking rationale (the four remaining problems carry the decision). ARCH-008's example is compile-time exhaustive over the real five-editor EDITOR_TARGETS union. CI-001 requires dereferencing annotated tags to a commit SHA and documents the rule's shape-only limitation. CI-002 names the exact checksum asset. GEN-003 scopes its mandate to the project's own JS/TS toolchain and carries the CI-only external-binary exception bidirectionally with CI-002. GEN-002 defines the English source set as excluding locale directories and keeps same-PR translation as the single policy. LEGAL-002 states the copyleft prohibition as project policy. Refs #504 #505 #506 #507 #509 #510 Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Refs #503 Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Deploying archgate-cli with
|
| Latest commit: |
0998ecd
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://9ffa8122.archgate-cli.pages.dev |
| Branch Preview URL: | https://rhuanbarreto-docs-issues-aud.archgate-cli.pages.dev |
|
Warning Review limit reached
Next review available in: 12 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe changes reconcile command error-handling ADRs with centralized boundaries, expand CLI registration and nested subcommand documentation checks, and align rule-scanner architecture guidance with convergence tests. They also correct CI, localization, tooling, licensing, barrel-file, and ADR-editing guidance. ADR domain documentation now separates 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 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 |
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: 5
🤖 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-001-command-structure.md:
- Around line 117-118: Complete the imports in both ADR examples: in
.archgate/adrs/ARCH-001-command-structure.md at lines 117-118, import
captureException used by the example; in
.archgate/adrs/ARCH-008-typed-command-options.md at lines 61-66, import
EDITOR_TARGETS before its use in .choices(EDITOR_TARGETS).
In @.archgate/adrs/ARCH-012-command-error-boundaries.md:
- Around line 30-32: Update the Context section of ARCH-012 to describe the
src/cli.ts main().catch() fallback as exiting with code 2 only for unexpected
errors, while noting that UserError is handled with logError() and exit code 1
before that path. Keep the existing safety-net description and align the wording
so escaped UserError and unexpected-error outcomes are not conflated.
In @.archgate/adrs/ARCH-015-cli-command-documentation-coverage.rules.ts:
- Around line 48-54: Replace the source-text regex in the ARCH-015 rule with
ctx.ast("src/cli.ts", "typescript") traversal, collecting only executable
register*Command(program) call expressions and preserving the existing
command-name normalization. In
.archgate/adrs/ARCH-015-cli-command-documentation-coverage.rules.ts lines 48-54,
update the registration inspection accordingly; in
.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md line 76, remove
the claims that the rule uses one regex pass and no AST parsing.
In @.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts:
- Line 86: Update the heading-matching regular expression in the Markdown
parsing logic to accept heading levels one through six by expanding the hash
quantifier from 1–4 to 1–6. Preserve the existing archgate command matching and
capture behavior.
In @.archgate/adrs/LEGAL-002-dependency-license-compatibility.md:
- Line 71: Correct the license example in the ADR’s “May reject useful packages”
bullet by removing readline-sync or replacing it with a confirmed
copyleft-licensed package, while preserving the point that such dependencies may
be rejected.
🪄 Autofix
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: abd0d723-67da-4d01-b7e0-1975e9208e39
📒 Files selected for processing (22)
.archgate/adrs/ARCH-001-command-structure.md.archgate/adrs/ARCH-002-error-handling.md.archgate/adrs/ARCH-004-no-barrel-files.md.archgate/adrs/ARCH-008-typed-command-options.md.archgate/adrs/ARCH-012-command-error-boundaries.md.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md.archgate/adrs/ARCH-015-cli-command-documentation-coverage.rules.ts.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts.archgate/adrs/ARCH-022-ast-aware-rule-context.md.archgate/adrs/ARCH-024-rule-file-sandbox-boundary.md.archgate/adrs/CI-001-pin-github-actions-by-hash.md.archgate/adrs/CI-002-validate-workflow-syntax-with-actionlint.md.archgate/adrs/GEN-002-docs-i18n.md.archgate/adrs/GEN-003-tool-invocation-via-scripts.md.archgate/adrs/LEGAL-002-dependency-license-compatibility.md.claude/agent-memory/archgate-developer/MEMORY.mddocs/public/llms-full.txtdocs/src/content/docs/nb/reference/cli/adr.mdxdocs/src/content/docs/pt-br/reference/cli/adr.mdxdocs/src/content/docs/reference/cli/adr.mdxtests/engine/rule-scanner-escapes-convergence.test.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (1)
- GitHub Check: Coverage Report
🧰 Additional context used
📓 Path-based instructions (16)
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/rule-scanner-escapes-convergence.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/rule-scanner-escapes-convergence.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/rule-scanner-escapes-convergence.test.ts
**/*.test.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Tests should mirror the
src/structure, with fixtures located undertests/fixtures/.
Files:
tests/engine/rule-scanner-escapes-convergence.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/rule-scanner-escapes-convergence.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.mdxdocs/public/llms-full.txt
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/rule-scanner-escapes-convergence.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/rule-scanner-escapes-convergence.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/rule-scanner-escapes-convergence.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.mdxdocs/public/llms-full.txt
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.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: Keep English documentation files at the root content path, and place each translation under the corresponding locale directory with the same relative path and filename.
Maintain 1:1 page parity: every English MDX page must have a Portuguese and Norwegian translation, and locale pages must not be orphaned.
When English documentation is added or modified, update the corresponding locale files in the same pull request.
Translate user-facing prose, titles, descriptions, headings, lists, tables, admonitions, and Starlight component text props; keep code blocks, CLI commands, paths, identifiers, technical terms, imports, component names, and link or slug values in English.
Keep internal link paths unchanged and do not add locale prefixes such as/pt-br/; Starlight resolves locale-aware routes automatically.
Preserve MDX curly-brace escaping and keep component imports identical between source and translations.
Use correct Brazilian Portuguese diacritics and Norwegian Bokmål, including the required charactersæ,ø, andå; do not use unaccented Portuguese or Nynorsk.
Do not use machine translation without human review for technical accuracy.
Reviewers must verify that translations are accurate and natural, individual words retain diacritics, English technical content remains unchanged, structural MDX elements and imports are preserved, links have no locale prefixes, and new English pages have sam...
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.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/public/llms-full.txt
.archgate/adrs/**/*.rules.ts
📄 CodeRabbit inference engine (.archgate/adrs/GEN-004-concise-forward-only-code-comments.md)
.archgate/adrs/**/*.rules.ts: Comments in.archgate/adrs/**/*.rules.tsmust be concise, forward-only, and limited to current behavior; historical or relocation narration is prohibited.
Changes to narration or relocation detection patterns in companion.rules.tsfiles must be synchronized with.archgate/lint/oxlint.ts, and both enforcement layers must continue to report violations at error severity.
Files:
.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts.archgate/adrs/ARCH-015-cli-command-documentation-coverage.rules.ts
.archgate/{lint,adrs}/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/GEN-004-concise-forward-only-code-comments.md)
.archgate/{lint,adrs}/**/*.ts: A contiguous run of whole-line comments must contain at most five lines of narrative prose, including in lint and companion rule implementations.
Use the same synchronized structural-TSDoc exemption in Archgate TypeScript files; narrative must not be relabeled with prose-container tags to evade the limit.
Files:
.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts.archgate/adrs/ARCH-015-cli-command-documentation-coverage.rules.ts
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: Each top-level CLI command must have its own reference page; subcommands must be documented inline in the parent page, andindex.mdxis reserved as the section landing page.
CLI reference pages should follow the established MDX 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.mdx
docs/src/content/docs/reference/cli/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
docs/src/content/docs/reference/cli/**/*.mdx: Every heading in an English CLI reference page whose command path has a parent chain consisting of command-group directories must correspond to an actual module-backed subcommand.
Use the standard heading format containingarchgate <parent> <sub>and the full command path; do not create separate.mdxfiles for subcommands.
Files:
docs/src/content/docs/reference/cli/adr.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 Portuguese (
pt-br) mirror.
Files:
docs/src/content/docs/pt-br/reference/cli/adr.mdx
🧠 Learnings (15)
📓 Common learnings
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T03:32:10.376Z
Learning: When switching on a narrowed fixed-choice option, use an exhaustive `never` check so newly added choices produce a compile-time failure until handled.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T03:32:24.995Z
Learning: When website CLI documentation changes, manually update the skill reference `commands.md` files in the separate `archgate/plugins` repository so all four copies remain identical and synchronized.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T03:32:40.283Z
Learning: Do not weaken the rule-file boundary by reintroducing denylists, allowing bare specifiers or `node:module`, importing unscanned rules, scanning after `import()`, or following relative imports transitively. Any such change, or removal of the import-time scan, requires a separate approved ADR.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T03:32:46.259Z
Learning: Enable and maintain Renovate or Dependabot updates for pinned GitHub Actions so immutable references do not become stale.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T03:32:58.503Z
Learning: When adding a new language, update `LOCALES` and `LOCALE_DIACRITICS` in the companion internationalization rules file.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T03:33:02.962Z
Learning: External non-npm binaries invoked only in CI, such as `actionlint`, are outside this script-wrapper requirement.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T03:33:07.923Z
Learning: Run `archgate check` or `bun run validate` before adding dependencies and ensure dependency additions document license compatibility.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T03:33:07.923Z
Learning: When a clearly permissive dependency lacks a package.json license field, add it to the LEGAL-002 allowlist only with a documented override explaining the evidence.
📚 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-002-error-handling.md.archgate/adrs/CI-002-validate-workflow-syntax-with-actionlint.md.archgate/adrs/LEGAL-002-dependency-license-compatibility.md.archgate/adrs/ARCH-008-typed-command-options.md.archgate/adrs/ARCH-004-no-barrel-files.md.archgate/adrs/ARCH-024-rule-file-sandbox-boundary.md.archgate/adrs/ARCH-022-ast-aware-rule-context.md.archgate/adrs/GEN-002-docs-i18n.md.archgate/adrs/CI-001-pin-github-actions-by-hash.md.archgate/adrs/ARCH-001-command-structure.md.archgate/adrs/ARCH-012-command-error-boundaries.md.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md.archgate/adrs/GEN-003-tool-invocation-via-scripts.md.archgate/adrs/ARCH-015-cli-command-documentation-coverage.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-002-error-handling.md.archgate/adrs/CI-002-validate-workflow-syntax-with-actionlint.md.archgate/adrs/LEGAL-002-dependency-license-compatibility.md.archgate/adrs/ARCH-008-typed-command-options.md.archgate/adrs/ARCH-004-no-barrel-files.md.archgate/adrs/ARCH-024-rule-file-sandbox-boundary.md.archgate/adrs/ARCH-022-ast-aware-rule-context.md.archgate/adrs/GEN-002-docs-i18n.md.archgate/adrs/CI-001-pin-github-actions-by-hash.md.archgate/adrs/ARCH-001-command-structure.md.archgate/adrs/ARCH-012-command-error-boundaries.md.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md.archgate/adrs/GEN-003-tool-invocation-via-scripts.md.archgate/adrs/ARCH-015-cli-command-documentation-coverage.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-002-error-handling.md.archgate/adrs/CI-002-validate-workflow-syntax-with-actionlint.md.archgate/adrs/LEGAL-002-dependency-license-compatibility.md.archgate/adrs/ARCH-008-typed-command-options.md.archgate/adrs/ARCH-004-no-barrel-files.md.archgate/adrs/ARCH-024-rule-file-sandbox-boundary.md.archgate/adrs/ARCH-022-ast-aware-rule-context.md.archgate/adrs/GEN-002-docs-i18n.md.archgate/adrs/CI-001-pin-github-actions-by-hash.md.archgate/adrs/ARCH-001-command-structure.md.archgate/adrs/ARCH-012-command-error-boundaries.md.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md.archgate/adrs/GEN-003-tool-invocation-via-scripts.md.archgate/adrs/ARCH-015-cli-command-documentation-coverage.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-002-error-handling.md.archgate/adrs/CI-002-validate-workflow-syntax-with-actionlint.md.archgate/adrs/LEGAL-002-dependency-license-compatibility.md.archgate/adrs/ARCH-008-typed-command-options.md.archgate/adrs/ARCH-004-no-barrel-files.md.archgate/adrs/ARCH-024-rule-file-sandbox-boundary.md.archgate/adrs/ARCH-022-ast-aware-rule-context.md.archgate/adrs/GEN-002-docs-i18n.md.archgate/adrs/CI-001-pin-github-actions-by-hash.md.archgate/adrs/ARCH-001-command-structure.md.archgate/adrs/ARCH-012-command-error-boundaries.md.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md.archgate/adrs/GEN-003-tool-invocation-via-scripts.md.archgate/adrs/ARCH-015-cli-command-documentation-coverage.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/rule-scanner-escapes-convergence.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/rule-scanner-escapes-convergence.test.ts
📚 Learning: 2026-08-04T19:58:05.877Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 543
File: src/helpers/copilot-user-settings.ts:0-0
Timestamp: 2026-08-04T19:58:05.877Z
Learning: In archgate/cli TypeScript code, use `Bun.file(path).exists()` only to check whether a file exists; it must not be used for directory existence checks. For helpers such as `isCopilotAvailable()` that need to detect a configuration directory, use an appropriate directory-aware check such as `existsSync` from `node:fs`.
Applied to files:
tests/engine/rule-scanner-escapes-convergence.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/rule-scanner-escapes-convergence.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/rule-scanner-escapes-convergence.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/rule-scanner-escapes-convergence.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/rule-scanner-escapes-convergence.test.ts
📚 Learning: 2026-07-27T16:05:38.683Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 536
File: tests/commands/adr/sync-strict.test.ts:173-173
Timestamp: 2026-07-27T16:05:38.683Z
Learning: In this Bun + TypeScript repo, for rejected-promise assertions use the unawaited form: `expect(promise).rejects.toThrow(...)`. Do NOT add `await` to `expect(promise).rejects.toThrow(...)` (Bun’s types model this as `void`), because it will violate the type-aware oxlint rules `typescript(await-thenable)` and `typescript(no-confusing-void-expression)`. Only request an `await` if the repo adopts a typed, lint-compliant assertion helper or Bun’s typings change.
Applied to files:
tests/engine/rule-scanner-escapes-convergence.test.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
🪛 LanguageTool
.archgate/adrs/CI-001-pin-github-actions-by-hash.md
[uncategorized] ~109-~109: The official name of this software platform is spelled with a capital “H”.
Context: ...CI-001/no-unpinned-actions: scans all .github/workflows/*.yml files for uses: line...
(GITHUB)
docs/src/content/docs/pt-br/reference/cli/adr.mdx
[uncategorized] ~196-~196: Sinal de pontuação isolado.
Context: ...``` Regras de nomenclatura: - <name>: kebab-case em minúsculas, 2–32 caracter...
(UNLIKELY_OPENING_PUNCTUATION)
🪛 OpenGrep (1.26.0)
.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts
[ERROR] 86-86: 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 (22)
.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md (1)
51-52: LGTM!Also applies to: 77-83, 94-94
.archgate/adrs/ARCH-015-cli-command-documentation-coverage.rules.ts (1)
16-39: LGTM!Also applies to: 56-77
.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md (1)
34-41: LGTM!Also applies to: 52-52, 72-84
.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts (1)
6-57: LGTM!Also applies to: 59-80, 99-128
docs/public/llms-full.txt (1)
3917-3961: LGTM!docs/src/content/docs/nb/reference/cli/adr.mdx (1)
167-211: LGTM!docs/src/content/docs/pt-br/reference/cli/adr.mdx (1)
167-211: LGTM!docs/src/content/docs/reference/cli/adr.mdx (1)
167-211: 📐 Maintainability & Code QualityVerify plugin skill-reference synchronization.
This website CLI reference changed. Update the four
commands.mdcopies in the separatearchgate/pluginsrepository, and confirm that they are identical.Source: Learnings
.archgate/adrs/ARCH-001-command-structure.md (1)
42-42: LGTM!Also applies to: 62-80
.archgate/adrs/ARCH-002-error-handling.md (1)
48-48: LGTM!.archgate/adrs/ARCH-012-command-error-boundaries.md (1)
41-43: LGTM!Also applies to: 59-68
.archgate/adrs/ARCH-008-typed-command-options.md (1)
61-87: 🎯 Functional CorrectnessVerify that
EDITOR_TARGETSretains a literal tuple type.The
neverbranch is exhaustive only whenopts.editoris narrowed to the editor union. Confirm thatEDITOR_TARGETSis exported as a readonly tuple, not a widenedstring[], and add a typecheck case that adds a new editor without a switch branch. The@commander-js/extra-typingsdeclarations derive choice types from the tuple element type passed to.choices(). (github.com)Also applies to: 139-139
Source: MCP tools
.archgate/adrs/ARCH-022-ast-aware-rule-context.md (1)
41-41: LGTM!Also applies to: 50-50, 84-84
.archgate/adrs/ARCH-024-rule-file-sandbox-boundary.md (1)
101-101: LGTM!tests/engine/rule-scanner-escapes-convergence.test.ts (1)
25-26: 📐 Maintainability & Code QualityNo change needed for the convergence corpus.
ARCH-024requirestests/engine/rule-scanner-escapes-convergence.test.tsto run every escape payload through both entry points; this file does that for its declared payloads..archgate/adrs/ARCH-004-no-barrel-files.md (1)
13-23: LGTM!Also applies to: 108-112
.archgate/adrs/CI-001-pin-github-actions-by-hash.md (1)
56-64: LGTM!Also applies to: 101-109
.archgate/adrs/CI-002-validate-workflow-syntax-with-actionlint.md (1)
36-36: LGTM!Also applies to: 63-63, 110-110
.archgate/adrs/GEN-002-docs-i18n.md (1)
34-34: LGTM!Also applies to: 50-50, 134-134
.archgate/adrs/GEN-003-tool-invocation-via-scripts.md (1)
34-34: LGTM!Also applies to: 62-62, 95-101
.archgate/adrs/LEGAL-002-dependency-license-compatibility.md (1)
13-13: LGTM!.claude/agent-memory/archgate-developer/MEMORY.md (1)
35-35: LGTM!
ARCH-015's registration cross-check walks src/cli.ts's AST for executable register*Command(program) call expressions, so a call spelled in a comment or string no longer counts as a registration; the ADR's enforcement-cost prose matches. ARCH-016's heading pattern accepts all six Markdown levels. ARCH-001/ARCH-008 examples import every identifier they use. ARCH-012's Context qualifies the main().catch() exit paths. LEGAL-002's copyleft example is the mariadb connector (LGPL-2.1-or-later, verified against the npm registry) — readline-sync is MIT. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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-015-cli-command-documentation-coverage.rules.ts:
- Around line 84-86: Update the registration-name normalization in the
registered.add flow to split acronym-to-word boundaries as well as
lowercase-or-digit-to-uppercase boundaries, so names such as
registerMCPServerCommand normalize to register-mcp-server-command and match
command filenames like mcp-server.
- Around line 22-33: Replace the recursive implementation of walk with an
iterative depth-first traversal using an explicit work list, preserving array
handling and visit behavior for EsTreeNode values. Track visited object
references with a WeakSet if the AST adapter may share nodes, and ensure deeply
nested trees cannot exhaust the call stack.
🪄 Autofix
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: 76e52576-f916-492f-abde-1962f268ec1b
📒 Files selected for processing (7)
.archgate/adrs/ARCH-001-command-structure.md.archgate/adrs/ARCH-008-typed-command-options.md.archgate/adrs/ARCH-012-command-error-boundaries.md.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md.archgate/adrs/ARCH-015-cli-command-documentation-coverage.rules.ts.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts.archgate/adrs/LEGAL-002-dependency-license-compatibility.md
📜 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 (2)
.archgate/adrs/**/*.rules.ts
📄 CodeRabbit inference engine (.archgate/adrs/GEN-004-concise-forward-only-code-comments.md)
.archgate/adrs/**/*.rules.ts: Comments in.archgate/adrs/**/*.rules.tsmust be concise, forward-only, and limited to current behavior; historical or relocation narration is prohibited.
Changes to narration or relocation detection patterns in companion.rules.tsfiles must be synchronized with.archgate/lint/oxlint.ts, and both enforcement layers must continue to report violations at error severity.
Files:
.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts.archgate/adrs/ARCH-015-cli-command-documentation-coverage.rules.ts
.archgate/{lint,adrs}/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/GEN-004-concise-forward-only-code-comments.md)
.archgate/{lint,adrs}/**/*.ts: A contiguous run of whole-line comments must contain at most five lines of narrative prose, including in lint and companion rule implementations.
Use the same synchronized structural-TSDoc exemption in Archgate TypeScript files; narrative must not be relabeled with prose-container tags to evade the limit.
Files:
.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts.archgate/adrs/ARCH-015-cli-command-documentation-coverage.rules.ts
🧠 Learnings (5)
📓 Common learnings
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:19:02.047Z
Learning: Exceptions to the no-barrel-file and no-re-export rule require lead architect approval and must be documented in a separate ADR explaining the specific necessity.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:19:06.857Z
Learning: Reuse existing type definitions and shared constants for option unions and `Record` keys rather than duplicating literals.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:19:22.994Z
Learning: The rule covers English website documentation only; localized mirrors are governed separately by GEN-002, and plugin-repository `commands.md` files require manual synchronization.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:19:22.994Z
Learning: Code reviewers must verify that added subcommands receive a parent-page heading, removed subcommands have their heading deleted, and the plugin skill reference is updated in the same change.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:19:41.242Z
Learning: Do not treat a successful `archgate check` as proof that the sandbox boundary is secure; behavioral security must be established by escape tests and review.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:19:41.242Z
Learning: Any proposal to widen the module allowlist beyond the four approved `node:` modules, follow imports transitively, or remove import-time scanning requires a separate approved ADR.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:19:46.777Z
Learning: Enable and maintain Renovate or Dependabot updates for SHA-pinned GitHub Actions so pinned dependencies receive security updates.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:19:46.777Z
Learning: Use local workflow references for internal reusable workflows and do not pin them by SHA.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:19:46.777Z
Learning: Any additional exception to SHA pinning must be evaluated case by case, documented with an explicit justification, and added to the enforcement rule’s allowlist before merging; silent exceptions are not permitted.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:19:46.777Z
Learning: Code reviewers must verify that each new or updated third-party `uses:` reference uses a full SHA, has an accurate exact-tag comment, and was resolved from a trusted source.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:19:58.975Z
Learning: Human reviewers must verify translation accuracy and naturalness, preservation of English technical content and MDX structure, locale-neutral links, and same-PR translations for new English pages.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:20:03.887Z
Learning: Run `bun run validate` before pushing or opening a pull request instead of running individual validation steps when the script is available.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:20:03.887Z
Learning: Do not pass ad hoc custom flags to linting or formatting commands; project-specific flags, targets, and ignore patterns must remain encoded in `package.json` scripts.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:20:03.887Z
Learning: Do not add JavaScript or TypeScript linting or formatting tools without corresponding `package.json` scripts; external non-npm CI binaries are outside this requirement.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:20:08.509Z
Learning: The `LEGAL-002/no-copyleft-deps` rule must scan all direct and transitive packages in `node_modules/`, reject licenses outside the approved allowlist with error severity, and run as part of `archgate check` / `bun run validate`.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-05T05:20:08.509Z
Learning: Dependency additions in pull requests should include confirmation of license compatibility, and newly encountered permissive licenses should be added to the LEGAL-002 allowlist with justification.
📚 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-015-cli-command-documentation-coverage.md.archgate/adrs/ARCH-008-typed-command-options.md.archgate/adrs/LEGAL-002-dependency-license-compatibility.md.archgate/adrs/ARCH-012-command-error-boundaries.md.archgate/adrs/ARCH-001-command-structure.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-015-cli-command-documentation-coverage.md.archgate/adrs/ARCH-008-typed-command-options.md.archgate/adrs/LEGAL-002-dependency-license-compatibility.md.archgate/adrs/ARCH-012-command-error-boundaries.md.archgate/adrs/ARCH-001-command-structure.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-015-cli-command-documentation-coverage.md.archgate/adrs/ARCH-008-typed-command-options.md.archgate/adrs/LEGAL-002-dependency-license-compatibility.md.archgate/adrs/ARCH-012-command-error-boundaries.md.archgate/adrs/ARCH-001-command-structure.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-015-cli-command-documentation-coverage.md.archgate/adrs/ARCH-008-typed-command-options.md.archgate/adrs/LEGAL-002-dependency-license-compatibility.md.archgate/adrs/ARCH-012-command-error-boundaries.md.archgate/adrs/ARCH-001-command-structure.md
🪛 OpenGrep (1.26.0)
.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts
[ERROR] 86-86: Dynamic command passed to child_process.exec/execSync. Use child_process.execFile or spawn with an argument array instead.
(coderabbit.command-injection.exec-js)
.archgate/adrs/ARCH-015-cli-command-documentation-coverage.rules.ts
[ERROR] 76-76: 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 (8)
.archgate/adrs/ARCH-001-command-structure.md (1)
42-42: LGTM!Also applies to: 62-80, 117-119, 134-149
.archgate/adrs/ARCH-012-command-error-boundaries.md (1)
15-15: LGTM!Also applies to: 30-32, 41-43, 59-68
.archgate/adrs/ARCH-008-typed-command-options.md (1)
60-87: LGTM!Also applies to: 139-139
.archgate/adrs/LEGAL-002-dependency-license-compatibility.md (1)
71-71: LGTM!.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md (1)
76-76: LGTM!Also applies to: 83-83, 94-94
.archgate/adrs/ARCH-015-cli-command-documentation-coverage.rules.ts (1)
12-20: LGTM!Also applies to: 41-62, 89-110
.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts (2)
86-86: 🎯 Functional CorrectnessVerify the case policy for the
archgateheading marker.The parser lowercases command tokens, but the heading regex matches only lowercase
archgate. If matching is case-insensitive,#### Archgate adr createis ignored. Add theiflag or document and test lowercase-only matching.
24-57: LGTM!Also applies to: 59-80, 99-108, 110-128
registerMCPServerCommand normalizes to mcp-server, matching the module filename convention for acronym-bearing command names. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
1 participant
Resolves all nine open
documentation-labeled issues in one pass. Every claim was first re-validated against currentmain(ae2b988); the fixes below reflect what actually held up, and the Validation notes section records where the issues' claims did not.Closes #502
Closes #503
Closes #504
Closes #505
Closes #506
Closes #507
Closes #508
Closes #509
Closes #510
What changed
main().catchDO, snippet, and Good Example now show the real three-branch handler (ExitPromptError→130,UserError→1, else Sentry+2, always viaexitWith()); ARCH-002 routes unexpected errors to the command boundary instead of a "natural crash"; ARCH-012's Decision and pattern namehandleCommandError()as the boundary mechanism.adr domain add/list/removeare now enforced, with new headings inadr.mdxacross en/nb/pt-br). Orphan detection is scoped to paths whose parent chain is group directories, so in-module subcommands (session-context <editor> list/show) stay legal and are documented as manual-review territory. ARCH-015's rule additionally cross-checksregister*Command(program)calls insrc/cli.tsagainst the module layout in both directions. Both rules fire-tested in both directions.default, real five-editorEDITOR_TARGETSunion); the Consequences overclaim corrected.no-copyleft-deps) unchanged.parseJsModuleas the parse primitive actually shared by the scanner andctx.ast(), and restores the entry-point convergence statement; ARCH-024 describesscanImportedRuleSource()as the pure pass-through it is. Newtests/engine/rule-scanner-escapes-convergence.test.tsruns one payload corpus (every blocked category + clean controls) through both entry points asserting deeply-equal results — ARCH-024's convergence guarantee is now executable, not prose.checksums.txtreferences now name the exact asset (actionlint_<version>_checksums.txt); GEN-003 carries the CI-only external-binary exception bidirectionally (Scope, Don'ts, Exceptions, References cross-linking CI-002).error-severity rules blocked anyway) is removed.Portuguêslabel diacritic fixed.Validation notes (where the issues' claims did not hold)
.github/workflows/**verified as genuine commit objects via the GitHub API. The hazard is real, though —pypa/gh-action-pypi-publish@v1.14.0resolves to a tag object (6733eb7d…) via the ADR's old one-step command, while the repo correctly pins the dereferenced commit (cef22109…).scanImportedRuleSource()is a one-line pass-through); ARCH-022 was the one naming the wrong shared helper — and the 2026-07-26 prose trim had removed its entry-point mention entirely.Verification
bun run validatepasses end-to-end (lint, typecheck, format:check, 1971 tests incl. 54 new convergence tests,archgate check50/50 with zero briefing-budget warnings, knip, build check).