@open-agent-toolkit/cli 0.3.19 → 0.3.20

package/assets/skills/oat-project-pr-progress/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(awk:*), Bash(gh:*), Bash(git:*), Bash(mktemp:*), Bash(oat:*), Bash(rm:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.3.3
+  version: 1.3.4
 ---
 
 # Progress PR
@@ -16,7 +16,7 @@ Create a progress PR description (typically at a plan phase boundary) and write
 
 Generate a PR-ready summary that is:
 
-- grounded in OAT artifacts (mode-aware: spec-driven uses spec/design; quick/import may use discovery/import reference; lite uses the five plan.md contract sections; brief uses the Project Brief's Outcomes and each phase's Intent and Exit evidence)
+- grounded in OAT artifacts (mode-aware: spec-driven uses spec/design; quick/import may use discovery/import reference; lite uses the five plan.md contract sections; brief and goal use the Project Brief's Outcomes and each phase's Intent and Exit evidence)
 - scoped to a specific phase (pNN) or an explicit git range
 - easy to paste into GitHub (or used with `gh pr create` if desired)
 
@@ -175,6 +175,16 @@ commit grep above (`oat-project-brief/references/brief-contract.md` section
   or a contradictory ordering stops the PR: route to `oat-project-reconcile`
   and never narrow the range silently.
 
+**Goal mode (`oat_workflow_mode: goal`).** A goal progress PR is a milestone
+delivery, and this skill is its registration owner. The scope is the router's
+`deliver mNN` or `deliver mNN/dNN` context, or a pending `oat_goal_recovery`
+record at stage `delivering`: the milestone's ordered phase set from the shared
+Milestones reader, or a registered delivery's frozen scope. Never derive it from
+a `pNN-pMM` range or commit labels. The Git range for the PR description is the
+set's first anchored base through its last anchored head; disclose phases of
+other milestones that fall inside it. Step 5.5 runs before Step 6 and replaces
+its optional PR creation.
+
 ### Step 2: Load Artifacts (Mode-Aware)
 
 Resolve workflow mode from `state.md` (default `spec-driven`):
@@ -313,7 +323,7 @@ oat_project: { PROJECT_PATH }
 
 ## Goals / Non-Goals
 
-{goals addressed by this phase, from available requirement artifacts: spec in spec-driven mode; discovery/import reference in quick/import mode; Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria in plan.md for lite; the phase's Intent and Exit evidence plus the brief's Outcomes for brief}
+{goals addressed by this phase, from available requirement artifacts: spec in spec-driven mode; discovery/import reference in quick/import mode; Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria in plan.md for lite; the phase's Intent and Exit evidence plus the brief's Outcomes for brief and goal}
 
 ## Changes
 
@@ -344,6 +354,89 @@ Only include links to artifacts that actually exist in the project. Omit any tha
 - Reviews: `[reviews/]({REPO_WEB}/tree/{BRANCH}/{PROJECT_REL}/reviews)` (fallback: `{PROJECT_PATH}/reviews/`) — include when active `reviews/` is tracked; omit archived review paths and any target that still matches a `localPaths` pattern
 ```
 
+### Step 5.5: Goal Delivery Registration (`goal` only)
+
+`oat-project-brief/references/brief-contract.md` sections 12.5–12.8 govern;
+this step states only the order. It never writes review dispositions, exit
+gate outcomes, or `oat_milestone` itself, and it never registers a delivery
+without passing evidence.
+
+1. **Refresh.** When `oat_deliveries` has entries, run
+   `oat project delivery refresh --project "$PROJECT_PATH" --json` and commit
+   the persisted observations as bookkeeping.
+2. **Check.** Run
+   `oat project delivery check --project "$PROJECT_PATH" --subject <mNN|dNN> --json`.
+   Register only on `status: ok` (exit 0): a passed, fresh integrated review
+   and an allowed, fresh exit carrier (`exit.source: milestone-carrier`).
+3. **Stale evidence stops before registration.** When refresh or check
+   reports the integrated review or the `exit` carrier not fresh, choose the
+   recovery stage by the section 12.5 missing-evidence order (a missing,
+   blocked or stale exit carrier → `exit_gate`; otherwise a missing or stale
+   integrated review → `reviewing`) and:
+   - **active milestone's delivery:** write `oat_milestone_status: reviewing`
+     and `oat_goal_recovery: { milestone, delivery_id, phase_ids, stage,
+review_artifact: null }`;
+   - **older milestone's delivery:** write only that targeted
+     `oat_goal_recovery` record; the active milestone's `oat_milestone`,
+     `oat_milestone_status`, `oat_current_task_id`, and `oat_current_task`
+     stay unchanged.
+
+   Commit and stop, reporting the stage owner. Never register stale evidence.
+
+**3a. Already-registered active delivery.** When the active milestone
+(`oat_milestone`) already has a non-superseded registered delivery (a `dNN`
+entry with `status: open` or `at_endpoint`), after its recovery completes at
+`delivering` or when `oat-project-goal` hands back a stale `delivered`
+milestone, run items 1–2 for that `dNN` instead of registering. On
+`status: ok`, in one bookkeeping write, clear any `oat_goal_recovery` that
+targets it, write `oat_milestone_status: delivered`, and project
+`oat_pr_status` and `oat_pr_url` from its latest member's observed status.
+Register nothing, create no pull request, and append no log entry. On a
+not-fresh report, apply item 3 (active milestone's delivery). A `registering`
+entry is not registered yet and resumes at item 5.
+
+4. **Idempotent registration.** When the active milestone has no
+   non-superseded registered delivery (item 3a), allocate the next unused
+   `dNN` and write its entry with `status: registering`: `milestone`, the
+   frozen `scope` (the ordered set), the agreed `endpoint` from the brief's
+   Delivery endpoint and authority, `kind: pr`, the persisted `lookup` keys
+   (`repository` from `gh repo view --json nameWithOwner`, `head_branch`,
+   `head_sha_at_registration` from `git rev-parse HEAD`), the
+   `integrated_review` (`artifact`, `scope`, `bound_revisions`,
+   `disposition: passed`) and the accepted `exit_gate` copied from the
+   milestone's current exit carrier, so the gate result is captured with the
+   delivery evidence. A replacement writes `covers_scope_of: <predecessor>`
+   and the predecessor's `superseded_by: <dNN>` in the same write; an additive
+   correction writes `corrects_delivery_id` instead. Commit this registration
+   record before creating anything.
+5. **Create or attach.** Generate the PR description (Steps 2–5), push the
+   branch, and create the pull request with the Step 6 commands. On resume
+   with a `registering` entry, first run
+   `gh pr list --repo <repository> --head <head_branch> --state all --json url,headRefOid`:
+   exactly one match is attached without creating a duplicate; zero matches
+   create once; more than one stops and routes to `oat-project-reconcile`.
+6. **Record.** Write the member (`url`, `base`, `reviewed_head`),
+   `status: open`, `oat_milestone_status: delivered` for the active milestone,
+   `oat_pr_status: open`, `oat_pr_url`, and `oat_phase_status: pr_open`;
+   commit this registration bookkeeping.
+7. **Log.** After that registration commit, append exactly one structural
+   entry and commit it in this same step:
+   `oat project log append --project "$PROJECT_PATH" --structural --producer oat-project-pr-progress --ref <dNN> --idempotency-key "<goal-slug>-register-<dNN>" --body "Registered <dNN> for <mNN> (<ordered phase ids>) at <url>; <goal-slug>-register-<dNN>"`.
+   Never pre-check log configuration: the helper no-ops when logging is
+   disabled.
+8. **Recovery targets.** For a pending `oat_goal_recovery` at stage
+   `delivering`, push the targeted delivery's fixes to its existing member,
+   run steps 1–2 for that `dNN`, and on `status: ok` clear the record
+   (`oat_goal_recovery: null`). When the record's milestone is not
+   `oat_milestone` (an older delivery), that is the whole write: the active
+   milestone stays untouched. When it targets the active milestone's own
+   delivery, fall through to item 3a, which clears the record and writes
+   `delivered` in one step.
+
+`delivered` means registered, open and review-ready. Activation of the next
+milestone belongs to `oat-project-goal` once the delivery reaches its agreed
+endpoint.
+
 ### Step 6: Optional - Open PR
 
 For a synced project whose user chooses to open the PR, use this ordered flow:
@@ -414,4 +507,5 @@ Do not assume `gh` is installed; if missing, instruct manual PR creation using t
 - Residual active review artifacts are archived before PR generation continues
 - Scope determined (phase or explicit range)
 - PR description artifact written to `{PROJECT_PATH}/pr/`
+- Goal mode: the delivery was registered only on a deliverable `delivery check`, idempotently, with its exit-gate result captured and one structural log entry per registration
 - User has clear next step to open PR (manual or gh)

package/assets/skills/oat-project-progress/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash(git:*), Bash(oat:*), AskUserQuestion
 metadata:
-  version: 1.4.6
+  version: 1.4.7
 ---
 
 # Progress Router
@@ -163,6 +163,7 @@ Start a new project:
   oat-project-quick-start - Start a quick workflow project
   oat-project-lite - Start a lite workflow (interview -> plan -> implement)
   oat-project-brief - Start a brief workflow (interview -> brief -> implement)
+  oat-project-goal - Start a goal workflow (interview -> brief and milestones -> deliver each milestone)
   oat-project-import-plan - Import an external markdown plan into OAT
 ```
 
@@ -174,7 +175,7 @@ Read `{project}/state.md` frontmatter:
 
 - `oat_phase` - Current phase
 - `oat_phase_status` - in_progress or complete
-- `oat_workflow_mode` - spec-driven | quick | import | lite | brief
+- `oat_workflow_mode` - spec-driven | quick | import | lite | brief | goal
 - `oat_blockers` - Any blockers
 - `oat_hill_checkpoints` - Configured gates (e.g., `["discovery", "spec", "design"]`)
 - `oat_hill_completed` - Completed HiLL checkpoints
@@ -183,6 +184,10 @@ Read `{project}/state.md` frontmatter:
 - `oat_implement_exit_gate` - The implementation exit gate record
 - `oat_quick_start_gate` - The quick-start plan gate record
 - `oat_brief_gate` - The brief artifact gate record (brief mode)
+- `oat_milestone`, `oat_milestone_status`, `oat_goal_status`, `oat_goal_recovery`,
+  `oat_milestone_gates`, and `oat_deliveries` - The active milestone, its
+  status, the declaration, any pending recovery, the per-milestone `plan` and
+  `exit` gate carriers, and the delivery registry (goal mode)
 
 Blockers may be legacy reason strings or structured `{task_id, reason, since}`
 records. Display strings as their reason; display records as
@@ -209,6 +214,9 @@ state or routing merely to render blockers.
    Gate Overrides: {gate-aware skill keys from oat_skill_gate_overrides, or "None"}
    Quick-Start Gate: {status}/{disposition}, decided {decided_at}, fingerprint {config_fingerprint} (as recorded), or "None"
    Brief Gate: {status}/{disposition}, decided {decided_at}, fingerprint {config_fingerprint} (as recorded), or "None" (brief mode only)
+   Milestone: {oat_milestone} ({oat_milestone_status}), {accepted}/{total} phases accepted in its scope (goal mode only)
+   Milestone Gates: {mNN} plan {status}/{disposition}, exit {status}/{disposition} {freshness} per milestone, as recorded (goal mode only)
+   Deliveries: {dNN} {status} ({endpoint} endpoint) per registry entry, or "None" (goal mode only)
    Exit Gate: {status}/{disposition} as recorded, or "None"
    Blockers: {oat_blockers or "None"}
    Next: {recommended_skill}
@@ -232,6 +240,13 @@ implementation workflow and is not re-derived here. Each record adds no route
 and no warning: quick plan readiness stays the single routing rule for quick
 plans, and the brief record is provenance only, read back by no route. Show "None" for an absent record, and never write or repair one here.
 
+Goal milestone carriers (`oat_milestone_gates[mNN].plan` and `.exit`) share
+the same core plus `resolution`, `subject` and `freshness`
+(`oat-project-brief/references/brief-contract.md` section 12.4). Report them as
+recorded, including `freshness` and `freshness_reason`; unlike the brief
+record, the router reads these carriers, so never recompute or repair them
+here.
+
 ### Step 5: Determine Next Skill
 
 Based on project state, recommend next action.
@@ -243,6 +258,7 @@ Read `oat_workflow_mode` from `state.md` frontmatter:
 - `import`
 - `lite`
 - `brief`
+- `goal`
 
 **HiLL override (apply before phase routing):**
 
@@ -283,8 +299,9 @@ fi
 
 If drift is detected, recommend `oat-project-reconcile` alongside the normal implementation skill.
 
-In brief mode `plan.md` carries no tasks, so skip the `PLAN_TASKS` comparison;
-compare `(pNN-tNN)` commits against the journal's execution records instead.
+In brief and goal modes `plan.md` carries no tasks, so skip the `PLAN_TASKS`
+comparison; compare `(pNN-tNN)` commits against the journal's execution
+records instead.
 
 Routing matrix by mode:
 
@@ -359,6 +376,21 @@ Brief progress counts phase-units: report `{accepted}/{total} phases accepted`
 from `oat project status`, never task counts. A provisional phase is never
 accepted, and execution records never change the totals.
 
+**Goal mode (`oat_workflow_mode: goal`):** before milestone state exists, the
+`plan` / `in_progress` row continues `oat-project-goal`. After it exists, the
+next skill is the control plane's recommendation (`oat project status --json`,
+`recommendation.skill` with its `context`), which follows the goal priority
+that `oat-project-next` tabulates: terminal recovery after a declaration,
+review feedback, a pending `oat_goal_recovery`, invalid membership, then the
+milestone status (`aligning` → `oat-project-goal`; `implementing` →
+`oat-project-implement`; `reviewing` → scoped closeout or the review owners by
+missing evidence; `delivering` → `oat-project-pr-progress`; `delivered` →
+`oat-project-goal` to re-align). Count phase-units per active milestone: report
+`{accepted}/{total} phases accepted in {mNN}` over the milestone's ordered
+phase set from `oat project status --json` (`milestoneMembership`), plus the
+whole-brief total. A pending recovery reports its own scope beside the active
+milestone; it never replaces it.
+
 **If blockers exist:**
 
 ```
@@ -383,9 +415,10 @@ Knowledge:
 Workflow:
   oat-project-lite              - Start a lite workflow (interview -> plan -> implement)
   oat-project-brief             - Start a brief workflow (interview -> brief -> implement)
+  oat-project-goal              - Start a goal workflow (interview -> brief and milestones -> deliver each milestone)
   oat-project-quick-start       - Start a quick workflow (discover -> plan -> implement)
   oat-project-import-plan       - Import an external markdown plan and normalize plan.md
-  oat-project-promote-spec-driven - Promote quick/import/lite project to spec-driven lifecycle (lite and brief promote via quick)
+  oat-project-promote-spec-driven - Promote quick/import/lite project to spec-driven lifecycle (lite, brief, and goal promote via quick)
   oat-project-discover          - Start discovery phase (requirements gathering)
   oat-project-design            - Confirm requirements + create technical design (folds spec authoring inline)
   oat-project-spec              - Optional standalone specification (most projects skip this — design handles it)

package/assets/skills/oat-project-progress/references/docs/gate-approval-record.md

@@ -62,6 +62,15 @@ replaces the record.
   core, written and read under the same rules as `oat_quick_start_gate`. It is
   absent when no gate is configured, and nothing routes on it: it is provenance
   only.
+- **`oat_milestone_gates[mNN].plan` and `.exit`** (goal mode;
+  `oat-project-goal` writes `plan` after each milestone's approval, and
+  `oat-project-implement`'s milestone closeout writes `exit`) carry the core
+  plus `resolution` (`configured`, `no_gate`, or `project_disabled`), a
+  `subject` binding (`plan` or `code` and the milestone's ordered phase set),
+  and derived `freshness` with `freshness_reason`. `reviewed_head` is `null`
+  for `no_gate` and `project_disabled`, and `no_gate` is written rather than
+  omitted because routing reads these carriers. `oat-project-brief`'s
+  `references/brief-contract.md` section 12.4 is their contract.
 
 ## Reading a quick-start record
 

package/assets/skills/oat-project-quick-start/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 2.3.20
+  version: 2.3.21
 ---
 
 # Quick Start Project
@@ -152,11 +152,13 @@ Step 3.7 — against `"$PROJECT_PATH/plan.md"`:
   `oat-project-implement/SKILL.md` and follow it to begin execution.
 
 **Promoted-brief resume.** When the resumed `plan.md` frontmatter records
-`oat_promoted_from: brief`, the project came from
-`oat project promote --to quick` (brief contract section 11), and quick plan
-readiness stays false while `oat_promotion_pending_phases` lists any phase
-(condition 6). `discovery.md` was rendered from the brief and counts as
-existing output, so re-enter at Step 2.9 and then:
+`oat_promoted_from: brief` or `oat_promoted_from: goal`, the project came from
+`oat project promote --to quick` (brief contract section 11; a goal promotes
+only at a settled delivery boundary), and quick plan readiness stays false
+while `oat_promotion_pending_phases` lists any phase (condition 6). The same
+resume serves both origins; there is no second readiness predicate.
+`discovery.md` was rendered from the brief and counts as existing output, so
+re-enter at Step 2.9 and then:
 
 1. Author executable `### Task pNN-tNN:` tasks, under Step 3's plan
    requirements, for every phase in `oat_promotion_pending_phases`, in document
@@ -166,7 +168,8 @@ existing output, so re-enter at Step 2.9 and then:
    ID is reused.
 2. In the same plan write that adds a phase's tasks, remove that phase from
    `oat_promotion_pending_phases`; when the last one is authored, write
-   `oat_promotion_pending_phases: []`. Keep `oat_promoted_from: brief`.
+   `oat_promotion_pending_phases: []`. Keep `oat_promoted_from` unchanged
+   (`brief` or `goal`).
 3. Present historical tasks (those copied from completed execution records and
    any synthesized `Accepted via phase evidence` task) as already accepted:
    their journal markers already satisfy quick progress, and they and the
@@ -176,7 +179,9 @@ existing output, so re-enter at Step 2.9 and then:
    configured gate see every task, with the historical ones labeled as accepted
    context, and the disposition Step 3.7 records is the sign-off for the newly
    authored tasks only. Existing `## Reviews` rows and the promotion provenance
-   line stay untouched.
+   line stay untouched. A promoted goal also keeps its `oat_deliveries`,
+   `oat_milestone_gates` and `oat_goal_outcome_audit` in `state.md` as
+   history; quick never edits them.
 
 If no valid active project exists:
 
@@ -658,7 +663,7 @@ Required frontmatter updates:
 
 **Promoted-brief provenance.** Promotion already wrote `oat_plan_source: quick`,
 and this step leaves it unchanged; the origin lives in `oat_promoted_from:
-brief`. Re-asserting the values above never removes `oat_promoted_from` or
+brief` or `oat_promoted_from: goal`. Re-asserting the values above never removes `oat_promoted_from` or
 `oat_promotion_pending_phases`; only the Step 0.5 promoted-brief resume shrinks
 that list as it authors each phase.