arkaos 4.22.0 → 4.23.0

package/THE-ARKAOS-GUIDE.md

@@ -0,0 +1,72 @@
+# The ArkaOS Guide
+
+> v4.23.0 — 86 agents, 17 departments, 292 skills, 270 commands, 16 ADRs.
+> One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
+
+## What it is
+
+ArkaOS is an operating system for AI agent teams: specialized
+departments with framework-backed agents, a constitution with a
+Quality Gate that holds veto power, and an evidence flow where
+gates pass on tool output read from disk — never on narration.
+
+## Start here
+
+```bash
+npx arkaos install     # detects your runtime, installs the core
+npx arkaos doctor      # canonical health check (venv, hooks,
+                       # fastpath, security advisory)
+```
+
+Then inside your runtime: `/arka setup` (profile) and `/do <what
+you need>` — plain language routes to the right department.
+
+## Keep it updated (two steps)
+
+```bash
+npx arkaos@latest update   # step 1: core, hooks, CLI
+```
+
+Then `/arka update` inside the runtime — step 2 syncs every
+project (skills, MCP configs, settings, stack rules).
+
+## Departments
+
+Every request routes through a department squad — ArkaOS never
+answers as a generic assistant.
+
+| Prefix | Commands |
+|---|---|
+| `/arka` | 22 |
+| `/brand` | 12 |
+| `/community` | 14 |
+| `/content` | 19 |
+| `/dev` | 36 |
+| `/do` | 1 |
+| `/ecom` | 18 |
+| `/fin` | 10 |
+| `/kb` | 22 |
+| `/landing` | 14 |
+| `/lead` | 10 |
+| `/mkt` | 12 |
+| `/ops` | 24 |
+| `/org` | 10 |
+| `/pm` | 12 |
+| `/saas` | 14 |
+| `/sales` | 10 |
+| `/strat` | 10 |
+
+## How work ships
+
+1. **G1 CONTEXT** — routing + grounding before anything runs.
+2. **G2 PLAN** — explicit approval before code.
+3. **G3 EXECUTE** — real test runs with exit codes on record.
+4. **G4 REVIEW** — the Quality Gate (CQO + copy + tech reviewers)
+   issues a binary APPROVED/REJECTED; failing evidence can never
+   be overridden by narrative.
+
+## Go deeper
+
+- Wiki: https://github.com/andreagroferreira/arka-os/wiki
+- npm: https://www.npmjs.com/package/arkaos
+- Dashboard: `npx arkaos dashboard` (localhost:3333)

package/VERSION

@@ -1 +1 @@
-4.22.0
+4.23.0

package/arka/SKILL.md

@@ -7,20 +7,42 @@ description: >
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
-## KB-First Research (non-negotiable)
+## KB-First Research (`always-research` SHOULD)
 
 Canonical home of the doctrine — every skill's compact
-`arka:kb-first-prefix` pointer references this section. Before any
+`arka:kb-first-prefix` pointer references this section. The Knowledge Base
+has two co-equal faces over the same corpus: **Obsidian** (note content)
+and **Graphify** (the knowledge graph — how concepts connect). Before any
 external research (Context7, WebSearch, WebFetch, Firecrawl):
 
 1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
+2. When Graphify is configured, also call `mcp__graphify__query_graph`
+   (or `god_nodes` / `shortest_path`) for the relationship view.
+3. Cite relevant hits with `[[wikilinks]]` and/or graph nodes, or
+   explicitly declare a KB gap.
+4. Only after (1)–(3) may external tools run.
+
+**Fail-open:** Graphify runs on a per-user endpoint (home LAN, localhost,
+or VPS — see `knowledge.graphify` config). When it is not configured or
+not reachable, treat it as a gap and proceed with Obsidian alone; never
+block a turn waiting on it. Obsidian remains the mandatory first step.
 
 The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
 treat them as your default source. External research supplements the vault;
