octocode-cli 1.2.8 → 1.2.10

package/skills/octocode-engineer/references/ast-reference.md

@@ -0,0 +1,166 @@
+# AST Reference
+
+Single AST guide for both tools:
+- `scripts/ast/tree-search.js` — fast triage on `ast-trees.txt` from a scan
+- `scripts/ast/search.js` — structural proof on live source files
+
+Use this as the only AST reference for agents.
+
+---
+
+## Which tool when
+
+| Goal | Tool | Why |
+|------|------|-----|
+| Quickly decide where to read next | `tree-search.js` | Works on scan artifact, very fast triage |
+| Prove a code shape exists in source | `search.js` | AST-accurate structural matching |
+| Validate a finding before presenting | `search.js` | Live-source evidence (not snapshot-only) |
+
+Golden rule: **triage with tree-search, prove with search**.
+
+---
+
+## `ast-trees.txt` format
+
+Each scan writes `ast-trees.txt` — a flattened AST snapshot of every analyzed file. The file is markdown-ish with a fixed structure:
+
+```
+# AST Trees — <timestamp>
+
+## <package> — <filepath>
+SourceFile[1:200]
+  ImportDeclaration[1]
+    ImportClause[1]
+      NamedImports[1]
+        ImportSpecifier[1] ...
+  FunctionDeclaration[10:35]
+    ExportKeyword[10]
+    AsyncKeyword[10]
+    Identifier[10]
+    Parameter[10]
+      Identifier[10]
+      StringKeyword[10]
+    Block[10:35]
+      IfStatement[12] ...
+      ReturnStatement[34] ...
+```
+
+**Format rules:**
+- `## <package> — <filepath>` — section header per file
+- `Kind[line]` — single-line node at that source line
+- `Kind[startLine:endLine]` — multi-line node spanning those source lines
+- **Indentation** (2 spaces per level) = AST depth
+- `...` suffix = children truncated by `--tree-depth` (default: 4)
+- Suppress with `--no-tree`. Control depth with `--tree-depth N`.
+
+**Reading directly:** you can read sections with standard tools (`grep`, `head`) or use `localGetFileContent(matchString="## <package> — <filepath>")` to jump to a file's AST. But prefer `tree-search.js` for structured queries.
+
+---
+
+## `tree-search.js` (scan artifact triage)
+
+Queries `ast-trees.txt` programmatically — faster and more reliable than reading the raw file.
+
+```bash
+node <SKILL_DIR>/scripts/ast/tree-search.js -i .octocode/scan -k function_declaration --limit 25
+```
+
+Useful options:
+- `--ignore-case` case-insensitive matching
+- `-i, --input` scan root or timestamp directory
+- `-k` node kind filter (supports `snake_case` and `PascalCase`)
+- `-p` regex pattern to match against any AST tree line
+- `--file` narrow to file (regex on filepath)
+- `--section` narrow to section header (regex)
+- `-C` context lines around each match
+- `--limit` max matches (default: 50, `0` = all)
+- `--json` structured JSON output
+
+Use cases:
+- identify large functions and nested regions before deep reading
+- find candidate files for a category-specific validation pass
+
+Do not use as final proof of live behavior.
+
+**Scan selection**: when `-i` points to `.octocode/scan` (the root), `tree-search` picks the **most recently modified** scan directory. If the latest scan was a narrow `--scope` run, the artifact will only contain AST trees for those scoped files — not the full codebase. To target a specific full scan, pass the exact timestamp directory: `-i .octocode/scan/<timestamp>`.
+
+---
+
+## `search.js` (live structural proof)
+
+Runs against source files via `@ast-grep/napi`.
+
+```bash
+node <SKILL_DIR>/scripts/ast/search.js [options]
+```
+
+Modes:
+- **Pattern** `-p` for AST shape matching with metavariables (`$X`, `$$$X`)
+- **Kind** `-k` for syntax-node class matching
+- **Rule** `--rule` for advanced JSON rules
+- **Preset** `--preset` for built-in smell checks
+
+Examples:
+
+```bash
+node <SKILL_DIR>/scripts/ast/search.js -p 'console.$METHOD($$$ARGS)' --json --root src/
+node <SKILL_DIR>/scripts/ast/search.js -k function_declaration --json --root src/
+node <SKILL_DIR>/scripts/ast/search.js --preset any-type --json --root src/
+```
+
+All presets (run `--list-presets` to verify against your version):
+
+| Preset | Detects |
+|--------|---------|
+| `empty-catch` | Empty catch blocks that silently swallow errors |
+| `console-log` | `console.log` calls left in production code |
+| `console-any` | Any `console` method call (log, warn, error, debug, etc.) |
+| `debugger` | Debugger statements left in code |
+| `todo-fixme` | TODO, FIXME, HACK, XXX, BUG comments |
+| `any-type` | Explicit `any` type annotations |
+| `type-assertion` | TypeScript type assertions (`as X`) |
+| `non-null-assertion` | Non-null assertions (`x!`) |
+| `fat-arrow-body` | Arrow functions with statement block bodies (could be expression) |
+| `nested-ternary` | Nested ternary expressions (hard to read) |
+| `throw-string` | Throwing string literals instead of Error objects |
+| `switch-no-default` | Switch statements without a default case |
+| `class-declaration` | All class declarations |
+| `async-function` | Async function declarations |
+| `export-default` | Default exports |
+| `import-star` | Namespace imports (`import * as X`) |
+| `catch-rethrow` | Catch blocks that only re-throw the caught error |
+| `promise-all` | `Promise.all` calls (check for missing error handling) |
+| `boolean-param` | Function parameters typed as `boolean` |
+| `magic-number` | Numeric literals (excluding 0 and 1) — potential magic numbers |
+| `deep-callback` | Deeply nested arrow function callbacks (3+ levels) |
+| `unused-var` | Variable declarations without call expressions (dead code candidates) |
+
+---
+
+## TypeScript pattern matching — best practices
+
+Pattern mode (`-p`) matches the full AST structure. In TypeScript, type annotations are part of the AST, so patterns must account for them or they will silently miss matches.
+
+**Common pitfall:** `async function $NAME($$$PARAMS)` returns 0 matches on functions with return types like `async function foo(): Promise<void>` — the `: Promise<void>` is a required part of the AST shape.
+
+| Scenario | Approach | Why |
+|----------|----------|-----|
+| Find all functions | `-k function_declaration` | Kind ignores type annotations |
+| Find all async functions | `--preset async-function` | Preset uses kind + regex internally |
+| Find specific call patterns | `-p 'JSON.parse($X)'` | Call expressions don't have TS types |
+| Find method calls | `-p 'console.$M($$$A)'` | Method calls don't have TS types |
+| Match including types | `-p 'function $N($P: string): string { $$$B }'` | Must include exact type shape |
+| Structural smells | `--preset empty-catch` etc. | Presets are TS-aware by design |
+
+**Rule of thumb:** Use `--kind` or `--preset` for declarations (functions, classes, exports, imports). Use `-p` pattern for call expressions, assignments, and code shapes where type annotations are not involved.
+
+---
+
+## Recommended AST workflow
+
+1. `tree-search.js` to narrow candidate files/functions
+2. `search.js` (`--preset`, `-p`, or `-k`) to get structural proof
+3. `localGetFileContent`/LSP tools for semantic context and impact
+
+This keeps investigation fast and reduces false positives.
+

