From 1244031b249803ac328831a7fbc3b6e17b52c3fa Mon Sep 17 00:00:00 2001 From: alderpath Date: Thu, 28 May 2026 16:18:33 +0100 Subject: [PATCH] Fix all 16 documentation deviations from deep audit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SKILL.md: Fix --files flag syntax (agent will error without it) FEATURE_MATRIX.md: Add 5 unified commands, remove lifecycle/timeline/provenance COMMANDS.md: Add unified commands section, fix escape-velocity labels README.md: Fix Mermaid diagram (agent guard → quale verify), update count ALGORITHM.md: Fix quale agent edit → quale ec EFFECT_HARNESS.md: Note unified verify --mode scope is preferred CI_INTEGRATION.md: Fix .quale-cache/ → .quale/ CHANGELOG.md: Add unified commands to v0.9.6 entry --- CHANGELOG.md | 4 ++++ README.md | 7 +++---- SKILL.md | 4 ++-- docs/ALGORITHM.md | 2 +- docs/CI_INTEGRATION.md | 2 +- docs/COMMANDS.md | 27 ++++++++++++++++++++++++--- docs/EFFECT_HARNESS.md | 2 +- docs/FEATURE_MATRIX.md | 24 +++++++++++++++++++++--- tests/snapshots/health_score.snap | 2 +- 9 files changed, 58 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b26a24..e5f19e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ - Refactored: extracted 14 analysis helpers from reports.py into reports/analysis.py (backward compatible) - Added 4 backward compatibility tests (359 total, 0 failing) +- Added 5 unified commands: `risk`, `verify`, `health`, `audit`, `temporal` + (consolidate 15 old commands with mode flags) +- Fixed escape-velocity jargon labels (ESCAPED/BOUND/DEEP → External/Contained/Internal) +- Fixed `provide --file` bare error messages with example syntax - Dogfood findings logged to /tmp/quale-bug-log.md - Added .quale/ to .gitignore diff --git a/README.md b/README.md index 407116e..a4a5e95 100644 --- a/README.md +++ b/README.md @@ -150,7 +150,7 @@ design target (measured 75% accuracy, 0.0 extra edits): | LLM agent | `quale` | `o` (orient), `ec` (edit-context, 75% accuracy), `vp` (verify-packet, 80% accuracy) | | Human developer | `quale` | `review`, `onboard`, `refactor-cost`, `inspect`, `explore` | | CI pipeline | `quale ci` | `check`, `comment`, `trend`, `init` (GitHub Actions generator) | -| Structural primitives | `quale core` | 60+ commands including `hub-risk`, `spectral-gap`, `criticality` | +| Structural primitives | `quale core` | 60+ commands including unified `risk`, `verify`, `health`, `audit`, `temporal` plus `spectral-gap`, `criticality` | ### LLM agent @@ -218,8 +218,7 @@ See [docs/EFFECT_HARNESS.md](docs/EFFECT_HARNESS.md) for full methodology. ### Advanced primitives -See `quale core --help` for 60+ commands including `hub-risk`, `spectral-gap`, -`criticality`, `coupling-chain`, `diff-structural`, `test-gaps`, and more. +See `quale core --help` for 60+ commands including unified `risk`, `verify`, `health`, `audit`, `temporal` plus `spectral-gap`, `criticality`, `coupling-chain`, `diff-structural`, `test-gaps`, and more. ## How it works @@ -271,7 +270,7 @@ flowchart LR A --> D[Test mirror ratio] A --> E[Criticality k] A --> F[Coupling chains] - B --> G["quale review / agent guard"] + B --> G[quale risk / verify] C --> G D --> G E --> G diff --git a/SKILL.md b/SKILL.md index 2395f12..25fc463 100644 --- a/SKILL.md +++ b/SKILL.md @@ -9,7 +9,7 @@ description: Structural codebase analysis for code review, editing, and test ver When asked to edit, review, debug, refactor, or analyze code. ## Before every edit -Run `quale ec ` +Run `quale ec --files ` Returns: risk level, verification candidates, stable anchor warnings. Measured: 75% test accuracy, 0.0 extra edits across 1,100 trials. @@ -17,7 +17,7 @@ Measured: 75% test accuracy, 0.0 extra edits across 1,100 trials. Use the `verification_mc.candidates` field to find the right test file before editing. ## After every edit -Run `quale vp ` +Run `quale vp --files ` Returns: verification candidates with co-change signal. Measured: 80% accuracy, best cost/benefit (2.87). diff --git a/docs/ALGORITHM.md b/docs/ALGORITHM.md index 982b677..432a60a 100644 --- a/docs/ALGORITHM.md +++ b/docs/ALGORITHM.md @@ -114,7 +114,7 @@ The matrix and derived metrics are rendered according to the persona: |---------|--------|---------| | Human developer | Colored terminal output | `quale review` shows per-file risks with icons and explanations | | CI pipeline | Exit codes + PR comment | `quale ci check` exits 0-7, `quale ci comment` posts markdown | -| LLM agent | Structured JSON | `quale agent edit` returns 21-key contract with `verification_mc` | +| LLM agent | Structured JSON | `quale ec` returns 21-key contract with `verification_mc` | All three output formats derive from the same matrix — there is no separate analysis path for different consumers. diff --git a/docs/CI_INTEGRATION.md b/docs/CI_INTEGRATION.md index 505f8d9..3a3eb15 100644 --- a/docs/CI_INTEGRATION.md +++ b/docs/CI_INTEGRATION.md @@ -58,6 +58,6 @@ jobs: ## Notes - Structural scan takes ~1-3 seconds on first run; cached afterward. -- Add `.quale-cache/` to your `.gitignore`. +- Add `.quale/` to your `.gitignore`. - `ci-trend` reads `.quale/ci-history.jsonl` which accumulates across runs. This file is local-only and should not be committed. diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 7fe5570..5298a18 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -41,9 +41,9 @@ quale o # Orient: landmarks, modules, languages ### Namespace commands (alternative) ```bash -quale agent edit src/spool.ts # Same as `quale ec` -quale agent guard src/spool.ts # Combined safety packet: guide + hub-risk + complexity + criticality quale agent orient # Same as `quale o` +quale agent edit src/spool.ts # Edit context with verification candidates +quale agent guard src/spool.ts # Combined safety packet ``` ### MCP tools (when using MCP server) @@ -69,6 +69,27 @@ quale ci comment origin/main HEAD # Posts the PR report as a GitHub comment quale ci trend # CI metric trends over time ``` +## Unified Commands + +These replace multiple old commands with single, mode-switched interfaces. + +```bash +quale risk # Hub + capillary + vulnerability intersection +quale risk --mode hub # Hub risk only +quale risk --mode capillary # Capillary risk only + +quale verify --files src/auth.ts # Combined verification: mc, scope, packet +quale verify --mode mc # Pre-edit multi-choice verification (75% accuracy) +quale verify --mode packet # Post-edit co-change signal (80% accuracy) +quale verify --mode scope # Post-edit scope verification (83% accuracy) + +quale health # Structural health dashboard +quale health --mode score # Single health score + +quale audit HEAD~1 HEAD # Review a diff: CI + PR + structural +quale temporal --file src/auth.ts # Temporal analysis: decay + vocabulary trends +``` + ## 🔬 Core Primitives (`quale core`) Over 30 advanced architectural primitives and algorithms power the insights above. They are available via the `core` namespace. @@ -82,7 +103,7 @@ quale core spectral-gap # Modularity score: largest cluster / seco quale core phantom # Detect framework/library from import/export vocabulary quale core trap # Identifier overlap between two concurrently-edited files quale core hub-risk # High-centrality files with zero edits -quale core escape-velocity # Phrase removal difficulty: ESCAPED / BOUND / DEEP +quale core escape-velocity # Phrase removal difficulty: External / Contained / Internal quale core heisenberg # Mixed refactor/feature edits that must be split ``` diff --git a/docs/EFFECT_HARNESS.md b/docs/EFFECT_HARNESS.md index 29dd5fb..f15838e 100644 --- a/docs/EFFECT_HARNESS.md +++ b/docs/EFFECT_HARNESS.md @@ -62,7 +62,7 @@ The harness tested several conditions. Here's how they map to current CLI comman | Harness condition | CLI command | Status | Notes | |-------------------|-------------|--------|-------| | `edit-context --format tool` | `quale ec` or `quale core edit-context --format tool` | ✓ Active | Primary LLM surface, 75% accuracy | -| `verify_scope` | `quale core verify-scope` | ✓ Active | Verification-only, 83% accuracy on weak models | +| `verify_scope` | `quale core verify-scope` or `quale verify --mode scope` | ✓ Active | Verification-only, 83% accuracy on weak models | | `verify_entangle` | `quale vp` (verify-packet has `entangled_candidates`) | ✓ Via JSON field | Closest match includes co-change signal | | `progressive_verify` | `quale core veto-cascade` | ✓ Via veto-cascade | Closest match: multi-step deterministic → oscillatory → manual | | `diff_edit-context` | `quale ec --diff ` | ✓ Via --diff flag | Same engine, use --diff instead of --files | diff --git a/docs/FEATURE_MATRIX.md b/docs/FEATURE_MATRIX.md index 47085c4..91b49c1 100644 --- a/docs/FEATURE_MATRIX.md +++ b/docs/FEATURE_MATRIX.md @@ -12,6 +12,20 @@ All commands are available in three forms: See [COMMANDS.md](COMMANDS.md) for detailed usage. +## Unified commands (recommended) + +These replace multiple old commands with single, mode-switched interfaces. + +| Command | Replaces | Description | +|---------|----------|-------------| +| `quale risk` | `hub-risk`, `capillary`, `vulnerability-map`, `traffic-control` | Surface risky files: hub, capillary, and their intersection. Modes: `--mode full` (default), `hub`, `capillary` | +| `quale verify` | `verify-packet`, `verify-scope`, `verify-classify`, `verify-bonds`, `verify-drift`, `guard` | Verification pipeline. Modes: `--mode full` (default), `mc`, `scope`, `packet` | +| `quale health` | `health-score`, `drift-check`, `parity-bit` | Structural health dashboard. Modes: `--mode dashboard` (default), `score` | +| `quale audit` | `ci-report`, `pr-report`, `check-diff`, `check-pr` | Review a diff: structural, CI, and PR reports in one command | +| `quale temporal` | `decay`, `vocabulary-trend`, `origins` | Temporal analysis: decay, vocabulary trends, and phrase lifecycles | + +## All commands + | Command | Panel | Description | |---------|-------|-------------| | `help-agent` | Getting Started | Recommend useful quale commands for an agent task. | @@ -28,6 +42,11 @@ See [COMMANDS.md](COMMANDS.md) for detailed usage. | `verify-scope` | Agent Safety | Post-edit scope verification: compare actual diff against expected contract. | | `veto-cascade` | Agent Safety | Veto cascade pipeline — ~33 avg tokens per verification call. | | `zk-proof` | Agent Safety | Verify generated code identifiers against allowed set. | +| `risk` | Code Analysis | Unified risk: hub + capillary + vulnerability intersection. | +| `verify` | Verification | Unified verification: mc, scope, packet, full. | +| `health` | CI | Unified health: dashboard + score. | +| `audit` | CI | Unified diff review: CI + PR + structural. | +| `temporal` | Maintenance | Unified temporal: decay + vocabulary trends. | | `co-change` | Verification | Show file co-change pairs from git history. | | `reverse-verify` | Verification | Given changed test files, find source files that need verification. | | `test-gaps` | Verification | Test gap map: source files with weak test mirrors. | @@ -39,7 +58,6 @@ See [COMMANDS.md](COMMANDS.md) for detailed usage. | `ci-report` | CI | CI-ready structural report: blast radius + stable file check + flags. | | `drift-check` | CI | Structural anomaly velocity across directories. | | `forecast` | CI | Forecast regression risk from co-change shifts. | -| `health` | CI | 0-1 health from stability, mirror, churn, concept age. | | `health-score` | CI | 2-axis health: coupling density x modularity. | | `parity-bit` | CI | SHA-1 of module phrase set. | | `pr-report` | CI | PR structural report in markdown. | @@ -53,6 +71,7 @@ See [COMMANDS.md](COMMANDS.md) for detailed usage. | `porosity` | Code Analysis | Sparse coupling estimate without computing co-occurrence. | | `spectral-gap` | Code Analysis | Modularity score: largest cluster / second largest. | | `trap` | Code Analysis | Identifier overlap between two concurrently-edited files. | +| `vulnerability-map` | Code Analysis | Overlap of hub-risk and capillary. | | `anomalies` | Maintenance | Detect structural anomalies and outliers in vocabulary. | | `cleanup-list` | Maintenance | Prioritized cleanup: extinct-exports x escape-velocity. | | `concept-flow` | Maintenance | Track phrase spread across weekly snapshots. | @@ -60,7 +79,7 @@ See [COMMANDS.md](COMMANDS.md) for detailed usage. | `deflate` | Maintenance | Cap net-new identifiers per edit. | | `diff-structural` | Maintenance | Structural fingerprint diff between two git refs. | | `entropy` | Maintenance | Dir-level vocabulary fragmentation vs 30-commit baseline. | -| `escape-velocity` | Maintenance | Phrase removal difficulty: ESCAPED / BOUND / DEEP. | +| `escape-velocity` | Maintenance | Phrase removal difficulty: External / Contained / Internal. | | `extinct-exports` | Maintenance | Multi-file exports never imported externally. | | `heisenberg` | Maintenance | Mixed refactor/feature edits that must be split. | | `migration-pairs` | Maintenance | Deterministic phrase substitution from two-repo comparison. | @@ -69,7 +88,6 @@ See [COMMANDS.md](COMMANDS.md) for detailed usage. | `solve` | Maintenance | Surface cipher keys: non-dictionary identifiers to learn a repo. | | `traffic-control` | Maintenance | Zone files by graph centrality percentile. | | `vocabulary-trend` | Maintenance | Entropy velocity: is vocabulary diversity accelerating or decelerating?. | -| `vulnerability-map` | Maintenance | Overlap of hub-risk and capillary. | | `coupling` | Cross-Repo | Concept coupling classification: tightly bound, loosely bound, independent. | | `agent-bootstrap` | Utilities | One-shot agent bootstrap: explore + modules + stability + related files. | | `fingerprint` | Utilities | Structural fingerprint of a file or entire repo. | diff --git a/tests/snapshots/health_score.snap b/tests/snapshots/health_score.snap index 25d9f55..9ee484c 100644 --- a/tests/snapshots/health_score.snap +++ b/tests/snapshots/health_score.snap @@ -1,4 +1,4 @@ { - "excess_porosity": -0.01404, + "excess_porosity": -0.014038, "schema_version": null } \ No newline at end of file