-it does not replace it. Enforcement: the Stop hook's kb-cite check
-measures citation compliance per turn.
+it does not replace it.
+
+**Enforcement** runs on three surfaces, in the order they fire:
+
+| Surface | Effect |
+| --- | --- |
+| PreToolUse gate (`core/workflow/research_gate.py`) | DENIES the tool call in the current turn on a repeat violation |
+| Quality Gate | DOD item `kb-research-cited` (`definition_of_done.universal`) is `hard: true` — a failed hard item blocks the done marker (rule `definition-of-done-per-domain`) |
+| Stop hook (`core/governance/kb_cite_check.py`) | SOFT — measures citation compliance and nudges the next turn, never blocks this one |
+
+Governing rule: `always-research` (SHOULD, `config/constitution.yaml`).
+`kb-research-cited` is a Definition-of-Done item (`hard: true`), not an
+entry in the must/should/non-negotiable rule lists — the two are
+complementary, not alternatives.
 
 # ArkaOS — Main Orchestrator
 

package/arka/skills/bootstrap-agent/SKILL.md

@@ -16,8 +16,9 @@ allowed-tools: [Agent, Read, Write, Bash]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-> **KB-first:** query `mcp__obsidian__search_notes` and cite
-> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
 > Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 

package/arka/skills/flow/SKILL.md

@@ -18,8 +18,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-> **KB-first:** query `mcp__obsidian__search_notes` and cite
-> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
 > Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 

package/arka/skills/forge/SKILL.md

@@ -19,8 +19,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-> **KB-first:** query `mcp__obsidian__search_notes` and cite
-> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
 > Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 

package/arka/skills/recipes/SKILL.md

@@ -14,8 +14,9 @@ allowed-tools: [Read, Bash]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-> **KB-first:** query `mcp__obsidian__search_notes` and cite
-> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
 > Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 

package/arka/skills/refine/SKILL.md

@@ -15,8 +15,9 @@ allowed-tools: [Read, AskUserQuestion, Skill]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-> **KB-first:** query `mcp__obsidian__search_notes` and cite
-> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
 > Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 

package/arka/skills/research/SKILL.md

@@ -17,8 +17,9 @@ allowed-tools: [Agent, Read, Write, mcp__obsidian__search_notes]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-> **KB-first:** query `mcp__obsidian__search_notes` and cite
-> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
 > Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 

package/bin/arka-doctor

@@ -3,6 +3,11 @@
 # ARKA OS — Doctor (Health Check System)
 # Usage: arka doctor [--fix] [--json]
 # 18 modular checks: fail = critical, warn = advisory
+#
+# SCOPE: this doctor audits the legacy v1 layout (~/.arka-os +
+# ~/.claude/skills). The CANONICAL doctor for the engine (venv, hooks,
+# fastpath, security advisory) is `npx arkaos doctor` — see issue #358
+# for the consolidation/migration map.
 # ============================================================================
 set -euo pipefail
 
@@ -421,4 +426,7 @@ else
     echo -e "  ${G}All checks passed!${N} ARKA OS is healthy."
   fi
   echo ""
+  echo -e "  ${C}Note:${N} this audits the legacy v1 layout (~/.arka-os + ~/.claude/skills)."
+  echo -e "  For the engine (venv, hooks, fastpath, security advisory) run: ${C}npx arkaos doctor${N}"
+  echo ""
 fi

package/core/cognition/insights/store.py

