# Spec Sub-Spec: planning-and-host-adapter

This sub-spec is part of the `spec.md` product contract. SSOT order is `spec.md` core > `docs/spec/*` sub-specs > `Plans.md`.

## Planning Surface Contract

`/harness-plan` owns co-required planning output between the spec.md product contract and Plans.md task contract.
It must not behave as a Plans.md-only generator, and it must not flatten the
precedence order. The order remains `spec.md > sub-spec > Plans.md`:
`spec.md` is the product contract, sub-specs refine scoped domains, and
Plans.md is the task ledger.

`/harness-plan create` and product-impacting `/harness-plan add` must produce
both:

- `Spec delta` when the product contract changes, with the root `spec.md` or
  fallback spec path and the rules being added or changed.
- `Spec skip reason` when the task does not change the product contract, with
  the reason preserved in task context or the sprint contract.
- `Plans.md` task contract rows with DoD, dependencies, status, and evidence
  expectations.

For `create` and product-impacting `add`, agents must read the root `spec.md`
and produce the spec result before producing task rows. Only when a consumer
repository has no root `spec.md` may the agent fall back to an existing project
spec or `docs/spec/00-project-spec.md`.

The agent drafts the spec delta from the request, current repo evidence, memory,
and tests. The user is not expected to write a product spec from scratch before
Harness can plan. If the correct delta is ambiguous, the agent should offer the
smallest decision branch and keep unverified facts as `unknown` or
`not observed`.

Harness generates the spec result. Consumers approve or edit `Spec delta` /
`Spec skip reason`; they are not expected to write the spec from scratch.

Non-trivial planning must be team-validated before it becomes implementation
work. A request is non-trivial when it spans multiple tasks, files, sessions,
or changes product behavior, APIs, data models, permissions, billing, external
integrations, distribution, or security posture. For those requests,
`/harness-plan` must use TeamAgent or sub-agent perspectives when available.
If the runtime cannot spawn sub-agents, the plan must explicitly say
`サブエージェント未使用` and run the same checks in separated sections.
The plan must include `team_validation_mode`, one of
`not_required_lightweight`, `native`, `subagent`, `manual-pass`, or
`unavailable`. Lightweight work may use `not_required_lightweight`.
Non-trivial work must use `native`, `subagent`, or `manual-pass`; `unavailable`
cannot be marked Required.

Product, Architecture, Security, QA, and Skeptic are validation perspectives,
not required runtime `agent_type` names. Harness should pass those perspectives
to the available TeamAgent or Task mechanism rather than requiring arbitrary
agent spawning.

Every non-trivial plan must show:

- alignment with root `spec.md`, applicable sub-specs, and `Plans.md`,
- a project-scoped harness-mem / harness-recall / repo-memory wheel check,
- product-fit validation against the primary operator workflow,
- security validation for permissions, secrets, external sends, supply chain,
  branch protection, and release gates,
- works-in-practice validation that maps the plan to test, smoke, CI, review,
  and release or closeout evidence.

If any of those gates cannot pass, the plan must not mark the work Required
until it adds a spike, narrows scope, updates the product contract, or rejects
the idea.

Security validation must not require reading secrets. If a plan would need to
inspect `.env`, tokens, private keys, or customer data, it must stop at a Risk
Gate and use non-secret evidence such as guardrail rules, config shape, audit
metadata, tests, or CI/GitHub state.

## Hokage Core And Host Adapter Boundary

Harness is a single `harness` CLI binary, not a host plugin. The value-bearing
Go core is the reusable kernel; host adapters are generated shims, not
hand-written source.

The kernel is the irreducible IP and is host-agnostic. It is the set of stdlib-only
Go packages plus the embedded prompt pack:

- `go/internal/policy`: the R01-R13 guardrail rule engine (first-match-wins,
  stdlib + regexp only) plus the deny-surface self-audit baseline.
- `go/internal/gitport`: the single git-exec seam every package routes through.
- `go/internal/plans`: the `Plans.md` parser and marker tally.
- `go/internal/state`: the trimmed session/task state store.
- `go/internal/harnessmem`: the membridge to harness-mem.
- `go/internal/promptpack`: the embedded `work`/`plan`/`review`/`release`
  workflow contracts — the single source of truth for skills and agents.

The kernel must not depend on any host's hook event names, host-only tools,
host config shape, or marketplace packaging details. It defines workflow intent,
user-facing triggers, inputs/outputs, required evidence, acceptance criteria,
review/completion rules, and the R01-R13 adjudication surface. Host-specific
mechanics are derived from it, never hand-maintained alongside it.

