basant307/AI_Governance_Project

1# AGENTS.md2 3This file provides guidance to Qwen Code when working with code in this4repository.5 6## Working Principles7 8### Simplicity First9 10**Minimum code that solves the problem. Nothing speculative.**11**(This is the principle we care about most.)**12 13- No features beyond what was asked.14- No abstractions for single-use code.15- No "flexibility" or "configurability" that wasn't requested.16- No error handling for impossible scenarios.17- If you write 200 lines and it could be 50, rewrite it.18 19Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes,20simplify.21 22_Adapted from Andrej Karpathy's [CLAUDE.md](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md)._23 24### Core Infrastructure Is Maintainer-Only (triage gate, two-tier rule)25 26Core modules — `packages/core/src/**`, `packages/*/src/auth/**`,27`packages/*/src/providers/**`, `packages/*/src/models/**`,28`packages/*/src/config/**`, `packages/*/src/tools/**`,29`packages/*/src/services/**`, cross-package changes — are the architectural30backbone. External PRs touching them face a two-tier gate (maintainer-authored31PRs are exempt):32 331. **Large-scope `refactor` changes (500+ production logic lines in core,34   excluding test and generated/schema files) → hard block.**35   Skip evaluation entirely — the maintainer exemption above is the sole36   exception. Large-scale core refactors must be maintainer-initiated.37   When counting lines, exclude files matching `*.test.ts`, `*.test.tsx`,38   `*.spec.ts`, `*.spec.tsx`, `__tests__/**`, `*.schema.ts`, `*.schema.json`,39   `*.generated.ts`, and `**/generated/**` — only production logic counts.40   `feat`-type and other non-`refactor` PRs are NOT hard-blocked on size; they41   escalate to the maintainer for awareness instead. A non-blocking advisory42   also applies at 1000+ production logic lines. Breadth alone is not size — a43   low-risk sweep that touches 10+44   files but changes a line or two each is escalated to a maintainer for45   awareness and otherwise judged under Tier 2's 100%-confidence bar, not46   auto-rejected on file count.472. **Small-scope changes → gate may evaluate, but must be 100% confident.**48   Any doubt at all → escalate to maintainer. "The direction looks correct"49   is not confidence. The gate must name every downstream consumer; if it50   cannot, escalate.51 52**When in doubt, escalate. Better to wrongly escalate than to wrongly53approve.**54 55## Common Commands56 57### Building58 59```bash60npm install        # Install all dependencies61npm run build      # Build all packages (TypeScript compilation + asset copying)62npm run build:all  # Build everything including sandbox container63npm run bundle     # Bundle dist/ into a single dist/cli.js via esbuild64                   # (requires build first)65```66 67`npm run build` compiles TS into each package's `dist/`. `npm run bundle`68takes that output and produces a single `dist/cli.js` via esbuild. Bundle69requires build to have run first.70 71### Development72 73```bash74npm run dev        # Run CLI directly from TypeScript source (no build needed)75```76 77Runs the CLI via `tsx` with `DEV=true`. Changes to `packages/core` or78`packages/cli` are reflected immediately without rebuilding.79 80### Unit Testing81 82Tests must be run from within the specific package directory, not the project83root.84 85**Run individual test files** (always preferred):86 87```bash88cd packages/core && npx vitest run src/path/to/file.test.ts89cd packages/cli && npx vitest run src/path/to/file.test.ts90```91 92**Update snapshots:**93 94```bash95cd packages/cli && npx vitest run src/path/to/file.test.ts --update96```97 98**Avoid:**99 100- `npm run test -- --filter=...` — does NOT filter; runs the entire suite101- `npx vitest` from the project root — fails due to package-specific vitest102  configs103- Running the whole test suite unless necessary (e.g., final PR verification)104 105**Test gotchas:**106 107- In CLI tests, use `vi.hoisted()` for mocks consumed by `vi.mock()` — the108  mock factory runs at module load time, before test execution.109 110### Integration Testing111 112Build the bundle first: `npm run build && npm run bundle`113 114Run from the project root using the dedicated npm scripts:115 116```bash117npm run test:integration:cli:sandbox:none118npm run test:integration:interactive:sandbox:none119```120 121Or combined in one command:122 123```bash124cd integration-tests && \125  cross-env QWEN_SANDBOX=false npx vitest run cli interactive126```127 128**Gotcha:** In interactive tests, always call `session.idle()` between sends —129ANSI output streams asynchronously.130 131### Linting & Formatting132 133```bash134npm run lint       # ESLint check135npm run lint:fix   # Auto-fix lint issues136npm run format     # Prettier formatting137npm run typecheck  # TypeScript type checking138npm run preflight  # Full check: clean → install → format → lint → build139                   # → typecheck → test140```141 142## Code Conventions143 144- **Module system**: ESM throughout (`"type": "module"` in all packages)145- **TypeScript**: Strict mode with `noImplicitAny`, `strictNullChecks`,146  `noUnusedLocals`, `verbatimModuleSyntax`147- **Formatting**: Prettier — single quotes, semicolons, trailing commas,148  2-space indent, 80-char width149- **Linting**: No `any` types, consistent type imports, no relative imports150  between packages151- **Tests**: Collocated with source (`file.test.ts` next to `file.ts`),152  vitest framework153- **File naming**: `PascalCase.tsx` for React components, `kebab-case.ts` for154  `.ts` files in `packages/core` and `packages/cli` (enforced by ESLint). Existing camelCase files are allowlisted in `eslint.legacy-filenames.mjs`; rename opportunistically when touching them, updating all imports in the same commit (note: renames lose `git blame` history).155- **Comments**: Default to none. Add only when _why_ is non-obvious; don't delete existing ones as cleanup.156- **Commits**: Conventional Commits (e.g., `feat(cli): Add --json flag`)157- **Node.js**: Development and production both require `>=22` (Ink 7 + React 19.2 requirement)158 159## Development Guidelines160 161### General workflow162 1631. **Design doc for non-trivial work** — write one in `docs/design/` if the164   change touches multiple files or involves design decisions. Skip for small165   bugfixes.1662. **Test plan for behavioral changes** — write an E2E test plan in167   `.qwen/e2e-tests/` when the change affects user-observable behavior. Dry-run168   against the global `qwen` CLI first to confirm the baseline.1693. **Build + typecheck before declaring done**:170   `npm run build && npm run typecheck`.1714. **Code review** — run `/review` when available. Triage each comment:172   valid / false positive / overthinking.173 174### Feature development175 176Use the `/feat-dev` skill for the full workflow: investigate, design, test plan,177dry-run, implement, verify, code review, and iterate.178 179### Bugfix180 181Use the `/bugfix` skill for the reproduce-first workflow: reproduce, fix,182verify, test, and code review.183 184## GitHub Operations185 186Use the `gh` CLI for all GitHub-related operations — issues, pull requests,187comments, CI checks, releases, and API calls. Prefer `gh issue view`,188`gh pr view`, `gh pr checks`, `gh run view`, `gh api`, etc. over web fetches189or manual REST calls.190 191## Testing, Debugging, and Bug Fixes192 193- **Bug reproduction & verification**: spawn the `test-engineer` agent. It194  reads code and docs to understand the bug, then reproduces it via E2E testing195  (or a test-script fallback). It also handles post-fix verification. It cannot196  edit source code — only observe and report.197- **Hard bugs**: use the `structured-debugging` skill when debugging requires198  more than a quick glance — especially when the first attempt at a fix didn't199  work or the behavior seems impossible.200- **E2E testing**: the `e2e-testing` skill covers headless mode, interactive201  (tmux) mode, MCP server testing, and API traffic inspection. The202  `test-engineer` agent invokes this skill internally — you typically don't203  need to use it directly.204 205## Submitting PRs206 207When creating a PR, follow the template at `.github/pull_request_template.md`.208After the PR is submitted, post a separate comment with the E2E test report if209applicable.210 211- **PR description**: explain the motivation and changes in prose. Avoid212  referencing file names or function names.213- **Reviewer Test Plan** (template section): describe behaviors a reviewer214  should verify and what to expect, not scripted test commands. Use **How to215  verify** for reproduction steps; Before/After for TUI evidence when216  applicable.217- **Line wrapping**: do not hard-wrap the PR body at a fixed column width.218  GitHub renders single newlines as `<br>`, so a wrapped description displays219  as a narrow column. Write each paragraph or list item as one long line.220 221## Project Directories222 223Design docs and implementation plans are committed under `docs/` so they are224tracked in version control:225 226| Directory      | Purpose                          |227| -------------- | -------------------------------- |228| `docs/design/` | Design docs for planned features |229| `docs/plans/`  | Implementation plans             |230 231Other working artifacts live under `.qwen/` (git-ignored):232 233| Directory               | Purpose                              |234| ----------------------- | ------------------------------------ |235| `.qwen/e2e-tests/`      | E2E test plans and results           |236| `.qwen/issues/`         | Issue drafts before filing on GitHub |237| `.qwen/pr-drafts/`      | PR drafts before submitting          |238| `.qwen/pr-reviews/`     | PR review notes                      |239| `.qwen/investigations/` | Structured debugging journals        |240| `.qwen/scripts/`        | Utility scripts                      |241