fix(skill): provenance-gated explain_skill_activation() and invalid-JSON hardening

Changes:
- skill_loader: explain_skill_activation() now reads provenance.json
  from skill bundle to determine governance_status (candidate_installed
  vs direct_write vs unknown). Includes write_targets map.
- skill_candidates: record installed_via=candidate in provenance.
- chat_agent: ModelDecisionEngine now raises RuntimeError for workspace
  tasks when JSON parsing fails after max retries, instead of silently
  emitting invalid_model_decision_json. Test updated.
- docs: new analysis doc (dynamic-skill-generation audit), e2e test
  roadmap (3 sprints), updated spec/risks with 3 new failure modes,
  acceptance doc counter bumped.
- test: regression test for RSS candidate bundle governance report.

Constraint: provenance must stay beside SKILL.md, not in a separate tree
Tested: pytest -q (42 passed, 1 warning), ruff check passed, ruff format --check passed, git diff --check passed
Confidence: high

Author: johnteee

docs/acceptance.md

@@ -21,7 +21,7 @@ acceptance flow writes the user TUI state file. In sandboxed environments, run
 them with permission to bind localhost ports and write the TeaAgent state
 directory.
 
-**Current acceptance test count: `440 passed`**
+**Current acceptance test count: `441 passed`**
 
 ## Acceptance Flows
 

docs/analysis/dynamic-skill-generation-and-long-result-audit-2026-06-05.md

@@ -30,3 +30,38 @@
 **File**: `skill_rag.py`
 **Risk**: If skill descriptions are similar, semantic routing may invoke the wrong skill.
 **Failure mode**: Unexpected behavior; hard to debug since skill name is not shown by default.
+
+### SKL-R-007: Direct active-skill writes bypass candidate governance
+**File**: `skill_writer.py`, `workspace_tools/_files.py`, `skill_loader.py`
+**Risk**: An agent can write a `SKILL.md` directly into an active discovery
+directory such as `.opencode/skill/` or `.config/agent/skills/`. The loader will
+discover it, but no candidate artifacts, offline eval, review, or install
+provenance prove that it is safe or useful.
+**Failure mode**: The UI reports a skill as available even though it is an
+unreviewed direct write. Users may mistake compatibility discovery for a
+governed TeaAgent skill lifecycle.
+**Mitigation**: Treat missing candidate provenance as `direct_write` in
+explainability output; block or quarantine direct writes to active skill
+directories by default; allow reviewed installs through `skill candidate
+install`.
+
+### SKL-R-008: Skill loaded does not prove skill used
+**File**: `chat_agent.py`, `skill_loader.py`
+**Risk**: Agent Skills can be injected into the prompt but ignored by the model,
+especially when the model fails to read supporting resources or emits invalid
+tool-decision JSON.
+**Failure mode**: A run claims a skill-based task succeeded, but the skill only
+appeared in context and did not drive the output.
+**Mitigation**: Add explicit `skill_activated`, `skill_resource_read`, and
+`skill_output_verified` audit events; add user-forced activation; compare
+with-skill and without-skill behavior in candidate evals.
+
+### SKL-R-009: Long skill or web results lose required evidence
+**File**: `workspace_tools/_files.py`, `chat_agent.py`, future web/RSS tools
+**Risk**: Long RSS/WebSearch/skill results can be truncated or summarized before
+the model sees the evidence required for a faithful answer.
+**Failure mode**: The model writes a plausible summary from a partial preview,
+or creates a placeholder helper script and claims completion.
+**Mitigation**: Standardize a long-result envelope with preview, truncation
+metadata, full artifact path, content hash, cursor, and compaction-preserved
+source IDs. Acceptance tests must verify final output against fixture sources.

docs/modules/skills/risks.md

@@ -2,7 +2,17 @@
 
 ## Purpose
 
-Discovers, routes, and executes skill tool modules — reusable, composable agent behaviors packaged as Python or WASM files. Skills are isolated from the main agent and run in sandboxed environments.
+Discovers, routes, evaluates, installs, and in some cases executes reusable
+agent capabilities. TeaAgent currently has two related skill surfaces:
+
+1. **Agent Skills prompt packages**: directories containing `SKILL.md` and
+   optional references/scripts/assets. These are discovered by `skill_loader.py`
+   and injected into agent context.
+2. **Executable skill tools**: Python/WASM/Docker callable modules handled by
+   `skill_executor.py` and `skill_router.py`.
+
+The daily-driver skill path should prefer the governed Agent Skills candidate
+workflow before a skill becomes active in a project.
 
 ## Behavior Contract
 
@@ -19,9 +29,30 @@ Discovers, routes, and executes skill tool modules — reusable, composable agen
 5. **Result wrapping** — always returns `SkillExecutionResult(success, sandbox_type, output, error)`.
 
 ### Skill Loading (`skill_loader.py`)
-1. **Discovery** — scans `~/.teaagent/skills/` and project `.teaagent/skills/` for skill directories.
-2. **Manifest parsing** — reads `skill.yaml` or `manifest.json` for metadata.
-3. **RAG indexing** — indexes skill descriptions for semantic routing via `skill_rag.py`.
+1. **Discovery** — scans project and user skill directories in priority order (first match wins per skill name):
+   - Project scope: `.config/agent/skills/`, `.claude/skills/`, `.opencode/skill/`, `.opencode/skills/`
+   - User scope: `~/.config/agent/skills/`, `~/.claude/skills/`, `~/.config/opencode/skills/`
+2. **Review gate** — loads only `SKILL.md` files that pass `review_skill()`.
+3. **Candidate artifact gate** — installed candidate bundles with policy,
+   provenance, cost, or contract artifacts must pass artifact validation.
+4. **Prompt mode** — eager mode loads full skill text; index-only mode exposes
+   metadata without injecting full instructions.
+5. **Explainability** — `explain_skill_activation()` reports loaded skills,
+   shadowed paths, searched directories, token estimates, governance status, and
+   expected project write targets.
+
+### Skill Candidate Governance (`skill_candidates.py`)
+1. **Proposal** — creates a quarantined candidate under `.teaagent/skill-candidates/`.
+2. **Artifact bundle** — requires `SKILL.md`, `REFERENCE.md`,
+   `tool_call_contract.json`, `cost_profile.json`, `interaction_policy.json`,
+   and `provenance.json`.
+3. **Offline eval** — validates artifacts, size, review findings, provenance,
+   reference content, and candidate-specific `eval_dataset.json` checks.
+4. **Review** — a candidate must pass review before installation.
+5. **Install** — project installs write to `.config/agent/skills/<name>`;
+   personal installs require explicit personal-install attestation.
+6. **Provenance** — installed candidates record install scope and candidate
+   origin so CLI/TUI can distinguish reviewed skills from direct writes.
 
 ### Skill Router (`skill_router.py`)
 1. **Semantic matching** — `SkillRouter.route(query)` returns ranked skills by description similarity.
@@ -32,3 +63,8 @@ Discovers, routes, and executes skill tool modules — reusable, composable agen
 - Skill execution never modifies the main agent's workspace directly (isolation guarantee).
 - `SkillExecutionResult.success=False` always has a non-empty `error` string.
 - Native execution timeout is enforced (subprocess or thread limit).
+- A reviewed candidate install must carry provenance next to `SKILL.md`.
+- A loaded active skill without candidate provenance should be treated as an
+  unmanaged/direct-write skill for explainability and review purposes.
+- "Skill loaded" does not imply "skill used"; runtime activation and output
+  verification require separate audit evidence.