@open-agent-toolkit/cli 0.2.62 → 0.2.63

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/assets/bundle-metadata.json +1 -1
  2. package/assets/docs/cli-utilities/config-and-local-state.md +1 -0
  3. package/assets/docs/cli-utilities/configuration.md +10 -8
  4. package/assets/docs/cli-utilities/project-log.md +16 -0
  5. package/assets/docs/cli-utilities/workflow-gates.md +124 -16
  6. package/assets/docs/provider-sync/commands.md +3 -0
  7. package/assets/docs/provider-sync/instruction-sync.md +107 -0
  8. package/assets/docs/reference/cli-reference.md +16 -6
  9. package/assets/docs/reference/oat-directory-structure.md +32 -31
  10. package/assets/docs/workflows/projects/lifecycle.md +45 -0
  11. package/assets/docs/workflows/projects/picking-up-projects.md +14 -0
  12. package/assets/docs/workflows/skills/explainer-kit.md +10 -4
  13. package/assets/docs/workflows/skills/repo-improve.md +15 -1
  14. package/assets/public-package-versions.json +4 -4
  15. package/assets/skills/oat-explainer-kit/SKILL.md +14 -1
  16. package/assets/skills/oat-explainer-kit/references/config-contract.md +12 -0
  17. package/assets/skills/oat-explainer-kit/references/lifecycle-contract.md +57 -10
  18. package/assets/skills/oat-explainer-kit/scripts/check-terminal-outcome.mjs +28 -5
  19. package/assets/skills/oat-explainer-kit/scripts/probe-recap-seams.mjs +371 -0
  20. package/assets/skills/oat-explainer-kit/scripts/resolve-intent.mjs +123 -1
  21. package/assets/skills/oat-project-autonomous/SKILL.md +10 -1
  22. package/assets/skills/oat-project-autonomous/references/gate-inventory.md +121 -121
  23. package/assets/skills/oat-project-complete/SKILL.md +134 -4
  24. package/assets/skills/oat-project-document/references/docs/autonomy-contract.md +121 -121
  25. package/assets/skills/oat-project-implement/SKILL.md +1 -1
  26. package/assets/skills/oat-project-implement/references/completion-and-closeout.md +38 -6
  27. package/assets/skills/oat-project-implement/references/docs/autonomy-contract.md +121 -121
  28. package/assets/skills/oat-project-lite/references/docs/autonomy-contract.md +121 -121
  29. package/assets/skills/oat-project-next/SKILL.md +62 -19
  30. package/assets/skills/oat-project-plan/SKILL.md +31 -5
  31. package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md +121 -121
  32. package/assets/skills/oat-project-progress/SKILL.md +12 -3
  33. package/assets/skills/oat-project-quick-start/SKILL.md +264 -4
  34. package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md +121 -121
  35. package/assets/skills/oat-project-summary/SKILL.md +34 -23
  36. package/assets/skills/oat-repo-improve/SKILL.md +40 -5
  37. package/assets/skills/oat-repo-improve/references/plan-template.md +84 -7
  38. package/dist/commands/config/index.d.ts +1 -0
  39. package/dist/commands/config/index.d.ts.map +1 -1
  40. package/dist/commands/config/index.js +401 -18
  41. package/dist/commands/gate/index.d.ts +3 -1
  42. package/dist/commands/gate/index.d.ts.map +1 -1
  43. package/dist/commands/gate/index.js +699 -211
  44. package/dist/commands/init/tools/shared/skill-script-references.d.ts +126 -0
  45. package/dist/commands/init/tools/shared/skill-script-references.d.ts.map +1 -0
  46. package/dist/commands/init/tools/shared/skill-script-references.js +311 -0
  47. package/dist/commands/instructions/instructions.types.d.ts +63 -0
  48. package/dist/commands/instructions/instructions.types.d.ts.map +1 -1
  49. package/dist/commands/instructions/instructions.utils.d.ts +51 -2
  50. package/dist/commands/instructions/instructions.utils.d.ts.map +1 -1
  51. package/dist/commands/instructions/instructions.utils.js +201 -4
  52. package/dist/commands/instructions/sync/sync.d.ts.map +1 -1
  53. package/dist/commands/instructions/sync/sync.js +12 -1
  54. package/dist/commands/instructions/validate/validate.d.ts.map +1 -1
  55. package/dist/commands/instructions/validate/validate.js +12 -1
  56. package/dist/commands/project/log/append.d.ts +195 -0
  57. package/dist/commands/project/log/append.d.ts.map +1 -1
  58. package/dist/commands/project/log/append.js +1034 -11
  59. package/dist/config/oat-config.d.ts +41 -0
  60. package/dist/config/oat-config.d.ts.map +1 -1
  61. package/dist/config/oat-config.js +111 -0
  62. package/package.json +2 -2
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-summary
3
- version: 1.5.2
3
+ version: 1.5.3
4
4
  description: Use when the user requests or confirms summarizing an active OAT project — e.g. "summarize the project", "generate the summary", "run oat-project-summary", or confirms a previously offered summary run. Do NOT auto-invoke when implementation completes. Generates summary.md from project artifacts as institutional memory.
