#263 Use plan provenance and trust level when calibrating orchestration effort

packages/agents/content/skills/design-and-plan/SKILL.md

@@ -178,11 +178,27 @@ Present the plan to the user. Revise until approved.
    - Target: `{base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
    - `mkdir -p` the target directory
 
-2. Save both artifacts following `save-artifact` naming conventions:
+2. Resolve provenance data:
+   - Run `git rev-parse origin/main` via Bash to obtain `{baseSha}`. If the command fails (no remote, shallow clone), omit `baseSha` from the header.
+   - Set `{timestamp}` to the current UTC time in ISO 8601 format.
+
+3. Save both artifacts following `save-artifact` naming conventions:
    - Ticket: `{YYYYMMDD-HHMMSSZ}_{slug}_ticket.md`
-   - Plan: `{YYYYMMDD-HHMMSSZ}_{slug}_plan.md`
+   - Plan: `{YYYYMMDD-HHMMSSZ}_{slug}_plan.md` — prepend the following YAML frontmatter to the plan content:
+
+   ```yaml
+   ---
+   provenance:
+     skill: design-and-plan
+     timestamp: <timestamp>
+     baseSha: <baseSha>
+     isInteractive: true
+   ---
+   ```
+
+   If `baseSha` could not be resolved, omit the `baseSha` line entirely.
 
-3. Report paths and suggest next steps:
+4. Report paths and suggest next steps:
 
 ```
 Design and plan complete:

packages/agents/content/skills/orchestrate/SKILL.md

@@ -154,7 +154,40 @@ Prefix the status line with a colored emoji for visual distinction:
 
 1. **Get context**: Use `get-project-slug` and `get-ticket-id`. Resolve the diff base: use `--diff-base` if provided, otherwise use `get-default-branch`. Then compute the merge-base SHA once: run `git merge-base HEAD {diff-base}` and store the result as `{merge-base-sha}` — this concrete SHA is what you pass to all downstream agents. The ticket ID is optional — if unavailable, `init_run` will auto-generate one.
 2. **Read ticket** (if available): If the ticket ID resolves to a GitHub issue, read it via `gh issue view {number}` and store the content as `{ticket-content}`. If the read fails (not a GitHub issue, CLI unavailable), continue without ticket content.
