Update developer docs and agent workflow reference

AGENTS.md

@@ -1,14 +1,14 @@
 # AGENTS.md
 
-> Primary entry point for AI agents integrating the resolver as a skill.
-> Deep reference is in **[agents-docs/](agents-docs/README.md)**.
+> AI agent integration reference for the web doc resolver.
+> Deep reference is in **[agents-docs/README.md](agents-docs/README.md)**.
 
 ## Named Constants
 
 ```bash
 readonly MAX_LINES_PER_SOURCE_FILE=500
 readonly MAX_LINES_PER_SKILL_MD=250
-readonly MAX_LINES_AGENTS_MD=200
+readonly MAX_LINES_AGENTS_MD=150
 readonly DEFAULT_MAX_RETRIES=3
 readonly DEFAULT_RETRY_DELAY_SECONDS=5
 readonly DEFAULT_POLL_INTERVAL_SECONDS=5
@@ -63,16 +63,10 @@ After every completed task, append to `.agents/metrics.jsonl`:
 }
 ```
 
-Append-only. Never truncate. dora-report reads this file.
-
 ## YAML Workflow Style Rule
 
 All `.github/workflows/*.yml` must include `# yamllint disable-line rule:truthy` on the `on:` line.
 
-## Session Bootstrap
-
-`docflow.json` drives context injection at agent startup. `hooks/session-start.sh` can be run manually to verify environment readiness.
-
 ## Repository Structure
 
 ```text
@@ -106,82 +100,16 @@ Detailed reference material in `agents-docs/`:
 
 ## Coding Workflow
 
-### Branching & Commits
-
-- Branch naming: `feat/`, `fix/`, `chore/`, `docs/`
-- Commit format: Conventional Commits (`type(scope): description`)
-
-### PR Checklist
-
-- `./scripts/quality_gate.sh` passes
-- Linting clean (`ruff`, `black`, `cargo fmt`, `cargo clippy`, `npm run lint`)
-- No new secrets (verified via Gitleaks)
-- `AGENTS.md` updated if structure changed
-
-### CI & Codacy Rules (NEVER SKIP)
-
-**ALL GitHub Actions checks MUST pass before merge.** No exceptions.
-
-**Codacy MUST be up to standards before merge.** If Codacy shows `ACTION_REQUIRED`:
-
-#### Codacy Issue Resolution Protocol
-
-**NEVER skip, suppress, or ignore Codacy issues without following this protocol:**
-
-1. **Analyze**: Run `codacy pull-request gh <org> <repo> <prN> --output json` to get all issues
-2. **Research**: For each issue, web-research the pattern against official docs and best practices:
-   - Check the rule's official documentation (ESLint, Biome, Semgrep, etc.)
-   - Determine if it's a genuine code quality concern or a false positive
-   - Document findings in the PR description or comments
-3. **Fix**: If the issue is genuine, fix the code. Commit, push, re-verify.
-4. **Verify**: Confirm the fix resolves the issue without introducing regressions
-5. **Ignore (last resort only)**: If and only if the issue is a verified false positive:
-   - Document WHY it's a false positive (with links to docs/best practices)
-   - Use `codacy pull-request gh <org> <repo> <prN> --ignore-issue <resultDataId> --ignore-reason FalsePositive`
-   - Add an inline comment explaining the rationale
-
-**Key principles:**
-
-- Fix first, ignore never (unless verified false positive)
-- Always document the reasoning behind any decision
-- Never assume an issue is a false positive without verification
-- Web research against official docs is mandatory before dismissing any issue
-
-**Never merge with:**
-
-- Any failing GitHub Action (even if "pre-existing on main")
-- Codacy `ACTION_REQUIRED` status
-- Merge conflicts
-- Required reviews missing
-
-### Test Commands
-
-- **Python**: `pytest -m "not live"`
-- **Rust**: `cd cli && cargo test`
-- **Web**: `cd web && npx playwright test --project=desktop --project=mobile --project=tablet`
-
-## Release Workflow
-
-> **Do NOT use `gh release create` manually.** The CI/CD pipeline handles releases automatically.
-
-### Correct Release Steps
-
-```bash
-# 1. Bump versions
-python scripts/sync_versions.py --set $VERSION
-
-# 2. Commit
-git add -A && git commit -m "chore(release): v$VERSION"
-
-# 3. Tag and push (triggers CI/CD)
-git tag -a v$VERSION -m "Release v$VERSION"
-git push origin main --tags
-```
-
-### What CI/CD Does Automatically
-
-- Runs Python + Rust test suites
-- Builds binaries: Linux x86_64, macOS aarch64, Windows x86_64
-- Generates build attestations
-- Extracts changelog from `CHANGELOG.md`
-- Creates GitHub release with binaries + install instructions
+- **Branch Naming**: Prefix branches with `feat/`, `fix/`, `chore/`, or `docs/`.
+- **Commit Format**: Conventional Commits style: `type(scope): description`.
+- **PR Checklist**:
+  1. All tests must pass successfully.
+  2. Linting must be completely clean (`ruff`, `ruff-format`, `cargo fmt`, `cargo clippy`, `npm run lint`).
+  3. Verify that no new secrets are introduced (via Gitleaks).
+  4. Ensure `AGENTS.md` is updated if there are structural or tree modifications.
+- **Quality Gate Command**: `./scripts/quality_gate.sh`
+- **Test Commands per Layer**:
+  - Python: `pytest -m "not live"`
+  - Rust: `cd cli && cargo test`
+  - Web: `cd web && npx playwright test --project=desktop`
+- **File Size Limit**: Source files must not exceed 500 lines max per source file.

CONTRIBUTING.md

@@ -5,57 +5,73 @@
 ### Python
 
 ```bash