5
5
  disable-model-invocation: false
6
6
  user-invocable: true
@@ -239,37 +239,47 @@ spec, or design artifacts.
239
239
 
240
240
  **Non-lite section sources:**
241
241
 
242
- | Section | Primary Sources |
243
- | ------------------------------ | ---------------------------------------------------------------------- |
244
- | Overview | discovery.md initial request, spec.md problem statement |
245
- | What Was Implemented | implementation.md task outcomes, plan.md phase structure |
246
- | Key Decisions | design.md decisions, implementation.md notes/decisions |
247
- | Design Deltas | implementation.md deviations table; review-received design drift notes |
248
- | Notable Challenges | implementation.md issues/blockers in task notes |
249
- | Tradeoffs Made | implementation.md decisions, design.md tradeoff sections |
250
- | Integration Notes | implementation.md notes about cross-cutting concerns |
251
- | Revision History | plan.md p-revN phases, implementation.md revision notes |
252
- | Follow-up Items | implementation.md deferred findings, plan.md deferred items |
253
- | Associated Issues | state.md `associated_issues` field |
254
- | Workflow Observations | project-log.md via `oat project log rollup` only |
255
- | Autonomous Execution Learnings | oat-execution-learnings.md dated entries |
256
- | Explainer Outcome | project-recap `manifest.json` and `build-record.json` |
242
+ | Section | Primary Sources |
243
+ | ------------------------------ | --------------------------------------------------------------------------------- |
244
+ | Overview | discovery.md initial request, spec.md problem statement |
245
+ | What Was Implemented | implementation.md task outcomes, plan.md phase structure |
246
+ | Key Decisions | design.md decisions, implementation.md notes/decisions |
247
+ | Design Deltas | implementation.md deviations table; review-received design drift notes |
248
+ | Notable Challenges | implementation.md issues/blockers in task notes |
249
+ | Tradeoffs Made | implementation.md decisions, design.md tradeoff sections |
250
+ | Integration Notes | implementation.md notes about cross-cutting concerns |
251
+ | Revision History | plan.md p-revN phases, implementation.md revision notes |
252
+ | Follow-up Items | implementation.md deferred findings, plan.md deferred items |
253
+ | Associated Issues | state.md `associated_issues` field |
254
+ | Workflow Observations | project-log.md via `oat project log rollup` only |
255
+ | Autonomous Execution Learnings | oat-execution-learnings.md dated entries |
256
+ | Explainer Outcome | project-recap `manifest.json` and `build-record.json`, or the recorded recap skip |
257
257
 
258
258
  **Explainer Outcome (conditional):**
259
259
 
260
- When a project-recap attempt exists, render this section:
260
+ When a project-recap attempt or a recorded recap skip exists, render this
261
+ section with exactly one item. A run that happened uses the first form:
261
262
 
262
263
  ```markdown
263
264
  ## Explainer Outcome
264
265
 
265
- - **project-recap:** {outcome} — `{run path}`{optional warning or recovery note}
266
+ - **project-recap:** {generated | degraded} {outcome} — `{run path}`{optional warning or recovery note}
266
267
  ```
267
268
 
268
- When a project-recap attempt exists, include exactly one concise outcome item with its recipe, outcome (`built-durable`, `built-not-durable`, or `failed`), run path, and warning or recovery note when applicable.
269
+ A recap that never ran because a required seam was unavailable uses the second
270
+ form, which has a reason and no run path:
269
271
 