package/skills/{octocode-code-engineer → octocode-engineer}/references/cli-reference.md

@@ -1,7 +1,7 @@
 # CLI Reference
 
 ```bash
-node <SKILL_DIR>/scripts/index.js [flags]
+node <SKILL_DIR>/scripts/run.js [flags]
 ```
 
 Output goes to `.octocode/scan/<timestamp>/` by default. Results are cached — subsequent runs skip unchanged files (~4x faster).
@@ -28,7 +28,7 @@ Output goes to `.octocode/scan/<timestamp>/` by default. Results are cached —
 | Single category | `--features=cognitive-complexity` |
 | Mix pillars + categories | `--features=dead-code,dependency-cycle` |
 | Everything except X | `--exclude=architecture` |
-| Exclude specific categories | `--exclude=dead-export,magic-number` |
+| Exclude specific categories | `--exclude=dead-export,unsafe-any` |
 | Cap findings (diverse) | `--findings-limit 500` |
 | Cap findings (pure severity) | `--findings-limit 500 --no-diversify` |
 | Include tests | `--include-tests` |
@@ -45,13 +45,20 @@ Output goes to `.octocode/scan/<timestamp>/` by default. Results are cached —
 | Enable semantic analysis | `--semantic` |
 | Semantic + scope combo | `--semantic --scope=packages/my-package` |
 | Only semantic categories | `--semantic --features=unused-parameter,shotgun-surgery` |