R02/R03 distinguish secret-bearing environment files from public templates.
Exact basenames `.env.example`, `.env.template`, `.env.sample`, and `.env.dist`
are writable templates; `.env`, `.env.local`, `.env.production`, additional
suffix variants, and environment files under an independently protected path
remain denied. A template-named symlink that resolves to a protected target is
also denied. The exemption is part of the deny-surface self-audit descriptor,
and the legacy shell guard must match the Go kernel behavior.

When R15 evaluates a staged path from `git add` or `git commit`, it must use
Git's effective working context rather than assuming the Harness process
directory. Literal `git -C` and `--work-tree` options are resolved before the
public-template exemption is applied, including nested or repeated `-C` forms.
If the effective working directory or work tree is supplied by dynamic shell
input and cannot be resolved deterministically, classification
fails closed. A public template name under an independently protected directory
therefore remains denied regardless of the Git invocation form.

A single descriptor, `hosts.toml`, holds every host difference: per host, the
native pre-action hook event name, the hook config path, the matcher, the deny
mechanism, the transport, and the model/effort. `harness gen` reads that one
descriptor and `go/internal/hostgen` emits each host's hook config. Host
adapters are therefore build artifacts (`harness gen` output), not tracked
source that drifts.

The boundary is one rule: **the kernel adjudicates; every generated host hook
routes each pre-action to `bin/harness hook pre-tool`.** A host adapter owns only
the thin shim that wires its native hook to that entrypoint and surfaces the
generated skills/agents; it never re-implements a rule engine and never owns a
parallel guardrail.

| Host | Generated shim owns | Must Not Claim |
|------|---------------------|----------------|
| Claude Code | `.claude-plugin/hooks.json` `PreToolUse` entry routing to `bin/harness hook pre-tool`, generated skill/agent surface, manifest version | A separate guardrail engine; that its hook config is hand-authored source |
| Codex | generated `.codex/hooks.json` `PreToolUse` entry routing to `bin/harness hook pre-tool --host codex`, generated skill/agent surface | A divergent rule set; that the companion path is the enforcement boundary |
| Cursor | generated `.cursor/hooks.json` `preToolUse` entry routing to `bin/harness hook pre-tool --host cursor`, generated skill/agent surface | That file writes are confined by Cursor (containment is harness-side, see `docs/CURSOR_INTEGRATION.md`); a divergent rule set |

A generated host shim or support document is valid only when `harness gen`
produces it from `hosts.toml` and the prompt pack, and `harness gen --check`,
setup, docs generation, release preflight, or an adapter smoke test consumes it
in the same phase. No host artifact is written by hand as source of truth.

**Codex/Cursor hook = generated, not inline (2-layer).** Codex and Cursor are
first-class hook hosts. Their hooks are not written inline in `config.toml`;
`harness gen` materializes them into `.codex/hooks.json` / `.cursor/hooks.json`
(gitignored build artifacts), each routing to `bin/harness hook pre-tool --host
<h>`. "config.toml ships no inline hooks" means "not inside config.toml," not
"no hook exists" — do not conflate the two. There are two hook layers, with
different deployment state per layer:

- **(a) Enforcement** (`PreToolUse` → `bin/harness hook pre-tool` → R01-R13):
  wired symmetrically across all three hosts and generated by `harness gen`. The
  Codex `.codex/hooks.json` carries `PreToolUse` (verified: `harness gen` emits
  it).
- **(b) Mode 2 delivery** (inbox-check / monitor receipt): the generator
  `go/internal/hostgen.GenerateDeliveryHooksJSON` is implemented and unit-tested,
  but has **no production caller** (not wired into `harness gen`), so generated
  `.codex/hooks.json` does not contain inbox-check. Claude's inbox-check lives
  hand-written in `.claude-plugin/hooks.json` (so Claude↔Claude delivery works);
  Codex/Cursor delivery hooks are not deployed. By design Codex delivery is
  turn-boundary (Stop) receipt; live monitor (SessionStart blocking stream) is
  Claude-only.

Before concluding a host lacks a capability, materialize the `harness gen` output
and inspect it: `not_observed` is not `absent`.

GAP (follow-up, not implemented here): wiring `GenerateDeliveryHooksJSON` into
`harness gen` would add inbox-check (turn-based, not live) to the generated
Codex/Cursor hooks, extending Mode 2 delivery to those hosts.

## Support Tiers And Host Claims

Public support wording must use support tiers.
Japanese marketing copy maps **正式対応** only to public EN `supported`.
`internal-compatible` may be described as 互換利用可 / 制限付き対応, never 正式対応.

