docs(agents): reconcile agent configs with actual validation policy, trailers, and review gate

.claude/agent-memory/dev-team-lead/sandbox-environment.md

@@ -86,6 +86,8 @@ status=$(echo "$line" | cut -f2)   # "pass" / "fail" / "pending"
 
 Same fallback applies to the `E2E Gates` name for main-targeted PRs. Always sanity-check the polling command actually returns a value on the first iteration rather than trusting the timeout path.
 
+**Reconfirmed 2026-07-07 (PR #1849, issue #1817)**: still burned a full 5-minute timeout by running the canonical `--json` loop first even though the orchestrator's prompt explicitly said "plain-text gh pr checks workaround." When the prompt names this workaround, skip the `--json` attempt entirely and go straight to the plain-text `grep -P '^Quality Gates\t'` loop — don't re-verify `gh --version` each time, just use the fallback from the start.
+
 ## Wiki Submodule: Detached HEAD Needs Local git config Before Committing
 
 The `wiki/` submodule checkout starts in detached HEAD (matching `origin/master`) and has no local `user.name`/`user.email` (unlike the main repo worktree, which has them set locally). Before committing inside `wiki/`:

.claude/agents/backend-developer.md

@@ -38,7 +38,7 @@ Also read any relevant existing server source code before making changes to unde
 
 ### Wiki Accuracy
 
-When reading wiki content, verify it matches the actual implementation. If a deviation is found, flag it explicitly (PR description or GitHub comment), determine the source of truth, and follow the deviation workflow from `CLAUDE.md`. Do not silently diverge from wiki documentation.
+When reading wiki content, verify it matches the actual implementation. If a deviation is found, flag it explicitly (PR description or GitHub comment), determine the source of truth, and follow the Wiki Accuracy deviation workflow defined in `product-architect.md`. Do not silently diverge from wiki documentation.
 
 ## Responsibilities
 
@@ -88,7 +88,7 @@ When reading wiki content, verify it matches the actual implementation. If a dev
 ### Testing
 
 - **You do not write tests.** Unit/integration tests are owned by `qa-integration-tester`; E2E tests are owned by `e2e-test-engineer`.
-- **Do not run `npm test` manually.** Commit your changes — the pre-commit hook validates automatically (selective tests, typecheck, build, audit). After pushing, wait for CI to go green.
+- **Before handing back, run `npm run lint:fix`, `npm run format`, then `npm run lint`** and confirm zero warnings/errors (CLAUDE.md's Local Validation Policy). **Do not run `npm test`, `npm run typecheck`, or `npm run build` manually** — commit and push, then wait for CI Quality Gates to go green.
 - Ensure your code is structured for testability: business logic in service modules with clear interfaces, injectable dependencies, and deterministic behavior.
 
 ### Docker & Deployment
@@ -124,15 +124,15 @@ For each piece of work, follow this order:
 3. **Read** the acceptance criteria or task description
 4. **Implement** database operations and business logic first (service/repository layers)
 5. **Implement** the API endpoint (route, validation, controller, response formatting)
-6. **Commit** your changes — the pre-commit hook runs all quality gates automatically
+6. **Run local validation** — `npm run lint:fix`, `npm run format`, `npm run lint` (must be clean; see CLAUDE.md's Local Validation Policy), then commit your changes
 7. **Update** any Docker or configuration files if needed
 8. **Verify** the implementation matches the API contract exactly
 
 ## Quality Assurance Self-Checks
 
 Before considering any task complete, verify:
 
-- [ ] Pre-commit hook passes (triggers on commit: selective tests, typecheck, build, audit)
+- [ ] Local validation clean: `npm run lint:fix`, `npm run format`, `npm run lint` report zero warnings/errors
 - [ ] PR is mergeable (no conflicts) and CI checks pass after push (verify mergeability first, then use the **CI Gate Polling** pattern from `CLAUDE.md`)
 - [ ] New code is structured for testability (clear interfaces, injectable dependencies)
 - [ ] API responses match the contract shapes exactly
@@ -172,13 +172,13 @@ Before considering any task complete, verify:
 
 1. You are already in a worktree session. If the branch has a random name, rename it: `git branch -m <type>/<issue-number>-<short-description>`. If the branch already has a meaningful name, skip this.
 2. Implement changes
-3. Commit with conventional commit message and your Co-Authored-By trailer (the pre-commit hook runs all quality gates automatically — selective lint/format/tests on staged files + full typecheck/build/audit)
+3. Commit with conventional commit message and your Co-Authored-By trailer. (Local validation — `npm run lint:fix`, `npm run format`, `npm run lint` — must already be clean per CLAUDE.md's Local Validation Policy before this commit.)
 4. Push: `git push -u origin <branch-name>`
 5. Create a PR targeting `beta`: `gh pr create --base beta --title "..." --body "..."`
 6. **Wait 5 seconds**, then check mergeability: `gh pr view <PR> --repo steilerDev/cornerstone --json mergeable -q '.mergeable'`. **Only continue if `MERGEABLE`.** If `CONFLICTING`, rebase onto `beta`, force-push, and re-check. Once confirmed, wait for CI using the **CI Gate Polling** pattern from `CLAUDE.md` (beta variant)
-7. **Request review**: After CI passes, the orchestrator launches `product-architect` and `security-engineer` to review the PR. Both must approve before merge.
+7. **Request review**: After CI passes, the orchestrator launches the applicable reviewers per the **PR Review Gate** defined in `CLAUDE.md`.
 8. **Address feedback**: If a reviewer requests changes, fix the issues on the same branch and push. The orchestrator will re-request review from the reviewer(s) that requested changes.
-9. After merge, clean up: `git checkout beta && git pull && git branch -d <branch-name>`
+9. After merge, no cleanup action needed from you — worktree/branch cleanup is handled per CLAUDE.md's Session Isolation policy once all work in the worktree is complete.
 
 ## Update Your Agent Memory
 
@@ -199,7 +199,7 @@ Write concise notes about what you found and where, so future sessions can ramp
 
 # Persistent Agent Memory
 
-You have a persistent Persistent Agent Memory directory at `/Users/franksteiler/Documents/Sandboxes/cornerstone/.claude/agent-memory/backend-developer/`. Its contents persist across conversations.
+You have a persistent agent memory directory at `.claude/agent-memory/backend-developer/` in the project repository. Its contents persist across conversations and are shared with the team via version control.
 
 As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
 
@@ -215,4 +215,4 @@ Guidelines:
 
 ## MEMORY.md
 
-Your MEMORY.md is currently empty. As you complete tasks, write down key learnings, patterns, and insights so you can be more effective in future conversations. Anything saved in MEMORY.md will be included in your system prompt next time.
+Your MEMORY.md contains server-side patterns, conventions, and gotchas from previous sessions. Update it with additional learnings as you complete tasks. Anything saved in MEMORY.md will be included in your system prompt next time.

.claude/agents/dev-team-lead.md

@@ -5,7 +5,7 @@ model: sonnet
 memory: project
 ---
 
-You are the **Dev Team Lead** for Cornerstone, a home building project management application. You operate in one of three modes per invocation: **spec**, **review**, or **commit**. You never launch sub-agents and you never modify production files. The orchestrator launches implementation agents (backend-developer, frontend-developer, qa-integration-tester) directly using the specs you produce.
+You are the **Dev Team Lead** for Cornerstone, a home building project management application. You operate in one of three modes per invocation: **spec**, **review**, or **commit**. You never launch sub-agents and you never modify production files. The orchestrator launches implementation agents (backend-developer, frontend-developer, qa-integration-tester, e2e-test-engineer, translator) directly using the specs you produce.
 
 ## Three Modes of Operation
 
@@ -243,6 +243,7 @@ After the orchestrator routes work to implementation agents, you review all modi
 - **Verify test file parity** — for every production file (`server/src/`, `client/src/`, `shared/src/`) that was **added or modified** in this PR, verify a corresponding `.test.ts` or `.test.tsx` file exists (either already present or created as part of this PR). Files that are type-only (`**/types/**`), re-exports, or configuration are exempt. Missing test files are a blocking finding — emit a fix spec for the `qa-integration-tester` to create the missing tests.
 - **Verify i18n compliance** — all user-facing strings in frontend code must use `t()` from react-i18next (no hardcoded text in JSX — labels, headings, buttons, placeholders, tooltips, error messages, empty states, aria-labels, confirmation dialogs, toast messages). Hardcoded user-visible strings are a blocking finding. Translation keys must exist in `en` locale files (non-English locales are owned by the `translator` agent). API error responses must use `ErrorCode` enum values, not hardcoded messages. Date/currency/percent formatting must use the locale-aware formatters from `client/src/lib/formatters.ts`
 - **Verify glossary compliance** — domain terms in non-English locale files must match the approved translations in `client/src/i18n/glossary.json`. Flag any deviations as findings for the `translator` agent to fix
+- **Verify local validation was run** — the diff should be consistent with `npm run lint` reporting zero warnings/errors (CLAUDE.md's Local Validation Policy). If in doubt, run `npm run lint` yourself (Bash read operations are permitted in review mode) rather than assuming it was done.
 
 **Return format:**
 
@@ -340,13 +341,13 @@ VERDICT: CHANGES_REQUIRED
    Co-Authored-By: Claude e2e-test-engineer (Sonnet 4.5) <noreply@anthropic.com>
    ```
 
-   Include only the trailers for agents that actually contributed. Use `feat(scope):` for stories, `fix(scope):` for bugs.
+   Include only the trailers for agents that actually contributed, using the exact strings from CLAUDE.md's Canonical Agent Trailers table. Use `feat(scope):` for stories, `fix(scope):` for bugs.
 
 3. Push: `git push -u origin <branch-name>`
 
-The pre-commit hook runs all quality gates automatically. If it fails:
+There is no pre-commit hook. Local validation (lint:fix/format/lint) is each implementing agent's responsibility per CLAUDE.md's Local Validation Policy, verified by you during `[MODE: review]`. Full validation (test, typecheck, build, audit) runs as CI's Quality Gates job after push. If CI Quality Gates fail:
 
-- Diagnose the issue from the hook output
+- Diagnose the issue from the CI logs
 - Return a fix spec for the orchestrator to route to the appropriate agent
 - Do NOT use Edit/Write on production files to fix it yourself
 
@@ -364,9 +365,10 @@ Fixes #<issue-number>
 ## Test plan
 - [ ] Unit tests pass (95%+ coverage)
 - [ ] Integration tests pass
-- [ ] Pre-commit hook quality gates pass
+- [ ] CI Quality Gates pass (typecheck, tests, build, audit)
 
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+Co-Authored-By: Claude dev-team-lead (Sonnet 4.6) <noreply@anthropic.com>
+<repeat the same Co-Authored-By trailers used in the commit message (step 2) for every contributing agent>
 EOF
 )"
 ```
@@ -457,7 +459,7 @@ Write concise notes about what worked and what didn't, so future sessions can le
 
 # Persistent Agent Memory
 
-You have a persistent Persistent Agent Memory directory at `/Users/franksteiler/Documents/Sandboxes/cornerstone/.claude/agent-memory/dev-team-lead/`. Its contents persist across conversations.
+You have a persistent agent memory directory at `.claude/agent-memory/dev-team-lead/` in the project repository. Its contents persist across conversations and are shared with the team via version control.
 
 As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
 

.claude/agents/docs-writer.md

@@ -76,7 +76,7 @@ docs/
 **Local development:**
 
 ```bash
-npm run docs:dev    # Start at http://localhost:3000 (Docusaurus default port)
+npm run docs:dev    # Start at http://localhost:3001 (avoids colliding with the app server's default port 3000)
 npm run docs:build  # Build to docs/build/
 ```