-3. **Detect external plan**: Determine whether the task description contains an **external plan** — step-by-step implementation instructions with specific file paths or code changes. If it does, set `{externalPlan}` to `true` and extract the plan content for use in downstream prompts. Otherwise, set `{externalPlan}` to `false`. This detection must happen before `init_run` so the flag is recorded correctly in the run header.
+3. **Detect external plan and evaluate trust**: Determine whether the task description contains or references an **external plan** — step-by-step implementation instructions with specific file paths or code changes. If it does, set `{externalPlan}` to `true` and extract the plan content. Otherwise, set `{externalPlan}` to `false` and set `{planTrust}` to `null`.
+
+   When `{externalPlan}` is `true`, evaluate the plan's provenance to compute a trust tier:
+
+   **a. Parse provenance header:** Check whether the plan content starts with YAML frontmatter (`---` delimiters) containing a `provenance` block. Extract `skill`, `timestamp`, `baseSha`, `isInteractive`, and `iteration` fields. If no provenance block exists, set `{planTrust}` to `"low"` and skip remaining evaluation.
+
+   **b. Evaluate source credibility:** The plan is credible if `provenance.skill` is one of: `design-and-plan`, `writing-plans`, `plan-orchestrable-steps`. If not credible, set `{planTrust}` to `"low"` and skip remaining evaluation.
+
+   **c. Evaluate codebase freshness:** Run `git rev-parse origin/main` to obtain `{current-main-sha}`. If the command fails, classify freshness as "unknown" and fall back to timestamp:
+   - If `provenance.timestamp` is less than 24 hours ago → "unknown (recent)"
+   - Otherwise → "unknown (stale)"
+
+   If `git rev-parse` succeeds and `provenance.baseSha` is present:
+   - If `baseSha` equals `{current-main-sha}` → "fresh"
+   - Else run `git merge-base --is-ancestor {baseSha} {current-main-sha}`. If exit code 0 → "diverged". If exit code 1 (not an ancestor) → "unverifiable". If the command fails for other reasons (e.g., exit code 128 for unknown ref, shallow clone), fall back to timestamp-based classification as in the `baseSha`-absent case above.
+
+   If `git rev-parse` succeeds but `provenance.baseSha` is absent, fall back to timestamp as above.
+
+   **d. Assign trust tier:**
+
+   | Credible | Freshness        | Tier       |
+   | -------- | ---------------- | ---------- |
+   | Yes      | Fresh            | **high**   |
+   | Yes      | Diverged         | **medium** |
+   | Yes      | Unknown (recent) | **medium** |
+   | Yes      | Unverifiable     | **low**    |
+   | Yes      | Unknown (stale)  | **low**    |
+
+   Note: Non-credible sources are already handled in sub-step b (set to `"low"` and skip). This table only applies to credible sources.
+
+   Store the result as `{planTrust}` (one of `"high"`, `"medium"`, `"low"`).
+
+   This detection and evaluation must happen before `init_run` so the flags are recorded correctly in the run header.
+
 4. **Initialize run via MCP**: Attempt to call MCP tool `init_run` with:
 
    ```
@@ -167,6 +200,7 @@ Prefix the status line with a colored emoji for visual distinction:
    models: {resolved models map}
    config: {
      externalPlan: {externalPlan},
+     planTrust: {planTrust},
      mergeBaseSha: {merge-base-sha},
      diffBase: {diff-base},
      maxReviewRounds: {N},
@@ -307,9 +341,85 @@ The `summary` phase is not a pipeline phase — it is an inherent engine respons
 
 ### Skip logic
 
-**Skip Architecture if:** task is narrow, touches few files, or follows an existing pattern — **and** no external plan is present. When an external plan exists, always run Architecture to validate the plan's assumptions about codebase structure.
+**Skip Architecture if:**
+
+- Task is narrow, touches few files, or follows an existing pattern — **and** no external plan is present, OR
+- External plan is present with `{planTrust}` of `"high"` or `"medium"`. Emit `phase_decision` with `run: false, reason: "skipped: {planTrust}-trust plan (skill: {provenance.skill}, freshness: {freshness classification})"`.
+
+When an external plan exists with `{planTrust}` of `"low"`, always run Architecture to validate the plan's assumptions about codebase structure.
+
+**Skip Planning if:**
+
+- Task is small enough for a single pass, or is a bug fix with clear scope, OR
+- External plan is present with `{planTrust}` of `"high"`. Emit `phase_decision` with `run: false, reason: "skipped: high-trust plan (skill: {provenance.skill}, baseSha matches main)"`. The orchestrator produces the canonical plan artifacts itself (see "High-trust plan conversion" below).
+
+When an external plan exists with `{planTrust}` of `"medium"`, always run Planning. The planner's Task prompt includes an adoption-mode hint (see Phase 2 below).
+
+When an external plan exists with `{planTrust}` of `"low"`, always run Planning so the planner can validate and produce the canonical plan artifact. **Never skip Planning solely because the task already contains step-by-step instructions.**
+
+### High-trust plan conversion
+
+When `{planTrust}` is `"high"` and Planning is skipped, the orchestrator produces the canonical plan artifacts:
+
+1. **Check for JSON companion:** If the external plan file has a JSON companion (same directory, same base name or `orchestration-plan.json`), read it and use it as `{plan-json-content}`. Skip markdown parsing — the JSON is already structured.
+
+2. **Parse markdown to JSON** (if no companion): Parse the external plan's `### Task N:` sections. For each task section, extract:
+   - `title`: text after `### Task N: `
+   - `files`: lines under `**Files:**` (strip `- Create: `, `- Modify: `, `- Test: ` prefixes)
+   - `dependsOn`: parse `**Depends on:** Step N` or `**Depends on:** Steps N, M` references, converting to integer IDs
+   - `acceptanceCriteria`: bullet items under `**Acceptance criteria:**`
+   - `description`: remaining text in the section (between the title and the first recognized sub-heading)
+
+   If a task section lacks any of these sub-headings, use empty values: `[]` for arrays, `""` for strings.
+
+   Construct JSON in the orchestration-plan.json format:
 