| Tier | Meaning | Claim Allowed |
|------|---------|---------------|
| `supported` | **H1–H8** (below) all pass on the **same claim path**. Install-only or skill-discovery-only is not enough. | Public support claim (JP: 正式対応) for the verified host and version range. |
| `internal-compatible` | Repo mirror, setup docs, static validation, or local tooling exists, but runtime proof is incomplete. | Internal compatibility or experimental wording only. |
| `candidate` | Current official docs and local evidence suggest a viable adapter path, but no complete smoke proof exists. | Research or spike wording only. |
| `future/unsupported` | No verified adapter path or no current proof. | No setup docs, README support claim, or release support claim. |

### Multi-host `supported` bar (H1–H8)

This bar is **capability-relative**, not a Claude clone. Hosts need not share
SessionStart, PreToolUse shape, or Agent Teams. They must meet every row with
**host-native** mechanisms and honest strength labels.

| ID | Requirement | Notes |
|----|-------------|-------|
| H1 | Host dist + setup is deterministic (package-local paths, no `..`) | Install unit may differ per host |
| H2 | skill_loading is reproducible (CI or required-mode CLI) | Skill visible ≠ workflow complete |
| H3 | Host-native bootstrap route is named in the bootstrap contract | SessionStart **or** AGENTS/rules |
| H4 | Workflow smoke: at least plan (or work/review) produces a fixed artifact | Static golden prompts alone are not enough |
| H5 | Declared safety model is proven: (a) live pre_use deny via `harness hook pre-tool --host <h>`, **or** (b) documented post-gate / floor limits | Undeclared "guard exists" is forbidden |
| H6 | review_artifact path or brain-primary review handoff is contractual | Independent reviewer parity not required |
| H7 | release-preflight (or equivalent CI) consumes host gates fail-closed | Manual-only proof caps at `internal-compatible` |
| H8 | README / matrix / onboarding / claim-wording tests pin the **same** tier | Marketing cannot outrun evidence |

**False parity bans (non-exhaustive):** same capability name ≠ same enforcement;
skill menu visibility ≠ `supported`; Codex CLI ≠ Codex app; PM handoff ≠ Cursor
adapter support; post-gate ≠ pre-stop; `not_observed != absent`.

Claude-clone requirements (SessionStart parity, full event-coverage PreToolUse,
Breezing multitask, memory_bridge) are **not** required for multi-host
`supported`.

### Current default stance

| Host | Default Tier | Reason |
|------|--------------|--------|
| Claude Code | `supported` for Claude-first Harness | Primary product surface; H1–H8 reference host. |
| Codex CLI | `supported` | Plugin install smoke + 3cli Bash PreToolUse floor; live H4 green (2026-07-17); H7 release-preflight fail-closed (`scripts/release-preflight-host-smoke.sh`, 2026-07-19); H8 wording pin complete — not Codex app parity. |
| Codex app | `candidate` under the Codex adapter | App behavior must be verified separately from CLI help output. |
| OpenCode | `internal-compatible` until runtime bootstrap smoke passes | Existing mirror/setup validation exists; runtime parity is not yet proven. |
| Cursor | `supported` | Dist + `setup-cursor` + static smoke + observed Desktop skill loading + live H4 green (2026-07-17); H7 release-preflight fail-closed (2026-07-19); containment disclosure in `docs/CURSOR_INTEGRATION.md`; no FS jail — containment is harness-side. |
| Grok | `supported` | Dist + `setup-grok` + install/inspect + structural workflow smoke + hookcodec HostGrok floor + live H4 green (2026-07-17, hooks fired live); H7 release-preflight fail-closed (2026-07-19); Claude-envelope PreToolUse floor — not full Claude hook parity. |
| GitHub Copilot CLI | `candidate` | Current CLI docs must be verified and Harness-specific bootstrap proof is missing. |
| Antigravity CLI | `future/unsupported` until an official/verified adapter route exists | No local Harness or Superpowers adapter evidence has been observed. |

Phase 73.1.2 freezes the ladder from
`docs/research/superpowers-cherrypick.md`. Phase 111 refines the `supported`
bar as H1–H8. Tiers stay authoritative until host-specific setup, bootstrap,
workflow smoke, safety model, and release/preflight gates pass on the **same**
claim path.

README, onboarding, and release wording must not imply that `candidate`,
`internal-compatible`, or `future/unsupported` hosts are public `supported`
(正式対応). Candidate hosts may appear only as research, spike, or
adapter-candidate work. `future/unsupported` hosts may appear only as future
scope, unsupported scope, or unknown/unobserved research.

Having an install route for four hosts is **not** the same as four hosts sharing
identical capability. Claude Code, Codex CLI, Cursor, and Grok are public
`supported` after H8; OpenCode and other non-promoted hosts promote independently
when H1–H8 are green on their claim path.

If a host is not observed in the current runtime, Harness must say `unknown` or
`not observed`, not `unsupported`, unless the relevant source of truth was
checked.