270
- Use `manifest.json` and `build-record.json` as the source of truth; refresh the existing item instead of appending a duplicate.
272
+ ```markdown
273
+ ## Explainer Outcome
274
+
275
+ - **project-recap:** skipped — {skip reason}
276
+ ```
277
+
278
+ Include exactly one concise item with its recipe, state (`generated`, `degraded`, or `skipped`), and either its outcome (`built-durable`, `built-not-durable`, `built-needs-review`, or `failed`) with run path, or its skip reason. Add a warning or recovery note when applicable. Use `generated` for `built-durable`, `degraded` for any other terminal outcome, and `skipped` only for a recap whose intent resolved to skip.
279
+
280
+ Use `manifest.json` and `build-record.json` as the source of truth for a run, and the recorded recap intent for a skip; refresh the existing item instead of appending a duplicate.
271
281
 
272
- Omit `Explainer Outcome` when no project-recap attempt exists. A failed or non-durable recap remains visible as its product outcome; do not reinterpret it as project implementation failure.
282
+ Omit `Explainer Outcome` only when no project-recap attempt and no recorded recap skip exist. A degraded or skipped recap remains visible as its own product outcome; do not reinterpret either as project implementation failure. A `capability_probe` skip means the host had no provider configured for a required seam, not that the recap failed.
273
283
 
274
284
  **Autonomous Execution Learnings (conditional):**
275
285
 
@@ -619,5 +629,6 @@ Summary tracks: last task {task_id}, {N} revision phases
619
629
  ledger graduation
620
630
  - When the PJM tool pack is available, each Key Decision is promoted to a canonical `reference/decisions/DR-YYMMDD-slug` record via `oat decision new` (status `accepted`), deduped on the date-independent slug so re-runs never create duplicate records
621
631
  - When the PJM tool pack is unavailable, decision promotion is skipped silently with no prompt
622
- - A project-recap attempt appears once in a concise Explainer Outcome section
623
- sourced from its manifest and build record
632
+ - A project-recap attempt or recorded capability skip appears once in a concise
633
+ Explainer Outcome section sourced from its manifest and build record, or from
634
+ the recorded recap intent
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-repo-improve
3
- version: 2.1.2
3
+ version: 2.1.3
4
4
  description: Use when auditing a repository or turning maintainability reviews, backlog reviews, backlog directories, or backlog items into self-contained external implementation plans.
5
5
  argument-hint: '[repo-audit|maintainability-review|backlog-review|backlog-directory|backlog-item] [path-or-id] [quick|standard|deep] [focus] [--backlog-items] [--issues]'
6
6
  disable-model-invocation: false
@@ -162,7 +162,14 @@ Do not treat review rankings or backlog wording as verified code facts. Preserve
162
162
 
163
163
  ### Step 4: Vet and Select Plan Candidates
164
164
 
165
- For audit and review sources, present a concise vetted candidate table with impact/value, effort, risk, confidence, dependencies, and evidence. Keep rejected or stale candidates out of plans and explain material rejections.
165
+ For audit and review sources, present a concise vetted candidate table with impact/value, effort, risk, confidence, `plan_ready`, `execution_ready`, dependencies, and evidence. Keep rejected or stale candidates out of plans and explain material rejections.
166
+
167
+ Score the two readiness axes separately; they answer different questions:
168
+
169
+ - **`plan_ready`** — is the candidate understood well enough to write a self-contained, executable plan? Its evidence is verified live, it has one coherent outcome, and its verification boundary is known.
170
+ - **`execution_ready`** — could an executor start today? Every hard dependency the plan would name is already satisfied.
171
+
172
+ Dependency state alone does not disqualify a candidate. A candidate that is `plan_ready` but not `execution_ready` is still planned: its plan records `oat_execution_status: BLOCKED`, types the blocking row `Hard` in `## Dependencies`, and names the state that would unblock it. Reject a candidate for not being `plan_ready`, never for being blocked.
166
173
 
167
174
  Ask which candidates to plan. Recommend a bounded set of 3–5 when several are viable. In a non-interactive run, select the top 3–5 by leverage and record that default in the generated index.
168
175
 