-**Skip Planning if:** task is small enough for a single pass, or is a bug fix with clear scope. **Never skip Planning solely because the task already contains step-by-step instructions.** When an external plan exists, always run Planning so the planner can validate and produce the canonical plan artifact.
+   ```json
+   {
+     "overview": "{text from ## Approach or ## Overview section, first paragraph}",
+     "steps": [
+       {
+         "id": 1,
+         "title": "{task title}",
+         "description": "{task description}",
+         "files": ["{path1}", "{path2}"],
+         "acceptanceCriteria": ["{criterion1}", "{criterion2}"],
+         "dependsOn": []
+       }
+     ]
+   }
+   ```
+
+3. **Write artifacts:** Write both files using the orchestrator role (not planner):
+   - `{run-dir}/{NN}_orchestrator_orchestration-plan.md` — copy of the external plan content with the YAML frontmatter block removed (strip everything between and including the opening `---` and closing `---` delimiters at the start of the file)
+   - `{run-dir}/{NN}_orchestrator_orchestration-plan.json` — the structured JSON
+
+   Both files share the same `{NN}`. Increment `{seq}` once for the pair.
+
+4. **Register artifacts:** Call MCP tool `register_artifact` for each:
+
+   ```
+   runDir: {run-dir}
+   filename: {NN}_orchestrator_orchestration-plan.md
+   role: orchestrator
+   roleType: orchestrator
+   agent: orchestrator
+   type: orchestration-plan
+   phase: initialization
+   note: "Adopted from high-trust external plan"
+   ```
+
+   ```
+   runDir: {run-dir}
+   filename: {NN}_orchestrator_orchestration-plan.json
+   role: orchestrator
+   roleType: orchestrator
+   agent: orchestrator
+   type: orchestration-plan
+   phase: initialization
+   ```
+
+5. **Store paths:** Store full paths as `{plan-md-path}` and `{plan-json-path}` for downstream phases. Note: the `phase_decision` for planning was already emitted in the "Skip logic" section above with `reason: "skipped: high-trust plan (skill: {provenance.skill}, baseSha matches main)"`. Do not emit a second `phase_decision` here.
 
 ## Authority hierarchy
 
@@ -410,6 +520,8 @@ After: store the full path as `{architecture-path}`; increment `{seq}`. Extract
 
 ## Phase 2: Planning (optional)
 
+**If Planning was skipped** (high-trust plan conversion already produced `{plan-md-path}` and `{plan-json-path}`): proceed directly to Phase 3 without dispatching the planner. The canonical plan artifacts were already written during initialization.
+
 Before: call MCP tool `emit_event` with `{ runDir: {run-dir}, event: { event: "phase_started", phase: "planning" } }`.
 
 Call Task with `subagent_type: orchestrated-planner`, `max_turns: 40`, `model: {models.planner}`:
@@ -422,6 +534,8 @@ Call Task with `subagent_type: orchestrated-planner`, `max_turns: 40`, `model: {
 >
 > {If `config.externalPlan` is true: Reference plan (validate before adopting): Read `{external-plan-path}`}
 >
+> {If `{planTrust}` is `"medium"`: This plan has medium trust (credible source, codebase may have diverged since plan creation). Focus on validating assumptions that may have been invalidated by recent changes to main. Adopt unchanged steps without re-deriving them.}
+>
 > {If architecture ran and impact > `none`: Architectural guidance: Read `{architecture-path}`}
 >
 > Write plan files to: `{run-dir}/{NN}_planner_orchestration-plan.md` and `{run-dir}/{NN}_planner_orchestration-plan.json`
@@ -438,7 +552,7 @@ Call Task with `subagent_type: orchestrated-coder`, `max_turns: 80`, `model: {mo
 >
 > Task description: {task}
 >
-> {If planning phase ran: Implementation plan: Read `{plan-md-path}`}
+> {If `{plan-md-path}` is set: Implementation plan: Read `{plan-md-path}`}
 > {If architecture ran and impact > `none`: Architectural guidance: Read `{architecture-path}`}
 >
 > Write your response to: `{run-dir}/{NN}_coder_change-summary.md`
@@ -485,14 +599,15 @@ Write run-summary artifact to `{run-dir}/{NN}_orchestrator_run-summary.md`:
 
 ## Phases
 
-| Phase           | Status                         | Notes                                                               |
-| --------------- | ------------------------------ | ------------------------------------------------------------------- |
-| Architecture    | {ran/skipped}                  | {impact level or skip reason}{if external plan: ", plan validated"} |
-| Planning        | {ran/skipped}                  | {step count or skip reason}{if external plan: ", N deviations"}     |
-| Implementation  | {completed/failed}             |                                                                     |
-| Review          | {approved/needs_manual_review} | {aggregated criticality, reviewers with findings, re-review ran}    |
-| Code simplifier | {ran/skipped}                  | {actionable findings, fix cycle ran/not needed}                     |
-| Holistic review | {ran/skipped}                  | {criticality, late-stage fixes}                                     |
+| Phase           | Status                         | Notes                                                                    |
+| --------------- | ------------------------------ | ------------------------------------------------------------------------ |
+| Plan trust      | {planTrust or "n/a"}           | {if planTrust: "skill: {provenance.skill}, freshness: {classification}"} |
+| Architecture    | {ran/skipped}                  | {impact level or skip reason}                                            |
+| Planning        | {ran/skipped}                  | {step count or skip reason}{if ran with medium trust: ", adoption mode"} |
+| Implementation  | {completed/failed}             |                                                                          |
+| Review          | {approved/needs_manual_review} | {aggregated criticality, reviewers with findings, re-review ran}         |
+| Code simplifier | {ran/skipped}                  | {actionable findings, fix cycle ran/not needed}                          |
+| Holistic review | {ran/skipped}                  | {criticality, late-stage fixes}                                          |
 
 ## What was built
 
@@ -518,7 +633,8 @@ Examples of what belongs here:
 
 Include:
 
-- Deviations from reference plan (when external plan was provided)
+- Deviations from reference plan (when external plan was provided and planning ran)
+- Trust tier rationale (when external plan with provenance was provided)
 - Acceptance criteria from the ticket that were intentionally not addressed
 - Any other intentional omissions}
 

packages/agents/content/skills/plan-orchestrable-steps/SKILL.md

@@ -84,12 +84,29 @@ If the user provides feedback (not approval):
 
 When the user approves the plan:
 
-Output confirmation:
+1. Resolve provenance data:
+   - Run `git rev-parse origin/main` via Bash to obtain `{baseSha}`. If the command fails, omit `baseSha`.
+   - Set `{timestamp}` to the current UTC time in ISO 8601 format.
 