-| Deep hierarchy threshold | `--semantic --type-hierarchy-threshold 6` |
+| Deeper override-chain threshold | `--semantic --override-chain-threshold 6` |
 | Detect near-clones | `--similarity-threshold 0.8` |
 | Strict security | `--secret-entropy-threshold 4.0 --secret-min-length 16` |
 | Strict test quality | `--mock-threshold 5 --include-tests --features=test-quality` |
 | Force full re-parse | `--no-cache` |
 | Clear cache | `--clear-cache` |
 | JSON to stdout | `--json` |
+| CI gate | `--reporter github-actions --at-least 60` |
+| PR diff check | `--affected HEAD~1 --reporter compact` |
+| Progressive adoption (save) | `--save-baseline` |
+| Progressive adoption (check) | `--ignore-known --at-least 60` |
+| Module neighborhood graph | `--graph --focus=src/session.ts --focus-depth 2` |
+| High-level architecture | `--graph --collapse 2` |
+| Use config file | `--config .octocode-scan.json` |
 
 ---
 
@@ -59,6 +66,8 @@ Output goes to `.octocode/scan/<timestamp>/` by default. Results are cached —
 
 `--scope` focuses on specific paths (comma-separated, relative to root). Use `file:symbol` syntax to drill into a specific function or exported variable — only findings whose line range overlaps with that symbol are returned. The full dependency graph is still built so architecture findings involving scoped files are reported. Combinable with `--features`/`--exclude`.
 