-# Run tests
+# Run unit and integration tests
 python -m pytest tests/ -v -m "not live"
 
-# Linting and formatting
+# Linting and formatting checks
 python -m ruff check .
-python -m black .
+python -m ruff format --check .
+
+# Auto-format code
+python -m ruff format .
+python -m ruff check --fix .
 ```
 
 ### Rust CLI
 
 ```bash
 cd cli
+
+# Run tests
 cargo test
+
+# Check clippy warnings
 cargo clippy -- -D warnings
-cargo fmt
+
+# Format check
+cargo fmt -- --check
 ```
 
 ### Web UI
 
 ```bash
 cd web
+
+# Run linter
 npm run lint
+
+# Check TypeScript types
 npm run typecheck
+
+# Run Playwright E2E browser tests
 npx playwright test --project=desktop
 ```
 
 ### Quality Gate
 
-Run the full suite before submitting:
+Always execute the local quality gate script to verify all requirements before committing:
 
 ```bash
 ./scripts/quality_gate.sh
 ```
 
 ## Standards
 
-- **Python**: Follow Black formatting and Ruff rules. Use type hints for public functions.
-- **Rust**: Ensure `cargo clippy` and `cargo fmt` pass.
-- **Commits**: Use [Conventional Commits](https://www.conventionalcommits.org/):
+- **Python**: Adhere to Ruff formatting and linting rules. Use explicit type hints for all public functions.
+- **Rust**: Ensure `cargo clippy` and `cargo fmt` pass without warnings.
+- **Commits**: Follow Conventional Commits format (`type(scope): description`):
   - `feat:` new feature
   - `fix:` bug fix
-  - `docs:` documentation
-  - `chore:` maintenance
-  - `refactor:` code restructuring
-  - `test:` test updates
-- **Branching**: Use `feat/`, `fix/`, `chore/`, or `docs/` prefixes.
-- **File Size**: Source files must not exceed 500 lines. Split into sub-modules if they grow larger.
+  - `docs:` documentation updates
+  - `chore:` maintenance and dependency updates
+  - `refactor:` code restructuring without behavior changes
+  - `test:` test additions or modifications
+- **Branching**: Prefix development branches with `feat/`, `fix/`, `chore/`, or `docs/`.
+- **File Size Limit**: Source files must not exceed 500 lines. Refactor and partition into sub-modules if they exceed this limit.
 
 ## Pull Request Process
 
-1. Update documentation for user-facing changes.
-2. Add tests for new features or bug fixes.
-3. Ensure the quality gate passes: `./scripts/quality_gate.sh`.
-4. Update `AGENTS.md` if repository structure or skills change.
+1. Document any user-facing changes in the appropriate docs/ guides.
+2. Add unit or integration tests for new functionality.
+3. Verify that the quality gate script runs successfully: `./scripts/quality_gate.sh`.
+4. Update `AGENTS.md` if repository structure or skill definitions are modified.