-```
-Plan finalized: {artifact-dir}/orchestration-plan.json
-{step count} steps ready for orchestration.
-```
+2. Add provenance header to the latest plan markdown snapshot. List `{artifact-dir}/*_planner_orchestration-plan.md` files, sort lexicographically descending, and take the first (most recent by timestamp prefix). If no matching files are found, skip the provenance header step -- the planner did not produce a markdown snapshot. Read the file. Prepend the following YAML frontmatter and write back:
+
+   ```yaml
+   ---
+   provenance:
+     skill: plan-orchestrable-steps
+     timestamp: <timestamp>
+     baseSha: <baseSha>
+   ---
+   ```
+
+   If `baseSha` could not be resolved, omit the `baseSha` line.
+
+3. Output confirmation:
+
+   ```
+   Plan finalized: {artifact-dir}/orchestration-plan.json
+   {step count} steps ready for orchestration.
+   ```
 
 ## Artifact layout
 

packages/agents/content/skills/refine-plan/SKILL.md

@@ -25,18 +25,19 @@ Before every Task call and after every phase completion, output a status line:
 ### 1. Validate inputs and resolve context
 
 1. Read the plan file. If not found, report an error and stop.
-2. Resolve the ticket source:
+2. Parse YAML frontmatter from the plan content. If a `provenance` block is present, store it as `{input-provenance}`. If no frontmatter or no `provenance` block, set `{input-provenance}` to empty.
+3. Resolve the ticket source:
    - GitHub URL (`github.com/.../issues/...`) -> use `gh issue view --json title,body {url}` via Bash to fetch content.
    - File path -> Read the file.
    - Other URL -> use WebFetch to retrieve content.
-3. Use `get-branch-context` to obtain `ticket_id` and `project_slug`.
-4. Resolve `artifacts.base_dir`:
+4. Use `get-branch-context` to obtain `ticket_id` and `project_slug`.
+5. Resolve `artifacts.base_dir`:
    - Read `artifacts.base_dir` from `.agents/preferences.yaml`
    - If not found, read from `~/.agents/preferences.yaml`
    - If still not found, use default: `~/.ai`
    - If relative, resolve from project root (`git rev-parse --show-toplevel`). If absolute, use as-is.
-5. Resolve artifact directory: `{base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
-6. `mkdir -p {artifact_dir}`
+6. Resolve artifact directory: `{base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
+7. `mkdir -p {artifact_dir}`
 
 ### 2. Detect plan format
 
@@ -130,6 +131,42 @@ Parse the return block:
 
 `-- Refine plan -- revision complete`
 
+If the plan-reviser Task failed or the return block does not have `Status: completed`, skip the provenance update and report the failure:
+
+```
+Plan revision failed -- the plan-reviser did not complete successfully.
+  Review: {review_output_path}
+```
+
+Stop here. Do not attempt provenance update or report completion.
+
+If `{input-provenance}` is non-empty, update the provenance header on the revised plan:
+
+1. Run `git rev-parse origin/main` via Bash to obtain `{baseSha}`. If the command fails, preserve the original `baseSha` from `{input-provenance}`.
+2. Read the revised plan file at `{revision_output_path}`.
+3. Construct updated provenance:
+   - `skill`: preserve from `{input-provenance}` (the original authoring skill)
+   - `timestamp`: current UTC time in ISO 8601 format
+   - `baseSha`: the newly resolved value (or preserved original)
+   - `isInteractive`: preserve from `{input-provenance}` if present
+   - `iteration`: If `{input-provenance}.iteration` is present, set to `{input-provenance}.iteration + 1`. If `{input-provenance}.iteration` is absent, set to `2`.
+4. Prepend the updated YAML frontmatter to the revised plan and write back. Example output (assuming input had `skill: design-and-plan`, `isInteractive: true`, `iteration: 1`):
+
+   ```yaml
+   ---
+   provenance:
+     skill: design-and-plan
+     timestamp: 2026-03-10T08:00:00Z
+     baseSha: abc123def456...
+     isInteractive: true
+     iteration: 2
+   ---
+   ```
+
+   Include `isInteractive` only if it was present in `{input-provenance}`. Include `baseSha` only if resolved or preserved from input.
+
+If `{input-provenance}` is empty, do not add a provenance header — the original plan had none, and refine-plan should not fabricate one.
+
 ### 6. Report completion
 
 ```