@@ -179,7 +186,18 @@ For `backlog-item`, the selected candidate is the item itself unless investigati
179
186
 
180
187
  ### Step 5: Write External Plans
181
188
 
182
- Read `references/plan-template.md` before writing the first plan. Record `git rev-parse --short HEAD` and write only under:
189
+ Read `references/plan-template.md` before writing the first plan. Record plan provenance with this block before writing anything:
190
+
191
+ ```bash
192
+ git rev-parse HEAD # inspected baseline → oat_external_plan_commit
193
+ git fetch origin main && git rev-parse origin/main # comparison evidence → oat_external_plan_main_commit
194
+ git merge-base HEAD origin/main # comparison evidence when HEAD is a branch
195
+ git status --porcelain # must be empty, or name every dirty path in the plan
196
+ ```
197
+
198
+ `oat_external_plan_commit` is the full SHA of the `HEAD` whose content was actually inspected. Never stamp it with a fetched tip that was not read: fetching `origin/main` and recording its SHA as the planned-at commit claims evidence the plan never inspected. The fetched `origin/main` or merge-base SHA is comparison evidence and belongs in `oat_external_plan_main_commit`; the two may differ, and they normally do when planning from a branch. If `git status --porcelain` is not empty, name every dirty path in the plan's evidence section so a later executor knows what the inspected tree contained.
199
+
200
+ Then write only under:
183
201
 
184
202
  `.oat/repo/reference/external-plans/`
185
203
 
@@ -196,13 +214,23 @@ The index records source artifacts, selection rationale, execution order, depend
196
214
  Each plan must:
197
215
 
198
216
  - be self-contained for an executor with no session context;
199
- - carry external-plan frontmatter identifying source mode, source paths, planned-at commit, and related backlog IDs;
217
+ - carry external-plan frontmatter identifying source mode, source paths, and related backlog IDs;
218
+ - record the full inspected `HEAD` in `oat_external_plan_commit`, the compared `origin/main` or merge-base SHA in `oat_external_plan_main_commit`, and the planning date in `oat_external_plan_date`;
219
+ - carry `oat_execution_status: READY|BLOCKED` that agrees with its own `## Dependencies` table;
220
+ - include a typed `## Dependencies` table whose rows are `Hard`, `Soft`, or `Satisfied` and whose `Hard` rows name an unblock state, a `## Landing-event impact` table, and a `## Revalidation Before Execution` section;
221
+ - link back to its source backlog item or artifact from the plan body, so the link runs in both directions;
200
222
  - state explicitly that it is not a canonical OAT `plan.md`;
201
223
  - include exact paths, live-state evidence, relevant conventions, hard scope boundaries, ordered steps, tests, machine-checkable verification, done criteria, and specific STOP conditions;
202
- - avoid OAT phase/task IDs and lifecycle metadata;
224
+ - avoid canonical OAT phase/task IDs and lifecycle bookkeeping, while carrying the external execution-readiness metadata above;
203
225
  - preserve source intent without copying unverified claims;
204
226
  - never contain secret values.
205
227
 
228
+ Three document kinds live under `external-plans/`, and the readiness rules differ by kind. A plan carries the full contract. An index (`oat_external_plan_index: true`) carries provenance but no status or dependency/landing/revalidation sections. An execution program (`oat_execution_program: true`, written by `oat-wave-program`) maps plans into waves: it inspects no tree, so it carries no provenance SHAs and no status, and must instead carry `oat_program_indexes`, a `## Status Ledger` whose wave statuses are `composed`, `in-progress`, `merged`, or `done`, and a `## Wave Table`. A program has no plan date, so its mode is selected from `created`. See the "Execution Programs" section of `references/plan-template.md`.
229
+
230
+ Plans written before this contract landed on 2026-09-07 are read in legacy mode and are never retrofitted. The 31 plans in the 2026-08-31 execution program stamped `oat_external_plan_commit` with the `origin/main` SHA whose content they inspected from a planning branch; legacy mode accepts that provenance as-is. Apply the full provenance rule only to plans written from now on.
231
+
232
+ A plan executed inside a wave refreshes its drift check against the exact execution `HEAD` after predecessor lanes integrate, not only from the authored SHA to `origin/main`. Record that refreshed comparison rather than re-stamping the authored provenance.
233
+
206
234
  Before writing, apply the project-size threshold. If a candidate contains multiple independently shippable outcomes, spans subsystems that need separate design decisions, has no single coherent verification boundary, or is otherwise project-sized:
207
235
 
208
236
  1. Split separable work into bounded external plans.
@@ -219,6 +247,8 @@ After every plan write succeeds, update each source backlog item:
219
247
  - update `updated` to the current ISO 8601 UTC timestamp;
220
248
  - preserve all unrelated frontmatter and body content.
221
249
 
250
+ Links must run in both directions: the item's `external_plans` array points at the plan, and the plan body's source section links back to the item. A plan that no source links to, or that links to no source, is only half-tracked; verify both directions before reporting the plan as written.
251
+
222
252
  If safe YAML mutation cannot be established, leave the item unchanged and report the missing reverse link. Never leave a reverse link to a failed or partial plan write.
223
253
 
224
254
  Plans are always the primary output. Tracking publication happens only after the relevant plan writes succeed.
@@ -298,9 +328,14 @@ Audit the repository for security and test improvements, then let me choose what
298
328
 
299
329
  **A candidate is project-sized:** Split it when possible; otherwise recommend the appropriate OAT project/import route instead of writing a mega-plan.
300
330
 
331
+ **A candidate's dependency has not landed:** Plan it anyway when it is `plan_ready`. Record `oat_execution_status: BLOCKED`, type the blocking row `Hard` in `## Dependencies`, and name the state that unblocks it. Do not silently drop the candidate, and do not mark it `READY` to keep the table tidy — an unsatisfied hard dependency with a `READY` status is exactly the contradiction this contract exists to prevent.
332
+
301
333
  ## Success Criteria
302
334
 
303
335
  - Exactly one source mode and source boundary are explicit.
336
+ - Candidates are scored for plan readiness and execution readiness separately, and a plan-ready but blocked candidate is planned as `BLOCKED` rather than dropped.
337
+ - Every plan records the full inspected `HEAD` SHA, a separate comparison SHA, the planning date, and an `oat_execution_status` that agrees with its dependency table.
338
+ - Every plan carries typed dependencies, landing-event impact, and revalidation triggers, and links back to its source item.
304
339
  - Repo audits disclose and lock agent-directory inclusion plus any additional user exclusions before reconnaissance.
305
340
  - Substantive repo audits use managed read-only delegation or stop for narrowing/authorization.
306
341
  - Artifact-backed modes remain scoped to their source material plus bounded verification.
@@ -2,7 +2,9 @@
2
2
 
3
3
  Use this template for plans written by `oat-repo-improve`. Every plan must stand alone for an executor that has zero context from the advisor session, source review, backlog discussion, or sibling plans.
4
4
 
5
- External plans are durable reference artifacts. They are deliberately not canonical OAT `plan.md` files and must not contain OAT phase IDs, task IDs, lifecycle readiness, review tables, or implementation bookkeeping.
5
+ External plans are durable reference artifacts. They are deliberately not canonical OAT `plan.md` files and must not carry canonical OAT lifecycle state: phase IDs, task IDs, phase or task status tables, review tables, or implementation bookkeeping.
6
+
7
+ External execution-readiness metadata is a different thing and is explicitly permitted and required: `oat_execution_status`, the `## Dependencies` table, `## Landing-event impact`, and `## Revalidation Before Execution`. These record whether the plan's own prerequisites have merged, not how an OAT project is progressing through phases.
6
8
 
7
9
  ## File Contract
8
10
 
@@ -19,7 +21,10 @@ oat_external_plan: true
19
21
  oat_external_plan_source: repo-audit|maintainability-review|backlog-review|backlog-directory|backlog-item
20
22
  oat_external_plan_sources:
21
23
  - <repo-relative source artifact or scope>
22
- oat_external_plan_commit: <short SHA>
24
+ oat_external_plan_commit: <full 40-character SHA of the inspected HEAD>
25
+ oat_external_plan_main_commit: <full 40-character SHA of the compared origin/main or merge-base>
26
+ oat_external_plan_date: '<YYYY-MM-DD>'
27
+ oat_execution_status: READY|BLOCKED
23
28
  oat_backlog_items: []
