planner-task-packet

# Planner Task Packet

Use this skill when converting macro user intent or a frontdesk request into a
plan artifact for review.

## Inputs

- macro task request
- relevant plan-tree/source references
- explicit scope and non-goals
- current phase or prior round result if any

## Outputs

Produce these exact reply-visible sections. Do not replace them with prose,
tables, alternate headings, or "equivalent" sections.

Do not run shell commands, file searches, file reads, tests, builds, or CCB
commands before replying. Use only the intake evidence and compact artifacts
provided in the prompt.

- `task-packet.md`
- `readiness.json`
- `task-set.json` only for explicit independent deliverables, distinct routes,
  or route-mix intake
- `candidate-questions.jsonl` when user input may be needed

For single-slice work, use fenced blocks with these exact labels:

````markdown
**task-packet.md**
```markdown
# Task: <title>
Route: <direct_execution|needs_detail|macro_adjustment_request|blocked|partial_completion>
## Goal
<complete product outcome>
## Acceptance Criteria
- <observable behavior; preserve every intake requirement>
## Interface Contracts
- <concrete module/import path, callable/signature, CLI, data/error shape, or None declared>
## Constraints And Non-Goals
- <constraint or explicit non-goal>
## Execution Decomposition Inputs
- Independently reviewable surfaces: <surfaces or none>
- Stable interfaces available: <interfaces or none>
- Unresolved ordering constraints requiring predecessor output: <constraints or none>
Allowed paths:
- <relative path, or leave empty when route is needs_detail/blocked>
Verification:
- <direct executable argv command>
```

Every `Verification:` item is executed literally without a shell. Do not put
prose such as `Review docs...` in this list. Express documentation and contract
checks as executable tests, or keep them in acceptance criteria for Reviewer
inspection.

**readiness.json**
```json
{"readiness":"ready","route":"direct_execution","blockers":[],"allowed_paths":["path"],"verification":["command"]}
```
````

For task-set work, use exactly one fenced `**task-set.json**` section. Do not
also return single-task sections for the same reply.

For frontdesk single-task work, all five semantic `##` sections shown above
are mandatory and non-empty. Keep them inside the fenced task packet so the
script-owned artifact passed to the orchestrator preserves the user goal,
interfaces, constraints, and decomposition evidence.

A stable interface is parallelization evidence, not a predecessor edge. Only
put a constraint in `Unresolved ordering constraints requiring predecessor
output` when one unit needs a newly generated artifact, schema, data result, or
accepted predecessor evidence that is not already supplied by the intake.
Behavioral prose alone is not a stable interface. A cross-node consumer must
already have the exact module/import path and callable/signature, CLI contract,
or data/error shape it will use. If a test, example, or downstream module would
have to guess a new API name or result contract, record a predecessor-output
constraint instead of claiming that the units can run in parallel.

````markdown
**task-set.json**
```json
{
  "tasks": [
    {
      "task_id": "stable-bounded-task-id",
      "title": "Bounded task title",
      "route": "direct_execution",
      "readiness": "ready",
      "task_packet": "# Task: Bounded task title\nRoute: direct_execution\n",
      "execution_contract": "# Execution Contract\nRoute: direct_execution\n\nAllowed Change Paths:\n- relative/path\n",
      "allowed_paths": ["relative/path"],
      "verification": ["command or evidence review"],
      "blockers": []
    }
  ]
}
```
````

Readiness values are exactly:

- `ready`
- `needs_clarification`
- `blocked`
- `not_ready`

## Bounded Post-Detail Stop

An activation may optionally contain a controller-verified
`terminal_status_constraint`. Treat it as an authority constraint, not a
free-form suggestion, only when all of these fields are present and consistent
with the activation and compact artifact evidence:

- `schema_version=1`
- `status=detail_ready`
- `basis=verified_detail_ready_stop_contract`
- the current `task_id`, positive `task_revision`, and positive `state_version`
- lowercase SHA-256 `authority_digest` and `basis_digest`
- non-empty `required_reason` equal to the controller activation reason
- current post-detail task status `detail_ready` and route context
  `needs_detail`

For this one bounded case, `readiness=ready` means the planning artifacts are
complete; it does not authorize execution. Return a `needs_detail` task packet
and this matching readiness shape:

```json
{"readiness":"ready","route":"needs_detail","status_recommendation":"detail_ready","reason":"<required_reason>","allowed_paths":[],"verification":["<repo-independent verification>"],"blockers":[]}
```

Preserve `required_reason` exactly. Keep `allowed_paths` and `blockers` empty,
and use repo-independent verification rather than Git-only scope checks. The
reply must not authorize implementation, orchestrator, worker, checker, or
another route.

If any required constraint field is absent, stale, malformed, or conflicts with
the current artifacts, revision, task status, reason, or route, fail closed.
You must not guess or synthesize authority, and you must not fall back to
`ready_for_orchestration`. Return a blocker/invalid recommendation so the
controller rejects the reply.

Without `terminal_status_constraint`, this exception does not apply. Preserve
ordinary post-detail flow: after complete detail artifacts, the Planner may
recommend `ready` and `ready_for_orchestration` according to the existing
production rules. It does not make every `needs_detail` plus `ready` reply
terminal.

The provider reply is semantic evidence, not task-status authority. The
controller owns task-status authority, validates provenance/path/digest/revision
fences, and alone imports or settles the recommendation.