+**Symbol scope fallback**: if the scanner cannot resolve a `file:symbol` target (e.g., the symbol name doesn't match an exported function or the file uses patterns that prevent resolution), it falls back to file-level scope and emits a warning: `"symbol scope could not resolve: <path>. Falling back to file-level scope."` If you see this warning, check the exact exported function name and try again, or use file-level scope directly.
+
 `--features` and `--exclude` are mutually exclusive. Both accept pillar names (`architecture`, `code-quality`, `dead-code`, `security`, `test-quality`) and individual category names, comma-separated.
 
 `--semantic` enables TypeChecker + LanguageService analysis (additional categories). Off by default since it adds ~3-5s. Semantic categories require `--semantic` to appear in results.
@@ -69,6 +78,37 @@ Output goes to `.octocode/scan/<timestamp>/` by default. Results are cached —
 
 ---
 
+## Feature and Category Index
+
+Use this section to quickly verify feature coverage.
+
+### Pillar features (`--features=...`)
+
+- `architecture`
+- `code-quality`
+- `dead-code`
+- `security`
+- `test-quality`
+
+### Semantic-only categories
+
+Require `--semantic` to appear in results. The set of semantic categories evolves across versions — run `--help` or `--semantic --help` to see the current list for your installed version.
+
+### How to list all available categories in your current version
+
+```bash
+node <SKILL_DIR>/scripts/run.js --help
+```
+
+Then verify which categories were emitted in a run:
+
+```bash
+cat .octocode/scan/<latest>/summary.md
+cat .octocode/scan/<latest>/findings.json | jq '.optimizationFindings[].category' | sort -u
+```
+
+---
+
 ## All Flags Reference
 
 ### Core
@@ -94,6 +134,15 @@ Output goes to `.octocode/scan/<timestamp>/` by default. Results are cached —
 | `--no-cache` | off | Disable incremental cache; re-parse all files |
 | `--clear-cache` | — | Delete the analysis cache and exit (no scan) |
 | `--all` | off | Enable all features: `--include-tests --semantic` |
+| `--affected [revision]` | off | Scope to git-changed files + transitive dependents (default: HEAD) |
+| `--save-baseline` | off | Save current findings to `.octocode/baseline.json` |
+| `--ignore-known [file]` | off | Suppress findings matching baseline (default: `.octocode/baseline.json`) |
+| `--reporter <format>` | `default` | Output format: `default`, `compact`, `github-actions` |
+| `--focus <module>` | off | Show only this module and neighbors in graph (requires `--graph`). Supports `--focus=path` syntax |
+| `--focus-depth N` | 1 | Neighbor depth for `--focus` |
+| `--collapse N` | off | Collapse graph nodes to folder depth N |
+| `--at-least N` | off | Fail (exit 1) if gate score below N (0-100). Uses count-based formula, distinct from severity-weighted feature scores in `summary.md` |
+| `--config <file>` | auto-discover | Config file path. Auto-discovers `.octocode-scan.json`, `.octocode-scan.jsonc`, or `package.json#octocode` |
 | `--help`, `-h` | — | Show help message |
 
 ### Thresholds — Architecture
@@ -105,6 +154,8 @@ Output goes to `.octocode/scan/<timestamp>/` by default. Results are cached —
 | `--fan-out-threshold N` | 15 | Fan-out threshold for `god-module-coupling` |
 | `--layer-order <layers>` | _(none)_ | Comma-separated layer names for violation detection |
 | `--deep-link-topn N` | 12 | Max critical dependency paths to report |
+| `--sdp-min-delta N` | 0.15 | Min instability delta for SDP violations |
+| `--sdp-max-source-instability N` | 0.6 | Max source instability to report SDP violations |
 
 ### Thresholds — Code Quality
 
@@ -112,27 +163,30 @@ Output goes to `.octocode/scan/<timestamp>/` by default. Results are cached —
 |------|---------|----------|
 | `--critical-complexity-threshold N` | 30 | Complexity for HIGH findings + critical path weighting |
 | `--cognitive-complexity-threshold N` | 15 | Cognitive complexity threshold |
-| `--cyclomatic-density-threshold N` | 0.5 | CC/LOC ratio threshold |
 | `--halstead-effort-threshold N` | 500000 | Halstead effort threshold |
 | `--maintainability-index-threshold N` | 20 | MI below this triggers a finding (0-100 scale) |
 | `--parameter-threshold N` | 5 | Max function parameters before flagging |
 | `--any-threshold N` | 5 | Max `any` type usages per file |
-| `--magic-number-threshold N` | 3 | Max magic number occurrences per file |
 | `--god-module-statements N` | 500 | Statement threshold for `god-module` |
 | `--god-module-exports N` | 20 | Export threshold for `god-module` |
 | `--god-function-statements N` | 100 | Statement threshold for `god-function` |
+| `--god-function-mi-threshold N` | 10 | MI threshold for `god-function` (fires when MI < N and LOC > 30) |
 | `--min-function-statements N` | 6 | Min function body statements for duplicate matching |
 | `--min-flow-statements N` | 6 | Min control-flow statements for duplicate matching |
 | `--flow-dup-threshold N` | 3 | Min occurrences for a repeated flow to become a finding |
 | `--similarity-threshold N` | 0.85 | Jaccard similarity threshold for near-clone detection |
+| `--deep-nesting-threshold N` | 5 | Max branch/loop nesting depth before flagging |
+| `--multiple-return-threshold N` | 6 | Max return/throw paths per function before flagging |
+| `--magic-string-min-occurrences N` | 3 | Min repetitions of a string literal to flag as magic string |
+| `--boolean-param-threshold N` | 3 | Min boolean params per function to flag as cluster |
 | `--max-recs-per-category N` | 2 | Max findings per category in top recommendations |
 
 ### Thresholds — Semantic (require `--semantic`)
 
 | Flag | Default | Controls |
 |------|---------|----------|
-| `--type-hierarchy-threshold N` | 4 | Max inheritance depth before flagging |
 | `--override-chain-threshold N` | 3 | Max method override depth before flagging |
+| `--shotgun-threshold N` | 8 | Unique-file threshold for `shotgun-surgery` |
 
 ### Thresholds — Security
 
@@ -156,6 +210,26 @@ Output goes to `.octocode/scan/<timestamp>/` by default. Results are cached —
 
 ---
 
+## Scope Sanity Checks
+
+Low or zero findings can mean the codebase is clean — or the scope missed analyzable files. Before trusting a clean result:
+
+1. **Confirm the scope has source files**: `--scope=docs/` or a path with only `.md` files will produce 0 findings. Use `localViewStructure` or `ls` to verify the scope contains `.ts`/`.js`/`.tsx` files.
+2. **Test-quality needs test files**: `--features=test-quality` without `--include-tests` will produce 0 findings — test files are excluded by default.
+3. **Suspiciously low count? Broaden one level**: try removing `--scope` or removing `--features` temporarily to compare against a baseline full run. If the full run has findings and the scoped run doesn't, the scope was too narrow.
+4. **Scoped scans affect downstream tools**: `ast-trees.txt` from a scoped scan only contains AST trees for scoped files. If you later run `tree-search.js -i .octocode/scan`, it picks the latest scan — which may be the narrow one. Either point to a full-scan timestamp explicitly or re-run a full scan.
+
+```bash
+# Baseline (broad)
+node <SKILL_DIR>/scripts/run.js --graph --flow
+# Test-quality focused
+node <SKILL_DIR>/scripts/run.js --features=test-quality --include-tests --scope=<test-containing-path>
+# Source-quality focused
+node <SKILL_DIR>/scripts/run.js --features=code-quality,security --scope=src/
+```
+
+---
+
 ## Drill-Down Workflow
 
 ```

package/skills/octocode-engineer/references/externals.md

@@ -0,0 +1,86 @@
+# External Tools
+
+**Ask user before running.** Use `npx` — no install needed.
+
+## Scanner Already Covers
+
+| Domain | Categories | Flags |
+|--------|-----------|-------|
+| Duplicates | `duplicate-function-body`, `similar-function-body`, `duplicate-flow-structure` | `--similarity-threshold 0.8` |
+| Unused deps | `unused-npm-dependency` | `--features=dead-code` |
+| Dead exports | `dead-export`, `dead-re-export`, `semantic-dead-export` | `--features=dead-code --semantic` |
+
+## eslint
+
+```bash
+npx eslint --fix <target>
+npx eslint --format json <target>
+npx eslint --rule '{"complexity": ["error", 10]}' <target>
+```
+
+## tsc
+
+```bash
+npx tsc --noEmit
+npx tsc --noEmit --strict
+npx tsc --noEmit -p tsconfig.json --pretty --noErrorTruncation
+```
+
+## stylelint — CSS/SCSS/Less
+
+Use when project has CSS files. Scanner only handles JS/TS.
+
+```bash
+npx stylelint "**/*.css"
+npx stylelint "**/*.scss"
+npx stylelint --fix "**/*.css"
+npx stylelint --formatter json "**/*.css"
+```
+
+## knip — Framework-aware dead code
+
+100+ plugins (Next.js, Remix, Angular) detect framework-specific usage scanner can't see.
+
+```bash
+npx knip
+npx knip --exports
+npx knip --dependencies
+npx knip --files
+npx knip --workspace packages/my-pkg
+npx knip --fix
+npx knip --reporter json
+```
+
+## type-coverage — Type safety %
+
+Project-wide typed-vs-any ratio. Scanner counts per-file `any`; this gives one number.
+
+```bash
+npx type-coverage
+npx type-coverage --strict --at-least 90
+npx type-coverage --detail
+```
+
+## dependency-cruiser — Custom arch rules
+
+Declarative rule DSL (`forbidden`/`allowed`/`required`). Scanner has 28 built-in detectors; this adds project-specific constraints.
+
+```bash
+npx depcruise --no-config --output-type err src/
+npx depcruise --no-config --output-type metrics src/
+npx depcruise --no-config --output-type mermaid src/ > deps.md
+npx depcruise --no-config --output-type mermaid --focus "^src/session" src/
+npx depcruise --no-config --output-type err --affected HEAD src/
+```
+
+## Quick Reference
+
+| Finding | Tool | Command |
+|---------|------|---------|
+| `dependency-cycle` | dep-cruiser | `npx depcruise --no-config -T err <path>` |
+| `dead-export` | knip | `npx knip --exports` |
+| `unsafe-any` | type-coverage | `npx type-coverage --strict --detail` |
+| `layer-violation` | dep-cruiser | `npx depcruise --no-config -T err <path>` |
+| Lint issues | eslint | `npx eslint <path>` |
+| Type errors | tsc | `npx tsc --noEmit` |
+| CSS issues | stylelint | `npx stylelint "**/*.css"` |

package/skills/{octocode-code-engineer → octocode-engineer}/references/output-files.md

@@ -4,11 +4,13 @@ Each scan writes to `.octocode/scan/<timestamp>/`:
 
 | File | Contents | When to Read |
 |------|----------|-------------|
-| `summary.md` | Health scores, tags, severity, per-pillar counts, top recs, change risk hotspots | **Always first** |
-| `summary.json` | Machine-readable scan metadata, `agentOutput`, `analysisSummary`, `investigationPrompts`, `parseErrors[]` | Programmatic access |
+| `summary.md` | Health scores, **per-feature scores**, **AI + Structure hybrid ratings**, tags, severity, per-pillar counts, top recs, change risk hotspots | **Always first** |
+| `summary.json` | Machine-readable scan metadata, `agentOutput`, `analysisSummary`, `featureScores[]`, `qualityRating`, `investigationPrompts`, `parseErrors[]` | Programmatic access |
 | `architecture.json` | Dep graph, arch findings, `hotFiles[]`, `graphSignals[]`, chokepoints, optional advanced graph overlays | Cycles, coupling, SDP, D metric, test gaps, side-effect risk |
-| `code-quality.json` | Up to 28 quality findings, severity/category breakdowns | Duplicates, complexity, perf |
-| `dead-code.json` | Up to 10 hygiene findings, severity/category breakdowns | Dead code cleanup |
+| `code-quality.json` | Quality findings, severity/category breakdowns | Duplicates, complexity, perf |
+| `dead-code.json` | Dead-code findings, severity/category breakdowns | Dead code cleanup |
+| `security.json` | Security findings, severity/category breakdowns (emitted only when findings exist) | Secrets, sinks, unsafe eval |
+| `test-quality.json` | Test quality findings, severity/category breakdowns (emitted only when findings exist, requires `--include-tests`) | Mock density, brittle tests |
 | `file-inventory.json` | Per-file: functions, flows, metrics, `issueIds[]` | Deep-diving a specific file |
 | `findings.json` | ALL findings sorted by severity with `ruleId`, `analysisLens`, `confidence`, `impact`, `correlatedSignals[]`, `recommendedValidation`, and optional `flowTrace[]` | Complete sorted list |
 | `ast-trees.txt` | `Kind[startLine:endLine]` per file (on by default, disable with `--no-tree`) | Structural overview |
@@ -28,6 +30,8 @@ agentOutput { totalFindings, highPriority, mediumPriority, lowPriority,
               filesWithIssues[] { file, issueCount, issueIds } },
 analysisSummary { graphSignals[], astSignals[], strongestGraphSignal, strongestAstSignal, combinedSignals[], recommendedValidation },
 strongestGraphSignal, strongestAstSignal, combinedSignals[], recommendedValidation, investigationPrompts[],
+featureScores[] { category, pillar, findings, affectedFiles, hotspotHits, hotspotMaxRisk, contextPenalty, severityBreakdown { critical, high, medium, low, info }, score, grade },
+qualityRating { model, overallScore, overallGrade, aspects[] { aspect, label, weight, score, grade, confidence, rationale, signals[] } },
 parseErrors[] { file, message },
 outputFiles { summary, architecture, codeQuality, deadCode, fileInventory, findings, ... }
 ```
@@ -35,10 +39,26 @@ outputFiles { summary, architecture, codeQuality, deadCode, fileInventory, findi
 Use `summary.json` to drive the first decision:
 
 - Use `agentOutput.topRecommendations[]` and `filesWithIssues[]` to decide where to drill in first
+- Use `featureScores[]` to rank worst categories across the currently active feature set
+- Use `qualityRating.aspects[]` for non-rigid repo-shape scoring (architecture/folder/naming/common/shared/maintainability/consistency)
 - Use `summary.md` or `architecture.json` for graph-specific detail such as `cycles`, `criticalPaths`, and hotspots
 - If top recommendations are mostly complexity, duplication, or side-effect findings, switch to AST-first investigation
 - If graph-heavy recommendations and AST-heavy recommendations appear together, plan a combined investigation before proposing refactors
 
+### Scoring model (current)
+
+- Severity weights: `critical=25`, `high=10`, `medium=3`, `low=1`, `info=0`
+- Score formula: `round(100 / (1 + (weightedFindingsPerFile / 10)))`
+- Guardrails: non-info findings cannot score perfect `100`; critical/high findings are capped (`95`/`98`)
+- Feature context penalties: hotspot overlap lowers category scores (`hotspotHits`, `hotspotMaxRisk`, `contextPenalty`)
+- Hybrid quality model (`qualityRating`): weighted soft-signal scoring, not rigid checks:
+  - Architecture & Structure (30%)
+  - Folder Topology (15%)
+  - Naming Quality (15%)
+  - Common/Shared Layer Health (15%)
+  - Maintainability & Evolvability (15%)
+  - Codebase Consistency (10%)
+
 ### `findings.json`
 
 ```
@@ -103,6 +123,26 @@ findings[], findingsCount, severityBreakdown, categoryBreakdown
 generatedAt, findings[], findingsCount, severityBreakdown, categoryBreakdown
 ```
 
+### `security.json`
+
+Emitted only when security findings exist. Same schema as `dead-code.json`:
+
+```
+generatedAt, findings[], findingsCount, severityBreakdown, categoryBreakdown
+```
+
+Categories: `hardcoded-secret`, `eval-usage`, `command-injection-risk`, `path-traversal-risk`, `sql-injection-risk`, `unsafe-html`, `unsafe-regex`, `prototype-pollution-risk`, `sensitive-data-logging`, `debug-log-leakage`, `input-passthrough-risk`, `unvalidated-input-sink`.
+
+### `test-quality.json`
+
+Emitted only when test quality findings exist (requires `--include-tests`). Same schema as `dead-code.json`:
+
+```
+generatedAt, findings[], findingsCount, severityBreakdown, categoryBreakdown
+```
+
+Categories: `test-no-assertion`, `low-assertion-density`, `excessive-mocking`, `shared-mutable-state`, `missing-test-cleanup`, `focused-test`, `fake-timer-no-restore`, `missing-mock-restoration`.
+
 ### `file-inventory.json`
 
 ```
@@ -133,9 +173,9 @@ If `architecture.json` names a hotspot, use `file-inventory.json` to explain why
 
 ## Reading `ast-trees.txt`
 
-For format, navigation commands, and usage guide, see [ast-tree-search.md](./ast-tree-search.md).
+Flattened AST snapshot: `## <package> — <filepath>` section headers, then indented `Kind[startLine:endLine]` nodes (2 spaces = 1 depth level, `...` = truncated children). On by default (`--emit-tree`). Suppress with `--no-tree`. Tree depth: `--tree-depth N` (default: 4).
 
-On by default (`--emit-tree`). Suppress with `--no-tree`. Tree depth: `--tree-depth N` (default: 4).
+Query with `tree-search.js` (`-k`, `-p`, `--file`, `-C`). For format details and tool reference, see [ast-reference.md](./ast-reference.md).
 
 ---