@@ -4,7 +4,9 @@ Persists ActionableInsight instances with support for status-based retrieval,
 project filtering, presentation lifecycle, and dismissal analytics.
 """
 
+import contextlib
 import sqlite3
+from collections.abc import Iterator
 from datetime import UTC, datetime
 from pathlib import Path
 
@@ -24,11 +26,20 @@ class InsightStore:
         self._db_path = db_path
         self._init_db()
 
-    def _conn(self) -> sqlite3.Connection:
+    @contextlib.contextmanager
+    def _conn(self) -> Iterator[sqlite3.Connection]:
+        """Per-operation connection: transaction semantics AND a real
+        close. ``with sqlite3.connect(...)`` alone only commits/rolls
+        back — it never closes, leaking one connection per operation
+        (ResourceWarning under coverage, amplified by ingest loops)."""
         conn = sqlite3.connect(self._db_path)
-        conn.row_factory = sqlite3.Row
-        conn.execute("PRAGMA journal_mode=WAL")
-        return conn
+        try:
+            conn.row_factory = sqlite3.Row
+            conn.execute("PRAGMA journal_mode=WAL")
+            with conn:
+                yield conn
+        finally:
+            conn.close()
 
     # Instinct columns added after the original 12-column schema. An
     # operator's existing DB has the old shape, so these are ALTER-added

package/core/forge/persistence.py

@@ -4,8 +4,9 @@ import os
 import re as _re
 from pathlib import Path
 from tempfile import NamedTemporaryFile
-from typing import Optional
+
 import yaml
+
 from core.forge.schema import ForgePlan, ForgeStatus
 
 
@@ -23,7 +24,9 @@ def save_plan(plan: ForgePlan) -> Path:
     plans.mkdir(parents=True, exist_ok=True)
     target = plans / f"{plan.id}.yaml"
     data = plan.model_dump(mode="json")
-    fd = NamedTemporaryFile(mode="w", dir=str(plans), suffix=".tmp", delete=False, encoding="utf-8")
+    fd = NamedTemporaryFile(  # noqa: SIM115 — handle outlives the block: os.replace consumes fd.name
+        mode="w", dir=str(plans), suffix=".tmp", delete=False, encoding="utf-8"
+    )
     try:
         yaml.dump(data, fd, default_flow_style=False, allow_unicode=True)
         fd.close()
@@ -35,7 +38,7 @@ def save_plan(plan: ForgePlan) -> Path:
     return target
 
 
-def load_plan(plan_id: str) -> Optional[ForgePlan]:
+def load_plan(plan_id: str) -> ForgePlan | None:
     """Load a forge plan by ID. Returns None if not found."""
     path = _plans_dir() / f"{plan_id}.yaml"
     if not path.exists():
@@ -54,12 +57,20 @@ def list_plans() -> list[dict]:
         if path.name == "active.yaml":
             continue
         data = yaml.safe_load(path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            continue
+        # Pre-v4 plans stored complexity/critic as scalars — a summary
+        # must tolerate every shape that ever hit disk.
+        complexity = data.get("complexity")
+        critic = data.get("critic")
         results.append({
             "id": data.get("id", path.stem),
             "name": data.get("name", ""),
             "status": data.get("status", "draft"),
-            "tier": data.get("complexity", {}).get("tier", "shallow"),
-            "confidence": data.get("critic", {}).get("confidence", 0.0),
+            "tier": complexity.get("tier", "shallow")
+            if isinstance(complexity, dict) else "shallow",
+            "confidence": critic.get("confidence", 0.0)
+            if isinstance(critic, dict) else 0.0,
             "created_at": data.get("created_at", ""),
         })
     return results
@@ -72,7 +83,7 @@ def set_active_plan(plan_id: str) -> None:
     link.write_text(plan_id, encoding="utf-8")
 
 
-def get_active_plan() -> Optional[ForgePlan]:
+def get_active_plan() -> ForgePlan | None:
     """Get the currently active forge plan."""
     link = _active_link()
     if not link.exists():
@@ -94,7 +105,10 @@ def clear_active_plan() -> None:
 
 def _obsidian_forge_dir() -> Path:
     """Obsidian vault path for Forge documents."""
-    return Path.home() / "Documents" / "Personal" / "Projects" / "WizardingCode Internal" / "ArkaOS" / "Forge"
+    return (
+        Path.home() / "Documents" / "Personal" / "Projects"
+        / "WizardingCode Internal" / "ArkaOS" / "Forge"
+    )
 
 
 def export_to_obsidian(plan: ForgePlan) -> Path:
@@ -150,7 +164,8 @@ def _render_obsidian_context(plan: ForgePlan) -> list[str]:
     ctx = plan.context
     return [
         "## Context",
-        f"Repo: {ctx.repo} | Branch: {ctx.branch} | Commit: {ctx.commit_at_forge} | ArkaOS: {ctx.arkaos_version}",
+        f"Repo: {ctx.repo} | Branch: {ctx.branch} | "
+        f"Commit: {ctx.commit_at_forge} | ArkaOS: {ctx.arkaos_version}",
         "",
         "## Prompt",
         f"> {ctx.prompt}",
@@ -195,7 +210,10 @@ def _render_obsidian_critic(plan: ForgePlan) -> list[str]:
     if critic.risks:
         lines.append("### Risks")
         for risk in critic.risks:
-            lines.append(f"- **{risk.risk}** ({risk.severity.value}) — Mitigation: {risk.mitigation}")
+            lines.append(
+                f"- **{risk.risk}** ({risk.severity.value}) — "
+                f"Mitigation: {risk.mitigation}"
+            )
         lines.append("")
     return lines
 

package/core/forge/schema.py

@@ -6,23 +6,21 @@ structured ForgePlan that downstream agents consume.
 """
 
 from enum import Enum