24
29
  oat_issue_url: null
25
30
  created: '<ISO 8601 UTC>'
@@ -28,6 +33,14 @@ created: '<ISO 8601 UTC>'
28
33
 
29
34
  `oat_backlog_items` contains backlog IDs represented by the plan. Keep it empty when none apply. Set `oat_issue_url` only after confirmed issue publication. Never record absolute workstation paths in durable frontmatter.
30
35
 
36
+ `oat_external_plan_commit` is the full SHA of the `HEAD` whose content was actually inspected while planning — never a fetched tip that was not read. `oat_external_plan_main_commit` records the fetched `origin/main`, or the merge-base with it, as comparison evidence only. The two SHAs may differ, and they normally do when planning happens on a branch; recording them separately is what keeps "what I read" distinct from "what I compared against". `oat_external_plan_date` is the planning date. `oat_execution_status` is `READY` when no unsatisfied hard dependency blocks execution and `BLOCKED` otherwise.
37
+
38
+ ### Legacy plans
39
+
40
+ A plan with no `oat_external_plan_date`, or dated before this contract's landing date of `2026-09-07`, is read in legacy mode. Legacy mode accepts a short `oat_external_plan_commit` SHA, a missing `oat_external_plan_main_commit`, missing `## Dependencies`, `## Landing-event impact`, and `## Revalidation Before Execution` sections, and a missing `oat_execution_status` (read as `READY`).
41
+
42
+ Legacy plans are never rewritten to satisfy the prospective rules. Retrofitting durable plans is not a prerequisite for this contract, and a rule that would make an existing plan invalid or unimportable is a defect in the rule.
43
+
31
44
  ## Plan Template
32
45
 
33
46
  ````markdown
@@ -41,6 +54,11 @@ created: '<ISO 8601 UTC>'
41
54
  > Begin with the drift check. Follow the steps and verification gates in order.
42
55
  > If a STOP condition occurs, stop and report instead of improvising.
43
56
 
57
+ > [!IMPORTANT]
58
+ > **Execution status: READY|BLOCKED.** Say why in one or two sentences: assert
59
+ > that no unsatisfied hard dependency blocks execution, or name the blocking
60
+ > dependency and the state that would unblock it.
61
+
44
62
  ## Outcome
45
63
 
46
64
  State the observable end result in 2–5 sentences. Explain why it matters and preserve the source intent in language an executor and reviewer can understand without opening the source artifact.
@@ -48,19 +66,43 @@ State the observable end result in 2–5 sentences. Explain why it matters and p
48
66
  ## Source and live evidence
49
67
 
50
68
  - Source artifact or scope: `<repo-relative path or scope>`
51
- - Planned at: commit `<short SHA>` on `<YYYY-MM-DD>`
52
- - Related backlog items: `<ID and title, or none>`
69
+ - Inspected `HEAD`: `<full SHA>` — the tree whose content this plan actually read
70
+ - Comparison baseline: `<full SHA>` — say which it is, the fetched `origin/main` tip or the merge-base with it; comparison evidence only, and it may differ from the inspected `HEAD`
71
+ - Planning date: `<YYYY-MM-DD>`
72
+ - Working tree while planning: `git status --porcelain` was empty, or every dirty path is named here
73
+ - Related backlog items: `<ID and title, or none>` — link the item from this plan body so the link runs in both directions
53
74
  - Verified evidence:
54
75
  - `<file:line or command evidence>` — what it establishes
55
76
 
56
77
  Distinguish source assertions from facts verified against the live repository. Do not copy stale evidence forward.
57
78
 
