Refresh repository documentation guidance#88
Conversation
Import the latest agent and documentation style guidance from the Rust agent template, then add the canonical documentation contents and repository layout files required by the refreshed instructions.
|
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:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
A detailed high-level summary could not be generated for this review. Here is an overview derived from the analyzed file changes:
WalkthroughThis PR restructures Corbusier's documentation governance and establishes canonical project navigation. AGENTS.md receives substantive expansion with new development policies (abstraction/port/helper evaluation, dependency management, observability instrumentation, project documentation destinations). Two new foundational documents—docs/contents.md (documentation index) and docs/repository-layout.md (directory structure)—become canonical references. docs/documentation-style-guide.md is updated to enforce those new references and substantially expands roadmap task-writing guidance. Mermaid ER diagrams are standardised to uppercase naming conventions. Frontend testing infrastructure gains TypeScript type safety through Vitest accessibility matcher augmentations, test-scoped configuration, and Bun runtime synchronisation across tooling and CI. Orchestrator execution lock invariants are documented and session expiration handling is optimised. ChangesDocumentation governance and project structure canonicalisation
Frontend testing infrastructure upgrade
Orchestrator execution lock documentation and optimisation
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 20✅ Passed checks (20 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Reviewer's GuideRefreshes repository documentation guidance to align with the shared Rust agent template by updating AGENTS instructions, tightening documentation-style rules, and adding canonical docs index and repository layout files for navigation and path responsibilities. Flow diagram for updated documentation navigation and responsibilitiesflowchart LR
AGENTS_md[AGENTS.md
agent instructions]
Contents_md[docs/contents.md
documentation index]
Repo_layout_md[docs/repository-layout.md
path responsibilities]
Style_guide_md[docs/documentation-style-guide.md]
Users_guide_md[docs/users-guide.md]
Developers_guide_md[docs/developers-guide.md]
Roadmap_md[docs/roadmap.md]
Design_docs[Design documents
docs/*-design.md]
ADRs[ADRs
docs/adr-*.md]
RFCs[RFCS
docs/rfcs/]
Execplans[Execution plans
docs/execplans/]
AGENTS_md --> Contents_md
AGENTS_md --> Style_guide_md
Contents_md --> Repo_layout_md
Contents_md --> Users_guide_md
Contents_md --> Developers_guide_md
Contents_md --> Roadmap_md
Contents_md --> Design_docs
Contents_md --> ADRs
Contents_md --> RFCs
Contents_md --> Execplans
AGENTS_md --> Design_docs
AGENTS_md --> ADRs
AGENTS_md --> Users_guide_md
AGENTS_md --> Developers_guide_md
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Rename ER diagram aliases that conflict with the Mermaid parser so `nixie` can validate the documentation set. Keep the underlying field names and explanatory text unchanged.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
|
@coderabbitai resume |
Add developer-guide coverage for the refreshed agent instructions: quality gates, abstraction policy, dependency rules, error handling, observability, and local tooling expectations.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Pin the frontend esbuild resolution to the patched 0.28 line and update the PostgreSQL Rust dependency chain to versions that address new RustSec advisories reported by make audit.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Add a frontend test TypeScript project so test-only setup files are covered by the typecheck gate. Update the a11y matcher augmentation and local jest-axe declaration to match the Vitest assertion surface used by the accessibility tests.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
@coderabbitai resume |
✅ Action performedReviews resumed. |
Add an explicit maintainer-requirements map from the updated AGENTS.md policy areas to the developer guide sections that document tooling, dependency management, error handling, observability, and abstraction rules.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
Align the CI Bun setup and frontend package manager metadata with the Bun version that reports a clean audit for the current dependency graph. The reported shell-quote path is not present in the repository lockfile, so avoid adding an unused dependency override.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Add concise documentation for the local jest-axe ambient types, frontend accessibility TypeScript setup, and the full-turn session execution lock invariant.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
Clarify that `make frontend-typecheck` runs the frontend TypeScript validation in base and test-scoped passes, and record why the test configuration exists for accessibility setup and ambient types.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
@coderabbitai resume |
✅ Action performedReviews resumed. |
Add an inline note before the per-conversation execution lock is acquired so callers can see why the guard spans the full turn and where the detailed rationale lives.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Move the turn-session reservation directly into the expiry path after an upsert failure, since the function returns immediately afterwards.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Use the full inline rationale requested at the turn execution lock site and keep the orchestrator module within the existing line-count lint by removing blank spacer lines only.
|
@coderabbitai Have the following now been resolved? frontend-pwa/package.json (1)
🤖 Detailed instructionsVerify each finding against current code. Fix only still-valid issues, skip the In Source: Coding guidelines |
|
@coderabbitai Have the following now been resolved? ❌ Module-Level Documentation —
|
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "=== docs/developers-guide.md (TypeScript / typecheck section) ==="
grep -n -A 40 -i "typescript type checking\|typecheck\|tsconfig.test\|dual" docs/developers-guide.md | head -80
echo ""
echo "=== frontend-pwa/package.json lines 15-25 ==="
sed -n '15,25p' frontend-pwa/package.json
echo ""
echo "=== Full developers-guide.md for context ==="
cat docs/developers-guide.mdLength of output: 15459
✅ Document the test-scoped typecheck configuration —
|
| Requirement | Status |
|---|---|
make frontend-typecheck runs dual tsc passes |
✅ Lines 166–168 |
tsconfig.test.json widens scope to src/, tests/, Vite/Vitest/Playwright configs |
✅ Lines 163–165 |
| Rationale for the separate test pass | ✅ Lines 170–172 |
Cross-reference to jest-axe.d.ts ambient declarations |
✅ Lines 174–178 |
Cross-reference to setup-vitest-a11y.ts Vitest augmentation |
✅ Lines 180–184 |
The typecheck script in package.json (tsc --noEmit && tsc --project tsconfig.test.json --noEmit) matches the documentation exactly.
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "=== frontend-pwa/tests/types/jest-axe.d.ts ==="
cat frontend-pwa/tests/types/jest-axe.d.ts
echo ""
echo "=== docs/developers-guide.md ==="
cat docs/developers-guide.md
echo ""
echo "=== src/agent_backend/services/orchestrator/execution_locks.rs ==="
cat src/agent_backend/services/orchestrator/execution_locks.rs
echo ""
echo "=== _execution_guard acquisition in mod.rs ==="
rg -n "_execution_guard\|execution_locks\.lock" src/agent_backend/services/orchestrator/mod.rs -A8 -B5Length of output: 15519 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "=== Search for execution_guard in mod.rs ==="
grep -n "execution_guard\|execution_lock\|_guard\|per-conversation\|per-session\|lock" \
src/agent_backend/services/orchestrator/mod.rs | head -40
echo ""
echo "=== Full execute_turn function context ==="
rg -n "fn execute_turn" src/agent_backend/services/orchestrator/mod.rs -A 40Length of output: 3234
✅ Module-Level Documentation —
|
1 participant
Summary
This branch refreshes the repository's agent and documentation guidance from the current Rust agent template, then adds the canonical documentation contents and repository layout files required by that guidance. The update keeps contributor instructions, documentation style rules, and documentation navigation aligned with the shared template.
It also renames Mermaid entity aliases in docs/corbusier-design.md where
merman-clitreats parser-reserved words as invalid ER entity names.The branch now also resolves dependency audit failures by pinning frontend
esbuildresolution to the patched0.28line and updating the Rust PostgreSQL dependency chain throughtokio-postgres/postgres-protocolpatched releases.No issue, roadmap task, or execplan is associated with this branch.
Review walkthrough
AGENTS.md.Validation
make check-fmt: passed.make lint: passed.make test: passed, 902 tests passed and 1 skipped.make audit: passed; Rust audit reports only the existing allowed warnings.make frontend-lint: passed, with an informational Biome schema-version notice.make frontend-typecheck: passed.make frontend-test: passed, 8 files and 41 tests passed.make frontend-test-a11y: passed, 1 file and 2 tests passed.make frontend-localizability: passed.make frontend-semantic: passed, with the same informational Biome schema-version notice.make markdownlint: passed.make nixie: passed.make --no-print-directory markdownlint nixie: passed after the Mermaid alias repair./home/leynos/.bun/bin/markdownlint-cli2 AGENTS.md docs/documentation-style-guide.md docs/contents.md docs/repository-layout.md: passed.Notes
make fmtwas run as required after documentation changes, but the target exits non-zero after rewriting unrelated existing documentation and reporting five pre-existing line-length findings in docs/corbusier-api-design.md, docs/execplans/2-2-2-associate-branches-and-pull-requests-with-tasks.md, and docs/execplans/3-1-2-tool-discovery-and-routing.md. Those formatter side effects were restored so this branch remains scoped to the requested documentation import, diagram validation repair, developer-guide alignment, and audit remediation.