-from typing import List, Optional
 
 from pydantic import BaseModel, Field, field_validator
 
-
 # ---------------------------------------------------------------------------
 # Enums
 # ---------------------------------------------------------------------------
 
-class ForgeTier(str, Enum):
+class ForgeTier(str, Enum):  # noqa: UP042 — StrEnum flips str()/format(); migration is its own change
     """Execution tier determined by complexity score."""
     SHALLOW = "shallow"
     STANDARD = "standard"
     DEEP = "deep"
 
 
-class ForgeStatus(str, Enum):
+class ForgeStatus(str, Enum):  # noqa: UP042 — StrEnum flips str()/format(); migration is its own change
     """Lifecycle status of a ForgePlan."""
     DRAFT = "draft"
     REVIEWING = "reviewing"
@@ -34,21 +32,21 @@ class ForgeStatus(str, Enum):
     ARCHIVED = "archived"
 
 
-class ExplorerLens(str, Enum):
+class ExplorerLens(str, Enum):  # noqa: UP042 — StrEnum flips str()/format(); migration is its own change
     """The analytical perspective used when exploring a plan."""
     PRAGMATIC = "pragmatic"          # Focus on fastest viable path
     ARCHITECTURAL = "architectural"  # Focus on long-term design health
     CONTRARIAN = "contrarian"        # Challenge assumptions, surface risks
 
 
-class RiskSeverity(str, Enum):
+class RiskSeverity(str, Enum):  # noqa: UP042 — StrEnum flips str()/format(); migration is its own change
     """Severity level for identified risks."""
     LOW = "low"
     MEDIUM = "medium"
     HIGH = "high"
 
 
-class ExecutionPathType(str, Enum):
+class ExecutionPathType(str, Enum):  # noqa: UP042 — StrEnum flips str()/format(); migration is its own change
     """Type of execution artefact that fulfils a plan step."""
     SKILL = "skill"
     WORKFLOW = "workflow"
@@ -60,12 +58,22 @@ class ExecutionPathType(str, Enum):
 # ---------------------------------------------------------------------------
 
 class ComplexityDimensions(BaseModel):
-    """Five-axis complexity breakdown, each scored 0–100."""
+    """Five-axis complexity breakdown, each scored 0-100."""
 
-    scope: int = Field(default=0, description="Breadth of change across the codebase or system.")
-    dependencies: int = Field(default=0, description="Number and criticality of upstream/downstream dependencies.")
-    ambiguity: int = Field(default=0, description="How unclear or under-specified the requirements are.")
-    risk: int = Field(default=0, description="Potential for breakage, data loss, or security impact.")
+    scope: int = Field(
+        default=0, description="Breadth of change across the codebase or system."
+    )
+    dependencies: int = Field(
+        default=0,
+        description="Number and criticality of upstream/downstream dependencies.",
+    )
+    ambiguity: int = Field(
+        default=0, description="How unclear or under-specified the requirements are."
+    )
+    risk: int = Field(
+        default=0,
+        description="Potential for breakage, data loss, or security impact.",
+    )
     novelty: int = Field(default=0, description="How unlike existing patterns this work is.")
 
     @field_validator("scope", "dependencies", "ambiguity", "risk", "novelty", mode="before")
@@ -78,14 +86,19 @@ class ComplexityDimensions(BaseModel):
 class ComplexityScore(BaseModel):
     """Aggregated complexity result produced by the Complexity Scorer."""
 