79
+ ## Dependencies
80
+
81
+ Type every dependency and name its unblock state. `Hard` blocks execution. `Soft` records an ordering, integration, or evidence preference that never blocks. `Satisfied` records a formerly hard dependency that is now met.
82
+
83
+ The first word of the Type cell is the class; anything after it is a free-form qualifier, as in `Hard ordering`, `Soft adjacency`, or `Satisfied predecessor`. Earlier plans used ad-hoc type words such as `Related, distinct`, `Downstream`, or `Open question`; those stay valid in legacy mode, and a new plan expresses the same meaning as a `Soft` row with that word as its qualifier.
84
+
85
+ | Type | Dependency | Required state | Current state |
86
+ | ------------- | ---------------------------- | ------------------------ | ------------- |
87
+ | Hard ordering | [Plan](./YYYY-MM-DD-slug.md) | Merged to `origin/main`. | Pending. |
88
+ | Soft ordering | [Plan](./YYYY-MM-DD-slug.md) | Never in one group. | Landed. |
89
+
90
+ Every `Hard` row's Current state begins with a named unblock state: `Satisfied`, `Landed`, `Merged`, or `Accepted` when it is met; `Pending`, `Blocked`, or `In flight` when it is not. State plainly whether any unsatisfied hard dependency remains, and keep `oat_execution_status` in agreement with that sentence.
91
+
92
+ Dependency state alone never disqualifies a plan. A well-formed plan whose prerequisites have not merged is written and recorded as `BLOCKED`, not withheld.
93
+
94
+ ## Landing-event impact
95
+
96
+ | Event | Affected | Files in common | Required update |
97
+ | ----------------------- | -------- | --------------- | -------------------------------------- |
98
+ | `<PR or project>` lands | Minor | `<shared file>` | Re-anchor `<citation>` before editing. |
99
+
58
100
  ## Drift check
59
101
 
60
102
  Run before editing:
61
103
 
62
104
  ```bash
63
- git diff --stat <planned-at SHA>..HEAD -- <in-scope paths>
105
+ git diff --stat <inspected HEAD SHA>..HEAD -- <in-scope paths>
64
106
  ```
65
107
  ````
66
108
 
@@ -136,10 +178,24 @@ Stop and report instead of improvising when:
136
178
  - a required change crosses an out-of-scope boundary;
137
179
  - a named verification gate fails twice after one bounded correction;
138
180
  - a load-bearing dependency, API, ownership assumption, or migration precondition is false;
181
+ - an unsatisfied hard dependency in `## Dependencies` still blocks execution, whatever `oat_execution_status` claims;
139
182
  - the work would expose, copy, or rotate a credential without explicit authority.
140
183
 
141
184
  Add plan-specific STOP conditions for its actual risks.
142
185
 
186
+ ## Revalidation Before Execution
187
+
188
+ Revalidate this plan against live state before executing when:
189
+
190
+ - substantial time passes after the planning date;
191
+ - `origin/main` advances materially from the inspected `HEAD`;
192
+ - a named in-flight project or PR lands;
193
+ - a dependency named in `## Dependencies` changes state;
194
+ - an in-scope file's step numbering, section order, or cited line anchors change;
195
+ - a load-bearing evidence claim cannot be reproduced.
196
+
197
+ Apply the `## Landing-event impact` table when one of its events has occurred. A plan executed inside a wave refreshes its drift check against the exact execution `HEAD` after predecessor lanes integrate, not only from the authored SHA to `origin/main`.
198
+
143
199
  ## Review focus
144
200
 
145
201
  - What a reviewer should inspect most closely.
@@ -159,7 +215,9 @@ oat_external_plan_index: true
159
215
  oat_external_plan_source: <source mode>
160
216
  oat_external_plan_sources:
161
217
  - <source artifact or scope>
162
- oat_external_plan_commit: <short SHA>
218
+ oat_external_plan_commit: <full 40-character SHA of the inspected HEAD>
219
+ oat_external_plan_main_commit: <full 40-character SHA of the compared origin/main or merge-base>
220
+ oat_external_plan_date: '<YYYY-MM-DD>'
163
221
  created: '<ISO 8601 UTC>'
164
222
  ---
165
223
 
@@ -187,6 +245,22 @@ not an `oat-project-import-plan` target.
187
245
 
188
246
  Do not use a repository-wide `README.md` as the index. Do not ask executors to mutate the index; execution tracking belongs to the chosen execution workflow.
189
247
 
