@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.
- package/assets/bundle-metadata.json +1 -1
- package/assets/docs/cli-utilities/config-and-local-state.md +1 -0
- package/assets/docs/cli-utilities/configuration.md +10 -8
- package/assets/docs/cli-utilities/project-log.md +16 -0
- package/assets/docs/cli-utilities/workflow-gates.md +124 -16
- package/assets/docs/provider-sync/commands.md +3 -0
- package/assets/docs/provider-sync/instruction-sync.md +107 -0
- package/assets/docs/reference/cli-reference.md +16 -6
- package/assets/docs/reference/oat-directory-structure.md +32 -31
- package/assets/docs/workflows/projects/lifecycle.md +45 -0
- package/assets/docs/workflows/projects/picking-up-projects.md +14 -0
- package/assets/docs/workflows/skills/explainer-kit.md +10 -4
- package/assets/docs/workflows/skills/repo-improve.md +15 -1
- package/assets/public-package-versions.json +4 -4
- package/assets/skills/oat-explainer-kit/SKILL.md +14 -1
- package/assets/skills/oat-explainer-kit/references/config-contract.md +12 -0
- package/assets/skills/oat-explainer-kit/references/lifecycle-contract.md +57 -10
- package/assets/skills/oat-explainer-kit/scripts/check-terminal-outcome.mjs +28 -5
- package/assets/skills/oat-explainer-kit/scripts/probe-recap-seams.mjs +371 -0
- package/assets/skills/oat-explainer-kit/scripts/resolve-intent.mjs +123 -1
- package/assets/skills/oat-project-autonomous/SKILL.md +10 -1
- package/assets/skills/oat-project-autonomous/references/gate-inventory.md +121 -121
- package/assets/skills/oat-project-complete/SKILL.md +134 -4
- package/assets/skills/oat-project-document/references/docs/autonomy-contract.md +121 -121
- package/assets/skills/oat-project-implement/SKILL.md +1 -1
- package/assets/skills/oat-project-implement/references/completion-and-closeout.md +38 -6
- package/assets/skills/oat-project-implement/references/docs/autonomy-contract.md +121 -121
- package/assets/skills/oat-project-lite/references/docs/autonomy-contract.md +121 -121
- package/assets/skills/oat-project-next/SKILL.md +62 -19
- package/assets/skills/oat-project-plan/SKILL.md +31 -5
- package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md +121 -121
- package/assets/skills/oat-project-progress/SKILL.md +12 -3
- package/assets/skills/oat-project-quick-start/SKILL.md +264 -4
- package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md +121 -121
- package/assets/skills/oat-project-summary/SKILL.md +34 -23
- package/assets/skills/oat-repo-improve/SKILL.md +40 -5
- package/assets/skills/oat-repo-improve/references/plan-template.md +84 -7
- package/dist/commands/config/index.d.ts +1 -0
- package/dist/commands/config/index.d.ts.map +1 -1
- package/dist/commands/config/index.js +401 -18
- package/dist/commands/gate/index.d.ts +3 -1
- package/dist/commands/gate/index.d.ts.map +1 -1
- package/dist/commands/gate/index.js +699 -211
- package/dist/commands/init/tools/shared/skill-script-references.d.ts +126 -0
- package/dist/commands/init/tools/shared/skill-script-references.d.ts.map +1 -0
- package/dist/commands/init/tools/shared/skill-script-references.js +311 -0
- package/dist/commands/instructions/instructions.types.d.ts +63 -0
- package/dist/commands/instructions/instructions.types.d.ts.map +1 -1
- package/dist/commands/instructions/instructions.utils.d.ts +51 -2
- package/dist/commands/instructions/instructions.utils.d.ts.map +1 -1
- package/dist/commands/instructions/instructions.utils.js +201 -4
- package/dist/commands/instructions/sync/sync.d.ts.map +1 -1
- package/dist/commands/instructions/sync/sync.js +12 -1
- package/dist/commands/instructions/validate/validate.d.ts.map +1 -1
- package/dist/commands/instructions/validate/validate.js +12 -1
- package/dist/commands/project/log/append.d.ts +195 -0
- package/dist/commands/project/log/append.d.ts.map +1 -1
- package/dist/commands/project/log/append.js +1034 -11
- package/dist/config/oat-config.d.ts +41 -0
- package/dist/config/oat-config.d.ts.map +1 -1
- package/dist/config/oat-config.js +111 -0
- package/package.json +2 -2
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: oat-project-summary
|
|
3
|
-
version: 1.5.
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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,
|
|
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
|
|
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: <
|
|
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
|
-
-
|
|
52
|
-
-
|
|
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 <
|
|
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: <
|
|
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
|
-
-
|
|
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;
|
|
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"}
|