-    score: int = Field(default=0, description="Composite 0–100 score derived from all dimensions.")
-    tier: ForgeTier = Field(default=ForgeTier.SHALLOW, description="Execution tier selected based on the composite score.")
-    dimensions: ComplexityDimensions = Field(default_factory=ComplexityDimensions, description="Per-dimension breakdown.")
-    similar_plans: List[str] = Field(
+    score: int = Field(default=0, description="Composite 0-100 score derived from all dimensions.")
+    tier: ForgeTier = Field(
+        default=ForgeTier.SHALLOW,
+        description="Execution tier selected based on the composite score.",
+    )
+    dimensions: ComplexityDimensions = Field(
+        default_factory=ComplexityDimensions, description="Per-dimension breakdown."
+    )
+    similar_plans: list[str] = Field(
         default_factory=list,
         description="IDs of previously completed plans with similar profiles.",
     )
-    reused_patterns: List[str] = Field(
+    reused_patterns: list[str] = Field(
         default_factory=list,
         description="Named patterns from the ArkaOS pattern library reused in this plan.",
     )
@@ -213,13 +226,23 @@ class ForgePlan(BaseModel):
             "contains only constitution-enforced phases and confidence is 0.0."
         ),
     )
-    dispatch_errors: List[str] = Field(
+    dispatch_errors: list[str] = Field(
         default_factory=list,
         description="Dispatch failures collected during forge (lens: error class: message).",
     )
 
     status: ForgeStatus = ForgeStatus.DRAFT
-    approved_at: Optional[str] = None
-    approved_by: Optional[str] = None
-    executed_at: Optional[str] = None
-    completion_notes: Optional[str] = None
+    approved_at: str | None = None
+    approved_by: str | None = None
+    rejected_at: str | None = None
+    rejected_by: str | None = None
+    executed_at: str | None = None
+    completion_notes: str | None = None
+    review_note: str | None = Field(
+        default=None,
+        description=(
+            "Operator note attached at decision time (plan-canvas review) "
+            "— the 'ponto-e-anota' trail; distinct from completion_notes, "
+            "which belongs to execution."
+        ),
+    )

package/core/governance/evidence_checks.py

@@ -23,6 +23,8 @@ CLI (for hooks/skills)::
 from __future__ import annotations
 
 import argparse
+import configparser
+import fnmatch
 import importlib.util
 import json
 import re
@@ -31,7 +33,7 @@ import shutil
 import subprocess
 import sys
 import time
-from dataclasses import asdict, dataclass, field
+from dataclasses import asdict, dataclass, field, replace
 from pathlib import Path
 
 from core.shared.test_evidence import coverage_percent_from_xml
@@ -218,18 +220,22 @@ def _labelled(result: CheckResult, label: str) -> CheckResult:
     return result
 
 
-def _tool_cmd(tool: str) -> list[str] | None:
+def _tool_cmd(tool: str, module: str | None = None) -> list[str] | None:
     """Resolve a Python tool: PATH binary, else the interpreter's module.
 
     Operator machines install ruff/pytest into the ArkaOS venv with no
     PATH binary — keying on shutil.which alone silently downgraded
     Python lint to eslint over installer/*.js, a FALSE GREEN on a
     NON-NEGOTIABLE gate (QG findings, F1-B2/F1-C1 reviews).
+
+    ``module`` covers tools whose import name differs from the command
+    (codespell ships ``codespell_lib``); without it the module fallback
+    misses and the check skips forever on a venv install.
     """
     if shutil.which(tool):
         return [tool]
-    if importlib.util.find_spec(tool) is not None:
-        return [sys.executable, "-m", tool]
+    if importlib.util.find_spec(module or tool) is not None:
+        return [sys.executable, "-m", module or tool]
     return None
 
 
@@ -335,15 +341,59 @@ def _check_typecheck(
     return _skip("typecheck", "no typecheck configuration detected")
 
 
+def _project_pytest(project_dir: Path) -> list[str] | None:
+    """pytest belonging to the target project's own environment."""
+    for rel in (".venv/bin/pytest", "venv/bin/pytest"):
+        candidate = project_dir / rel
+        if candidate.is_file():
+            return [str(candidate)]
+    return None
+
+
+def _foreign_pytest_can_collect(
+    pytest_cmd: list[str], project_dir: Path, timeout: int,
+) -> bool:
+    """A PATH/venv-foreign pytest must prove it can import the project.
+
+    Running a foreign-env pytest blind produced false FAILs on projects
+    whose dependencies live in their own venv (import errors read as
+    test failures — issue #283, a blind gate on mandatory-qa). Exit 5
+    ("no tests collected") still counts as a working import path.
+    """
+    try:
+        probe = subprocess.run(
+            [*pytest_cmd, "--collect-only", "-q"], cwd=project_dir,
+            capture_output=True, text=True, timeout=min(timeout, 60),
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return probe.returncode in (0, 5)
+
+
 def _check_tests(
     project_dir: Path, changed: list[str] | None,
     test_command: str | None, timeout: int,
 ) -> CheckResult:
     if test_command:
         return _run("tests", shlex.split(test_command), project_dir, timeout)
-    pytest_cmd = _tool_cmd("pytest")
-    if _has_python(project_dir, changed) and pytest_cmd:
-        return _run("tests", [*pytest_cmd, "-q"], project_dir, timeout)
+    if _has_python(project_dir, changed):
+        local_pytest = _project_pytest(project_dir)
+        if local_pytest:
+            return _labelled(
+                _run("tests", [*local_pytest, "-q"], project_dir, timeout),
+                "tests(project-venv)",
+            )
+        pytest_cmd = _tool_cmd("pytest")
+        if pytest_cmd and _foreign_pytest_can_collect(
+            pytest_cmd, project_dir, timeout
+        ):
+            return _run("tests", [*pytest_cmd, "-q"], project_dir, timeout)
+        if pytest_cmd:
+            return _skip(
+                "tests",
+                "pytest resolved outside the project env cannot import "
+                "it — pin --test-command",
+            )
     if _package_json_script(project_dir, "test"):
         return _run(
             "tests", ["npm", "test", "--silent"], project_dir, timeout,
@@ -501,12 +551,54 @@ def _check_spellcheck(
     project_dir: Path, changed: list[str] | None,
     test_command: str | None, timeout: int,
 ) -> CheckResult:
-    if not shutil.which("codespell"):
+    # Resolve like lint/tests do. A bare shutil.which lookup left this check
+    # dark on venv installs (the binary is not on the harness PATH), so three
+    # consecutive QG rounds shipped with NO machine spellcheck signal.
+    cmd = _tool_cmd("codespell", module="codespell_lib")
+    if cmd is None:
         return _skip("spellcheck", "codespell not installed")
     md_files = [f for f in changed or [] if f.endswith(".md")]
     if not md_files:
         return _skip("spellcheck", "no changed .md files")
-    return _run("spellcheck", ["codespell", *md_files], project_dir, timeout)
+    result = _run("spellcheck", [*cmd, *md_files], project_dir, timeout)
+    # codespell honours .codespellrc `skip` even for explicitly listed files,
+    # so a PASS here can cover far fewer files than were handed in. Reporting
+    # the raw count as coverage is how a narrowed scope reads as a full green
+    # (QG finding: 8 of 220 inspected, reported as 220). State both.
+    inspected = _spellcheck_inspected_count(project_dir, md_files)
+    scope = f"{inspected} of {len(md_files)} changed .md inspected"
+    if inspected < len(md_files):
+        scope += f"; {len(md_files) - inspected} excluded by .codespellrc skip"
+    summary = f"{scope}\n{result.summary}" if result.summary else scope
+    return replace(result, summary=summary)
+
+
+def _spellcheck_inspected_count(project_dir: Path, md_files: list[str]) -> int:
+    """How many of ``md_files`` codespell actually reads after `skip`.
+
+    Asks codespell itself (``--count`` on a per-file basis is too slow; a
+    skipped file simply produces no output for any planted probe), so instead
+    we replay its own glob semantics from the config.
+    """
+    patterns = _codespell_skip_globs(project_dir)
+    if not patterns:
+        return len(md_files)
+    return sum(
+        1 for f in md_files
+        if not any(fnmatch.fnmatch(f, p) or fnmatch.fnmatch(f"./{f}", p) for p in patterns)
+    )
+
+
+def _codespell_skip_globs(project_dir: Path) -> list[str]:
+    """`skip` globs from .codespellrc, or [] when unreadable/absent."""
+    cfg = project_dir / ".codespellrc"
+    try:
+        parser = configparser.ConfigParser()
+        parser.read(cfg, encoding="utf-8")
+        raw = parser.get("codespell", "skip", fallback="")
+    except (OSError, configparser.Error):
+        return []
+    return [p.strip() for p in raw.split(",") if p.strip()]
 
 
 def _check_ui_screenshot(