248
+ An index records the same provenance as a plan, but it carries no `oat_execution_status` and none of the dependency, landing-event, or revalidation sections: it is not executable, so it has no execution readiness of its own. Each indexed plan carries its own status.
249
+
250
+ ## Execution Programs
251
+
252
+ A third document kind can appear in `external-plans/`: an execution program, marked `oat_execution_program: true`. Programs are written by `oat-wave-program`, not by this skill, and this contract only says how to read one.
253
+
254
+ A program maps a corpus of plans into waves. It inspects no tree, so it carries no `oat_external_plan_commit`, no `oat_external_plan_main_commit`, and no `oat_execution_status` — asking a map for provenance or execution readiness is a category error, and each plan it lists answers those questions for itself. What a program must carry instead is its ledger:
255
+
256
+ - `oat_program_indexes` listing at least one plan index path;
257
+ - a `## Status Ledger` section with a `Wave | Theme | Lanes | Status | Record` table recording at least one wave, where every Status cell is `composed`, `in-progress`, `merged`, or `done` — the vocabulary `oat-wave-program` itself uses;
258
+ - a `## Wave Table` section recording at least one plan; its heading may carry a coverage suffix, as in `## Wave Table (coverage: 31 plans = 31 index rows)`.
259
+
260
+ A program's mode is selected by `oat_external_plan_date` when it has one and by the date part of `created` otherwise, because the producing template emits `created` and no plan date. Without that fallback every generated program would sort into legacy mode permanently and never be checked at all.
261
+
262
+ A program dated on or after the contract's landing date is held to exactly the rules above; an earlier one is read in legacy mode like any other artifact. The exemption is deliberate and bounded: a program is not exempt from the contract, it is held to the part of it that applies to a map.
263
+
190
264
  ## Quality Gate
191
265
 
192
266
  Before finishing each plan, confirm:
@@ -197,4 +271,7 @@ Before finishing each plan, confirm:
197
271
  - Every step names exact files/symbols and ends in a command with an expected result.
198
272
  - Scope and STOP conditions are specific enough to prevent plausible but unauthorized expansion.
199
273
  - Frontmatter source paths are repo-relative and backlog IDs are exact.
200
- - No secret value, workstation-only absolute path, OAT task ID, or lifecycle bookkeeping appears.
274
+ - `oat_external_plan_commit` holds the full SHA of the inspected `HEAD`, `oat_external_plan_main_commit` holds the compared `origin/main` or merge-base SHA, and `oat_external_plan_date` is set.
275
+ - `oat_execution_status` is exactly `READY` or `BLOCKED` and agrees with the unblock states recorded in `## Dependencies`.
276
+ - `## Dependencies`, `## Landing-event impact`, and `## Revalidation Before Execution` are all present, and the plan body links back to its source item.
277
+ - No secret value, workstation-only absolute path, OAT phase or task ID, or canonical OAT lifecycle bookkeeping appears; external execution-readiness metadata is permitted.
@@ -11,6 +11,7 @@ interface ConfigCommandDependencies {
11
11
  readOatConfig: (repoRoot: string) => Promise<OatConfig>;
12
12
  readOatConfigForDefaultScopeRepair: (repoRoot: string) => Promise<OatConfig>;
13
13
  readOatConfigForDocumentationExcludesRepair: (repoRoot: string) => Promise<OatConfig>;
14
+ readOatConfigForInstructionPointerExcludesRepair: (repoRoot: string) => Promise<OatConfig>;
14
15
  writeOatConfig: (repoRoot: string, config: OatConfig) => Promise<void>;
15
16
  readOatLocalConfig: (repoRoot: string) => Promise<OatLocalConfig>;
16
17
  writeOatLocalConfig: (repoRoot: string, config: OatLocalConfig) => Promise<void>;
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAmBzC,OAAO,EAML,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAiBhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAGL,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAC/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,mCAAmC,EACnC,0BAA0B,EAC3B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2GpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kCAAkC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7E,2CAA2C,EAAE,CAC3C,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC7C,mCAAmC,EAAE,OAAO,mCAAmC,CAAC;IAChF,0BAA0B,EAAE,OAAO,0BAA0B,CAAC;IAC9D,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAunFD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsKT"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAIhF,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAoBzC,OAAO,EAML,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAkBhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAGL,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAC/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,mCAAmC,EACnC,0BAA0B,EAC3B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+GpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kCAAkC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7E,2CAA2C,EAAE,CAC3C,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,gDAAgD,EAAE,CAChD,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC7C,mCAAmC,EAAE,OAAO,mCAAmC,CAAC;IAChF,0BAA0B,EAAE,OAAO,0BAA0B,CAAC;IAC9D,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAwnGD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAkMT"}