Follow-up: complete portable pstack conformance hardening #2

Context

PR #1 adds a portability audit and fixes the highest-impact runtime-neutrality problems. This issue tracks the remaining work that should be handled in smaller, reviewable changes.

P0: make the new audit the source of truth

• Review every repository-wide warning produced by python3 scripts/audit_portability.py.
• Classify each warning as real portable debt, intentional adapter-specific content, or a false-positive pattern.
• Extend SCAN_EXCLUDES only for content whose purpose is explicitly runtime-specific; do not suppress portable skill debt.
• Add regression fixtures for every portability pattern before expanding the regex set.

P1: remove remaining vendor-shaped semantics

• Remove concrete model identifiers from all remaining portable skills, playbooks, and shared prompt references. Use model_role and the active adapter.
• Replace ambiguous mechanically generated phrases such as “explore / implement helper” with the one capability the step actually needs.
• Remove runtime fields such as helper type names, background flags, and read-only flags from portable bodies. Keep them inside adapters.
• Audit prompt templates under skills/*/references/, not only top-level SKILL.md files.
• Audit every page under docs/guide/ for Cursor-only installation, model-path, transcript, automation, control-surface, and mode-lifetime assumptions.

P1: harden the import pipeline

• Refactor scripts/port_to_portable.py away from broad word replacement for Task and other overloaded terms.
• Use targeted phrase transforms plus an explicit list of hand-maintained files.
• Make the import pipeline idempotent and fail when a second run changes generated output.
• Emit a machine-readable port report listing every transformation by file and rule.
• Run the strict audit automatically after both port passes.
• Add semantic review fixtures for how, why, architect, arena, swarm, interrogate, reflect, and poteto-mode.

P1: host conformance matrix

Create smoke tests or eval fixtures for each supported host:

• Claude Code
• Codex
• OpenCode
• Droid / Factory
• Generic Agent Skills host with a spawn tool
• Generic single-agent host without a spawn tool

Each host should cover:

• /how simple path: no unnecessary fan-out
• /how complex path: 2–4 independent explorers
• /arena: isolated candidates, cross-judge, synthesis, verification
• /interrogate: independent reviewers and lead judgment
• feature implementation: disjoint worker scope and lead diff review
• bug fix: reproduce, root cause, fix, same-surface verification
• fallback behavior when model selection or helper spawning is denied
• no invented tool parameters from another host

P1: mode and session lifecycle

• Document the exact lifecycle guarantee for every host: current turn, current conversation, post-compaction, and new session.
• Add optional host-native bootstrap/reminder integrations where supported.
• Ensure Session pickup can recover from repository evidence and decision trails without relying on hidden conversation memory.
• Never claim sticky mode on a host that cannot enforce it.

P2: upstream synchronization and provenance

• Add an upstream manifest containing repository, path, commit SHA, sync date, and portable patch version.
• Add a script that fetches or accepts an upstream checkout, imports it, runs both passes, refreshes mirrors, and produces a semantic-review checklist.
• Generate an upstream-to-portable coverage report instead of maintaining counts manually.
• Consider a scheduled workflow that opens a draft sync PR without auto-merging it.
• Keep NOTICE and attribution updates part of the sync check.

P2: reduce duplicated sources

• Decide whether mirrored playbooks and adapters should remain committed artifacts or be generated during packaging.
• When retained, provide one sync-mirrors command and keep the byte-equality audit.
• When generated, ensure skills.sh still discovers both entry layouts correctly.

P2: formalize adapter contracts

• Version the capability contract.
• Define required, optional, and degradable capabilities per adapter.
• Add adapter self-check guidance: available helper types, concurrency limit, model-selection support, external connectors, runtime control, and persistence.
• Validate model override files against a documented schema and reject unknown roles or unavailable model identifiers.
• Separate “tool access needed” from “write permission needed”; read-only intent must not accidentally remove connected evidence tools.

P2: workflow quality improvements

• Add a clear Spec-compliance axis beside engineering-quality review where an originating spec exists.
• Add explicit external-side-effect policy to PR, ticket, chat, deploy, and merge playbooks.
• Add cost/concurrency budgets for multi-model panels and autonomous loops.
• Add a lightweight mode for small tasks so rigor does not imply unnecessary fan-out.

Definition of done

• Repository-wide non-strict audit has no unexplained warnings.
• Strict changed-file audit passes for every pull request.
• All supported-host conformance fixtures pass or document a deliberate degraded behavior.
• Upstream import is repeatable, reviewable, pinned to a source revision, and cannot silently introduce vendor-specific semantics.