fix: audit follow-ups — batch 1.5, OpenCode spec-workflow port (Option A), tollgate v2 Stop gate

[hapo-nghialuu]

Summary

Follow-up train to the 2026-07 full-package audit (docs/audit-cafekit-vs-claude-code-2026-07.md, run against v0.13.2). Batch 1 (9 fixes) merged in #66; hook hardening merged in #65. This PR carries four workstreams, 14 commits, each independently revertable. Branch is rebased on dev after both merges; the full self-test suite passes at 150 tests on the final tree.

---

A. Batch-1 leftover cleanup (a705f98, 71f6b45)

• Purged the last references to the removed generate-graph/impact-analysis skills and stale Gemini model IDs missed by fix: audit batch 1 — validator, installer, and payload fixes #66 (READMEs, ai-multimodal references, changelog).
• Test-count parsers in run-skill-self-tests.mjs anchor on line starts; ANSI color prefixes from FORCE_COLOR environments broke them into false NO_TESTS. Child processes now run with NO_COLOR=1, FORCE_COLOR=0.

B. Audit batch 1.5 — items #10/#11/#13 (cb05ace, f963bff, 937fa5c, 6dfdb65)

• update content for new kit - update vị trí đặt taks planing #10 Attribution: pdf/pptx/docx/xlsx are adapted Anthropic stock skills (their LICENSE.txt is Anthropic's) but claimed author: haposoft. Frontmatter now credits Anthropic, PBC — adapted by Haposoft. License files untouched.
• feat(docs): migrate documentation from Antigravity Kit to CafeKit Spec #11 OpenCode contradiction: the compact-recovery banner in session.ts instructed AskUserQuestion — a Claude-only tool that AGENTS.md:85 itself declares unavailable in OpenCode. The banner now tells the agent to ask the user directly in chat (same safety intent).
• feat(docs): migrate documentation from Antigravity Kit to CafeKit Spec #13 frontend-design license: frontmatter pointed at a LICENSE.txt that does not exist. Provenance grep (anthropic → 0 hits) confirms it is Haposoft-authored → license: MIT, matching the other authored skills. No license file fabricated.

C. OpenCode spec-workflow port, Option A (dc74f1e, 41de4d0, 256f44b, 0ea97bc)

Closes 2 of the 3 enforcement hooks the audit flagged as missing from the OpenCode runtime:

• plugins/spec-state.ts — tollgate reminder via chat.message, pushing a schema-complete synthetic text part (id+sessionID+messageID required; a bare part crashes the turn — verified on opencode 1.17.15). Same state-change fingerprint gate as the Claude hook. Escape hatch spec.tollgate: false.
• plugins/task-scaffold-guard.ts — blocks hand-written task files on tool.execute.before. Covers OpenCode-specific creation vectors the Claude hook never needed: apply_patch (*** Add File: scan, defensive) and edit on a non-existent task file (OpenCode's edit can create files, unlike Claude's Edit). Sandbox-virtual paths resolved against the plugin directory.
• Escape-hatch hardening (both platforms): smoke tests proved that when the block message advertised the runtime.json override, the model simply wrote the override and disarmed the guard. Block messages no longer mention the hatch; it stays functional for humans and is documented in docs/opencode-hook-port-audit.md only.
• agent.cjs port explicitly dropped (unreliable subagent surface, low ROI) — decision recorded in the port audit doc.

D. Tollgate v2 — Stop-gate completion enforcement (6df8473, 80b1ae0, 74ca18c)

Audit §3.4.1: the per-prompt tollgate was a reminder, not a barrier — the model could mark tasks done with no verification evidence. Enforcement now moves to the turn boundary:

• New hooks/spec-gate.cjs (Stop hook, registered first on Stop). When a turn ends with newly-done tasks in the active spec's task_registry, each must carry a verification receipt: task-md Status: done (a), an Evidence section (all 3 heading aliases) (b) containing no {{...}} placeholders and at least a fenced block or PASS/FAIL/exit-code line (c), and completed_at set (d). Violations emit {"decision":"block","reason":…} listing each failing task and the exact fix — the assistant must repair before it can end the turn.
• Safety valves (scaffold-guard playbook): stop_hook_active loop guard; first run seeds the status cache without blocking (legacy specs are never gated retroactively); failing tasks are held at their old cache status so the gate re-fires on the next Stop; escape hatch spec.completion_gate: false (missing key → ON); crash-wrapper fail-open.
• spec-state.cjs slimmed: the bilingual ALL-CAPS tollgate wall is gone — state-change turns get a ≤7-line neutral summary; unchanged turns keep the one-liner. Hard enforcement now lives on Stop, so the loud prompt no longer pays its context cost.
• runtime.json template documents spec.{scaffold_guard, completion_gate}; rules/state-sync.md describes the gate; 7 new behavioral tests in hooks/__tests__/spec-gate.test.js (subprocess harness from fix(hooks): harden env escaping and privacy symlink resolution #65).

---

Behavior changes at a glance

Surface	Before	After
Ending a turn with a receipt-less done task	allowed	blocked (Stop gate, actionable reason)
Per-prompt tollgate block	red ALL-CAPS bilingual wall (~460 tok)	≤7-line neutral summary
Scaffold-guard block message	advertised its own disable switch	hatch hidden from the model (both platforms)
OpenCode task-file creation (write/apply_patch/edit-create)	unguarded	blocked → scaffold + Edit-fill
OpenCode spec tollgate	none	injected per turn (chat.message)
Document-skill authorship	haposoft	Anthropic, PBC — adapted by Haposoft

Verification

• npm test (packages/spec): PASS — 150 tests executed (143 baseline after fix(hooks): harden env escaping and privacy symlink resolution #65/fix: audit batch 1 — validator, installer, and payload fixes #66 + 7 new spec-gate tests), re-run on the final rebased tree.
• node --test hooks/__tests__/spec-gate.test.js: 7/7 (block-no-receipt, allow-with-receipt, no-active-spec, stop_hook_active loop guard, first-run seeding, escape hatch, placeholder rejection).
• grep -cE "URGENT|BẮT BUỘC|CẤM" hooks/spec-state.cjs → 0.
• Adversarial review (hapo:code-review, 3-stage): 9.6/10 PASS, 0 critical. Warnings tracked as follow-ups below.

Known follow-ups (non-blocking)

1. Config key naming drift: Claude uses spec.completion_gate, OpenCode uses spec.tollgate; tollgate is not listed in the shipped runtime.json template. Unify or document.
2. OpenCode reminder still loud: spec-state.ts preserves the full URGENT block. Defensible — OpenCode has no Stop-gate equivalent, so the loud prompt is its only completion control — but the port-audit doc should state that rationale explicitly.
3. .opencode/plugins/.logs/ cache dir should be confirmed covered by the installed .opencode/.gitignore.
4. Gate scope matches spec-state.cjs: only the first in_progress spec is gated per turn (pre-existing limitation, now shared by two hooks).

Upgrade path

Existing installs pick everything up on npx @haposoft/cafekit --upgrade: the settings merge appends spec-gate.cjs to the existing Stop entry (per-command merge shipped in #66), the manifest ships the new hook, and the first-run cache seed guarantees no retroactive blocking on in-flight specs.