@open-agent-toolkit/cli 0.3.17 → 0.3.19

package/assets/skills/oat-project-review-provide/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Edit, Bash(git:*), Bash(oat:*), Bash(pnpm:*), Bash(mkdir:*), Bash(date:*), Bash(realpath:*), Bash(awk:*), AskUserQuestion
 metadata:
-  version: 1.5.13
+  version: 1.5.14
 ---
 
 # Request Review
@@ -180,6 +180,14 @@ Inference rules (first match wins):
 | `implement` | `in_progress` | `code` with current phase scope (derive from `implementation.md` current task) |
 | `implement` | `complete`    | `code final`                                                                   |
 
+When `WORKFLOW_MODE` is `brief`, the `implement` / `in_progress` row derives
+the phase from `oat_current_task_id` by the brief pointer rule
+(`oat-project-brief/references/brief-contract.md` section 8): a task ID
+resolves to its phase, a phase ID to itself, and `null`, an unknown ID, or an
+accepted unit to the first incomplete unit in document order. A brief code
+scope is always a phase-unit (`pNN`, `p-revN`, `pNN-pMM`, or `final`), never an
+execution record.
+
 If inference produces a result, propose it and proceed unless the user overrides:
 
 ```
@@ -193,7 +201,7 @@ If the user confirms (or just presses enter), use the inferred type and scope. I
 
 - Ask: "What type of review? (code / artifact)"
 - Ask: "What scope?"
-  - For code: `pNN-tNN` task / `pNN` phase / `pNN-pMM` contiguous phase range / `final` / `base_sha=SHA` / `SHA..HEAD` range
+  - For code: `pNN-tNN` task / `pNN` phase / `pNN-pMM` contiguous phase range / `final` / `base_sha=SHA` / `SHA..HEAD` range (brief: `pNN` or `p-revN` phase / `pNN-pMM` / `final` / `base_sha=SHA` / `SHA..HEAD`)
   - For artifact: `discovery` / `spec` / `design` (and optionally `plan`)
 
 ### Step 1.5: Resolve Target Branch and Working Directory
@@ -312,6 +320,7 @@ WORKFLOW_MODE=$(oat project status --project-path "$PROJECT_PATH" --field projec
 - `quick`: `discovery.md`, `plan.md` (`spec.md`/`design.md` optional if present)
 - `import`: `plan.md` (`references/imported-plan.md` recommended, `spec.md`/`design.md` optional)
 - `lite`: `plan.md`, `implementation.md` (`discovery.md`/`spec.md`/`design.md` are absent by design)
+- `brief`: `plan.md` (the Project Brief) and `implementation.md` (the per-phase journal, which carries the `**Base:**`/`**Head:**` anchors); `discovery.md`, `spec.md`, and `design.md` are absent by design, and research under `references/` is optional
 
 **Required for artifact review:**
 
@@ -324,6 +333,7 @@ WORKFLOW_MODE=$(oat project status --project-path "$PROJECT_PATH" --field projec
   - reviewing `plan` in `spec-driven` mode requires `spec.md` + `design.md`
   - reviewing `plan` in `quick/import` mode may use `discovery.md` and/or `references/imported-plan.md` instead; lite uses the separate rule below
   - reviewing `plan` in `lite` mode requires only `plan.md`; its Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria sections are the complete upstream contract
+  - reviewing `plan` in `brief` mode requires only `plan.md`; the brief and `oat-project-brief/references/brief-contract.md` are the complete upstream contract. `discovery`, `spec`, and `design` are not reviewable artifacts in brief mode
 
 **If missing:** Report missing required artifacts for the current mode and stop if requirements are not met.
 
@@ -337,6 +347,268 @@ If review type is `artifact`:
 
 If review type is `code`, use the scope resolution below.
 
+**Step 3.0: Brief-Mode Anchor Resolution (`brief` only)**
+
+When `WORKFLOW_MODE` is `brief` and the review type is `code`, the review range
+comes from the phase anchors recorded in the journal, not from commit-message
+inference. `oat-project-brief/references/brief-contract.md` section 10 is
+authoritative where this step and the contract differ. This step is inert for
+every other workflow mode.
+
+Resolution order for brief code reviews:
+
+1. **Explicit user input** — unchanged. A supplied `base_sha=<sha>` or
+   `<sha1>..<sha2>` range skips this step; record
+   `oat_review_scope_source: explicit`, the range base as
+   `oat_review_base_sha`, and as `oat_review_phase_ids` the phases whose
+   `(pNN-` or `(prevN-` commit labels appear in the range (labels only),
+   listing a `prevN` label as its phase ID `p-revN`.
+2. **Guarded re-review narrowing** (Step 3a) — unchanged in its guards, with
+   the brief inputs described after the script below.
+3. **Anchor resolution** for a nominal `pNN`, `p-revN`, `pNN-pMM`, or `final`
+   token, by the script below.
+4. **Missing anchors** widen to the entire merge-base range.
+5. **Invalid or contradictory anchors** stop and route to
+   `oat-project-reconcile`; never narrow silently.
+6. Otherwise the explicit-range / merge-base fallback in the priority order
+   below (`oat_review_scope_source: merge-base` when the user selects
+   `merge-base..HEAD`).
+
+A brief code scope names phase-units only. An execution-record token
+(`pNN-tNN`) is not an anchored scope: offer its phase (`pNN`) or an explicit
+`<sha>^..<sha>` range built from the record's `**Commit:**` line instead.
+
+Run the resolver in bash from the reviewed checkout (after Step 1.5) with
+`PROJECT_PATH` and `SCOPE_TOKEN` set. It never edits any file. It sets
+`ANCHOR_VERDICT` (`accepted | fallback | reconcile | invalid-scope`),
+`ANCHOR_REASON`, `PHASE_IDS` (document order), `SCOPE_RANGE`,
+`REVIEW_BASE_SHA`, `AGGREGATE_HEAD`, `SCOPE_SOURCE`, `FALLBACK_REASON`, and
+`INTEGRATION_COMMITS`:
+
+````bash
+brief_phase_ids() {
+  # Phase IDs of the brief in document order; fenced code is excluded.
+  awk '
+    /^[ \t]*(```|~~~)/ { fence = !fence; next }
+    fence { next }
+    /^## Phase (p[0-9]+|p-rev[0-9]+): / { id = $3; sub(/:$/, "", id); print id }
+  ' "$PROJECT_PATH/plan.md"
+}
+
+brief_marker() {
+  # brief_marker PHASE_ID Status|Base|Head: the first exact marker line under
+  # the journal's phase heading. Ownership ends at the next line starting with
+  # "#"; fenced code is excluded; a Base or Head value that is not a full SHA,
+  # or a Status value outside the phase statuses, is not a marker.
+  awk -v id="$1" -v key="$2" '
+    /^[ \t]*(```|~~~)/ { fence = !fence; next }
+    fence { next }
+    /^#/ { owner = (index($0, "## Phase " id ": ") == 1); next }
+    !owner || found { next }
+    index($0, "**" key ":** ") == 1 {
+      v = substr($0, length("**" key ":** ") + 1); sub(/[ \t]+$/, "", v)
+      if (key == "Status" && v !~ /^(pending|in_progress|completed|failed|extracted)$/) next
+      if (key != "Status" && !((length(v) == 40 || length(v) == 64) && v ~ /^[0-9a-f]+$/)) next
+      print v; found = 1
+    }
+  ' "$PROJECT_PATH/implementation.md"
+}
+
+brief_group() {
+  # brief_group PHASE_ID: 1-based index of the declared parallel group in the
+  # brief's single-line oat_plan_parallel_groups that contains the phase.
+  awk -v id="$1" '
+    NR == 1 && /^---[ \t]*$/ { fm = 1; next }
+    fm && /^---[ \t]*$/ { exit }
+    fm && /^oat_plan_parallel_groups:/ {
+      line = $0; sub(/^oat_plan_parallel_groups:[ \t]*/, "", line); sub(/[ \t]+#.*$/, "", line)
+      n = split(line, groups, /\][ \t]*,[ \t]*\[/)
+      for (i = 1; i <= n; i++) {
+        g = groups[i]; gsub(/[^A-Za-z0-9,-]/, "", g)
+        m = split(g, members, ",")
+        for (j = 1; j <= m; j++) if (members[j] == id) { print i; exit }
+      }
+    }
+  ' "$PROJECT_PATH/plan.md"
+}
+
+brief_anchor_reject() { ANCHOR_VERDICT=reconcile; ANCHOR_REASON="$1"; }
+
+brief_resolve_anchors() {
+  ANCHOR_VERDICT=""; ANCHOR_REASON=""; SCOPE_SOURCE=""; FALLBACK_REASON=""
+  SCOPE_RANGE=""; REVIEW_BASE_SHA=""; AGGREGATE_HEAD=""; INTEGRATION_COMMITS=""
+  PHASE_IDS=()
+  local all=() id first last i start=-1 end=-1 key sha missing=0
+  local base head group prev_head="" prev_group="" fork=""
+  while IFS= read -r id; do all+=("$id"); done < <(brief_phase_ids)
+
+  # 1. Expand the requested scope to phase IDs in document order.
+  if [ "$SCOPE_TOKEN" = final ]; then
+    for id in "${all[@]}"; do
+      [ "$(brief_marker "$id" Status)" = completed ] && PHASE_IDS+=("$id")
+    done
+  else
+    first=${SCOPE_TOKEN%%-p*}; last=${SCOPE_TOKEN#"$first"}; last=${last#-}; last=${last:-$first}
+    for i in "${!all[@]}"; do
+      [ "${all[$i]}" = "$first" ] && start=$i
+      [ "${all[$i]}" = "$last" ] && end=$i
+    done
+    if [ "$start" -lt 0 ] || [ "$end" -lt "$start" ]; then
+      ANCHOR_VERDICT=invalid-scope; ANCHOR_REASON="$SCOPE_TOKEN is not a document-order phase run"; return 0
+    fi
+    for ((i = start; i <= end; i++)); do
+      [ "$(brief_marker "${all[$i]}" Status)" = extracted ] || PHASE_IDS+=("${all[$i]}")
+    done
+  fi
+  if [ "${#PHASE_IDS[@]}" -eq 0 ]; then
+    ANCHOR_VERDICT=invalid-scope; ANCHOR_REASON="no reviewable phase-unit in $SCOPE_TOKEN"; return 0
+  fi
+
+  # 2. Existence: every recorded anchor names a commit.
+  for id in "${PHASE_IDS[@]}"; do
+    for key in Base Head; do
+      sha=$(brief_marker "$id" "$key")
+      if [ -z "$sha" ]; then missing=1; continue; fi
+      git cat-file -e "$sha^{commit}" 2>/dev/null || { brief_anchor_reject "existence: $id $key $sha is not a commit"; return 0; }
+    done
+  done
+
+  # 3. Missing anchors widen to the whole merge-base range; (pNN- commit
+  #    matches only label commits and never narrow it.
+  if [ "$missing" = 1 ]; then
+    MERGE_BASE=$(git merge-base origin/main HEAD 2>/dev/null || git merge-base main HEAD 2>/dev/null)
+    REVIEW_BASE_SHA=$MERGE_BASE
+    if [ -z "$REVIEW_BASE_SHA" ]; then
+      ANCHOR_VERDICT=invalid-scope; ANCHOR_REASON="missing anchors and no merge base"; return 0
+    fi
+    AGGREGATE_HEAD=$(git rev-parse HEAD)
+    SCOPE_RANGE="$REVIEW_BASE_SHA..$AGGREGATE_HEAD"
+    INTEGRATION_COMMITS=$(git rev-list --merges "$SCOPE_RANGE")
+    ANCHOR_VERDICT=fallback; SCOPE_SOURCE=merge-base-range; FALLBACK_REASON=missing-anchors
+    return 0
+  fi
+
+  # 4. Per-phase ancestry, then sequential or parallel continuity.
+  for id in "${PHASE_IDS[@]}"; do
+    base=$(brief_marker "$id" Base); head=$(brief_marker "$id" Head); group=$(brief_group "$id")
+    git merge-base --is-ancestor "$base" "$head" 2>/dev/null || { brief_anchor_reject "ancestry: $id base is not an ancestor of its head"; return 0; }
+    if [ -n "$group" ] && [ -n "$prev_head" ] && [ "$group" = "$prev_group" ]; then
+      [ "$base" = "$fork" ] || { brief_anchor_reject "parallel continuity: $id base is not the group fork $fork"; return 0; }
+      git merge-base --is-ancestor "$prev_head" "$head" 2>/dev/null || { brief_anchor_reject "parallel continuity: $id head does not follow the previous member's integration head"; return 0; }
+    else
+      [ -z "$prev_head" ] || git merge-base --is-ancestor "$prev_head" "$base" 2>/dev/null || { brief_anchor_reject "sequential continuity: $id base does not equal or descend from the previous head"; return 0; }
+      fork=$base
+    fi
+    prev_head=$head; prev_group=$group
+  done
+  AGGREGATE_HEAD=$prev_head
+
+  # 5. Aggregate head: the last selected head contains every selected head and
+  #    is on the reviewed branch.
+  for id in "${PHASE_IDS[@]}"; do
+    git merge-base --is-ancestor "$(brief_marker "$id" Head)" "$AGGREGATE_HEAD" 2>/dev/null || { brief_anchor_reject "aggregate head: $id head is not contained in $AGGREGATE_HEAD"; return 0; }
+  done
+  git merge-base --is-ancestor "$AGGREGATE_HEAD" HEAD 2>/dev/null || { brief_anchor_reject "aggregate head: $AGGREGATE_HEAD is not on the reviewed branch"; return 0; }
+
+  REVIEW_BASE_SHA=$(brief_marker "${PHASE_IDS[0]}" Base)
+  SCOPE_RANGE="$REVIEW_BASE_SHA..$AGGREGATE_HEAD"
+  INTEGRATION_COMMITS=$(git rev-list --merges "$SCOPE_RANGE")
+  ANCHOR_VERDICT=accepted; SCOPE_SOURCE=anchors
+}
+
+brief_resolve_anchors
+````
+
+Act on the verdict:
+
+- `accepted`: the range is `SCOPE_RANGE` (first selected base through the
+  aggregate head). Coverage holds by construction: the aggregate head contains
+  every selected phase head, and every selected base sits inside the range or
+  at its start. Bookkeeping commits between sequential phases (a next base
+  that descends from the previous head) are inside the range.
+- `fallback`: the range is the entire merge-base range `MERGE_BASE..HEAD`.
+  On a `manual` invocation, show it and ask the user to confirm it; `auto` and
+  `gate` invocations print it and continue. Commit
+  matches by `(pNN-` or `(prevN-` (phase `p-revN`) label which commits belong
+  to which phase and never
+  narrow the range. Record `oat_review_scope_source: merge-base-range` and
+  `oat_review_fallback_reason: missing-anchors`.
+- `reconcile`: stop. Print
+  `Brief anchors are invalid or contradictory ({ANCHOR_REASON}); run oat-project-reconcile before reviewing {SCOPE_TOKEN}.`
+  and write no review artifact. Never fall back to a narrower range, to the
+  commit grep, or to `merge-base..HEAD`.
+- `invalid-scope`: the token is not a document-order phase run (for example
+  `pMM` precedes `pNN`, an unknown ID, or `final` with no accepted phase) or no
+  merge base exists for the fallback. Report `ANCHOR_REASON` and ask for a
+  valid scope or an explicit range; for a `gate` invocation, stop.
+
+Scope expansion: `pNN` and `p-revN` select one phase; `pNN-pMM` selects the
+contiguous document-order run, excluding extracted phases, and is invalid when
+`pMM` precedes `pNN`; `final` selects every accepted (`**Status:** completed`)
+non-extracted phase, revision phases included. Document order, not numeric
+order, governs.
+
+**Parallel continuity.** Phases in one declared group share a fork base (each
+`**Base:**` is the group's fork commit, `EXPECTED_HEAD` at group start) and
+each `**Head:**` is that phase's integration merge commit on the project
+branch, written at fan-in; the group's aggregate head is the last integration
+merge. Integration and conflict-resolution commits are inside the range: pass
+`INTEGRATION_COMMITS` (the merge commits in the range) plus any
+conflict-resolution commits the fan-in record names to the reviewer as
+integration commits and record them as `oat_review_integration_commits`. A
+group member's per-phase review runs before fan-in, when the member has no
+journal anchors yet: `oat-project-implement` supplies the range
+`EXPECTED_HEAD..<worktree head from the phase report>`, reviewed in that
+member's worktree, with `oat_review_requested_scope: pNN`,
+`oat_review_phase_ids: [pNN]`, `oat_review_base_sha: EXPECTED_HEAD`, and
+`oat_review_scope_source: anchors`. When this skill runs that review, verify
+`git merge-base --is-ancestor "$EXPECTED_HEAD" <worktree head>` first (a
+failure routes to `oat-project-reconcile`), use the supplied range without
+running the resolver, and never record it as `explicit`. The fan-in
+`**Base:**`/`**Head:**` written afterwards govern `pNN-pMM` and `final` scopes.
+The resolver verifies only the shared fork base and that member heads advance
+in document order; it does not enforce that a member head is a merge commit,
+because Parallel Group Execution step 7 may integrate a member by cherry-pick.
+
+A single group member reviewed after fan-in (`pNN` naming one member) resolves
+to `fork..<that member's integration head>`. For every member after the first
+in document order, that range also carries the earlier siblings' integration
+commits and their phase commits. Prefer the group's `pNN-pMM` run, or the
+pre-fan-in member range above, for that case. When a single member is
+requested, list its sibling phases in the Review Scope as context so the
+reviewer can attribute the sibling commits inside the range.
+
+**Late-fix rule.** A review-fix commit may advance a phase's `**Head:**`, base
+unchanged, only while no later phase in document order has a `**Base:**`. Once
+a later phase has started, the correction is an appended revision phase
+`## Phase p-revN:` with its own anchors and `**Corrects:** pNN`; the corrected
+phase keeps its original anchors. Revision phases resolve as ordinary later
+phases, so aggregate containment and sequential continuity hold for the whole
+history: a head advanced after a later phase took its base makes that later
+base precede the previous head, fails sequential continuity, and routes to
+reconcile. A `p-revN` review re-evaluates the corrected phase's findings: name
+the `**Corrects:**` phase in the Review Scope so `oat-project-review-receive`
+can update that phase's review row.
+
+**Brief inputs to Step 3a.** Run this resolver before Step 3a's candidate
+lookup. A `reconcile` or `invalid-scope` verdict stops before any narrowing.
+After `accepted` or `fallback`, Step 3a sets `REVIEW_HEAD` to `AGGREGATE_HEAD`
+(the anchored head, not the current `HEAD`) and keeps its guards unchanged.
+When it narrows, record `oat_review_scope_source: narrowed`,
+`oat_review_narrowed_from: {SCOPE_RANGE before narrowing}`,
+`oat_review_base_sha: {PRIOR_REVIEWED_HEAD}`, and keep `PHASE_IDS` from the
+resolver.
+
+**Brief artifact record.** Every brief code review carries, beside
+`oat_review_head_sha` (the aggregate head of the reviewed range):
+`oat_review_requested_scope` (the scope token as requested),
+`oat_review_phase_ids` (ordered `PHASE_IDS`), `oat_review_base_sha`,
+`oat_review_scope_source` (`anchors | merge-base-range | explicit | merge-base | narrowed`),
+and, when they apply, `oat_review_fallback_reason`,
+`oat_review_integration_commits`, and `oat_review_narrowed_from`. Step 5 passes
+them to the reviewer and Step 8 writes them; `oat-project-review-receive`
+preserves them.
+
 **Step 3a: Detect Re-Review Context**
 
 After parsing the requested scope, distinguish an explicit range override from a
@@ -349,7 +621,9 @@ For every code review, detect re-review context independently from deciding
 whether to narrow:
 
 1. Set `REVIEW_HEAD` to the full commit from
-   `git rev-parse HEAD^{commit}`. Resolve the current lineage:
+   `git rev-parse HEAD^{commit}` (in brief modes, `AGGREGATE_HEAD` from Step
+   3.0 when its verdict is `accepted` or `fallback`). Resolve the current
+   lineage:
    - `manual` and `auto` invocations use lifecycle lineage.
    - A `gate` invocation uses gate lineage qualified by its exact
      `oat_gate_target`.
@@ -422,16 +696,19 @@ narrowed range):**
 - This is the canonical scope format for checkpoint auto-reviews that need to cover multiple previously unpassed phases in one review.
 - When a phase-range token is used, treat it as a range review for artifact naming/storage, but preserve the exact `oat_review_scope` value (for example `p02-p03`) in frontmatter and plan review rows.
 
-2. **Automatic phase detection (if invoked at phase boundary):**
+  In brief modes a nominal `pNN`, `p-revN`, `pNN-pMM`, or `final` token
+  resolves through Step 3.0's anchors, never through rule 2 below.
+
+2. **Automatic phase detection (if invoked at phase boundary; not used in brief modes):**
    - Derive current phase from plan.md + implementation.md
    - Use commit convention grep to find commits:
 
      ```bash
      # Task commits: grep for (pNN-tNN)
-     git log --oneline --grep="\(p${PHASE}-t" HEAD~50..HEAD
+     git log --oneline --fixed-strings --grep="(p${PHASE}-t" --max-count=50
 
      # Phase commits: grep for (pNN-
-     git log --oneline --grep="\(p${PHASE}-" HEAD~50..HEAD
+     git log --oneline --fixed-strings --grep="(p${PHASE}-" --max-count=50
      ```
 
    - For contiguous phase-range scopes (`pNN-pMM`), aggregate commit matches for each phase in the inclusive range:
@@ -439,7 +716,7 @@ narrowed range):**
      ```bash
      for PHASE_NUM in $(seq "$START_PHASE_NUM" "$END_PHASE_NUM"); do
        PHASE_ID=$(printf "p%02d" "$PHASE_NUM")
-       git log --oneline --grep="\\(${PHASE_ID}-" HEAD~50..HEAD
+       git log --oneline --fixed-strings --grep="(${PHASE_ID}-" --max-count=50
      done
      ```
 
@@ -449,6 +726,11 @@ narrowed range):**
      - Provide `<sha1>..<sha2>` range
      - Confirm "review merge-base..HEAD" (all changes on branch)
 
+   In brief modes this fallback applies only when Step 3.0 did not resolve a
+   range (for example no nominal token). A user-selected `merge-base..HEAD`
+   records `oat_review_scope_source: merge-base`; a user-supplied base or
+   range records `explicit`.
+
    **Merge-base approach:**
 
    ```bash
@@ -509,7 +791,9 @@ case "$SCOPE_TOKEN" in
       FILES_CHANGED=$(printf "%s\n" "$PROJECT_PATH/plan.md" "$PROJECT_PATH/spec.md" "$PROJECT_PATH/design.md")
     elif [[ "$WORKFLOW_MODE" == "quick" ]]; then
       FILES_CHANGED=$(printf "%s\n" "$PROJECT_PATH/plan.md" "$PROJECT_PATH/discovery.md")
-    elif [[ "$WORKFLOW_MODE" == "lite" ]]; then
+    elif [[ "$WORKFLOW_MODE" == "lite" || "$WORKFLOW_MODE" == "brief" ]]; then
+      # brief: the reviewer also receives oat-project-brief/references/brief-contract.md
+      # as the contract reference (Step 5), not as a file in scope.
       FILES_CHANGED=$(printf "%s\n" "$PROJECT_PATH/plan.md")
     else
       FILES_CHANGED=$(printf "%s\n" "$PROJECT_PATH/plan.md" "$PROJECT_PATH/references/imported-plan.md")
@@ -594,14 +878,14 @@ Build the "Review Scope" metadata for the reviewer:
 
 **Artifact Paths:**
 
-- Spec: {PROJECT_PATH}/spec.md (required in spec-driven mode; optional in quick/import/lite)
-- Design: {PROJECT_PATH}/design.md (required in spec-driven mode; optional in quick/import/lite)
+- Spec: {PROJECT_PATH}/spec.md (required in spec-driven mode; optional in quick/import/lite; absent in brief)
+- Design: {PROJECT_PATH}/design.md (required in spec-driven mode; optional in quick/import/lite; absent in brief)
 - Plan: {PROJECT_PATH}/plan.md
 - Implementation: {PROJECT_PATH}/implementation.md
 - Discovery: {PROJECT_PATH}/discovery.md
 - Imported Plan Reference: {PROJECT_PATH}/references/imported-plan.md (optional; import mode)
 
-**Tasks in Scope (code review only):** {task IDs from plan.md matching scope}
+**Tasks in Scope (code review only):** {task IDs from plan.md matching scope; in brief modes, the execution-record IDs under the phases in scope in implementation.md, which label commits and never narrow the range}
 
 **Files Changed ({FILE_COUNT}):**
 {FILE_LIST}
@@ -658,6 +942,33 @@ and code-final Review Scope explicitly as:
 - Plan: `{PROJECT_PATH}/plan.md` (Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria are the requirements contract)
 - Implementation: `{PROJECT_PATH}/implementation.md`
 
+For `WORKFLOW_MODE=brief`, render the artifact-path portion of every
+artifact-plan and code Review Scope explicitly as:
+
+- Discovery: not required (absent by design)
+- Spec: not required (absent by design)
+- Design: not required (absent by design; the brief's optional `### Design` subsection and `references/` notes are part of the brief)
+- Import reference: not required
+- Plan: `{PROJECT_PATH}/plan.md` (the Project Brief: Goal, Outcomes, Approach, Constraints and Out of Scope, Decisions, and the in-scope phases' `**Intent:**` and `**Exit evidence:**` are the requirements contract)
+- Implementation: `{PROJECT_PATH}/implementation.md` (the per-phase journal: anchors, execution records, verification evidence)
+- Brief contract: `oat-project-brief/references/brief-contract.md`
+
+and append the brief anchor record to every brief code Review Scope:
+
+```markdown
+**Brief Anchor Record (brief code reviews only):**
+
+- oat_review_requested_scope: {SCOPE_TOKEN as requested}
+- oat_review_phase_ids: [{PHASE_IDS in document order}]
+- oat_review_base_sha: {REVIEW_BASE_SHA, full SHA}
+- oat_review_head_sha: {AGGREGATE_HEAD, full SHA}
+- oat_review_scope_source: {anchors|merge-base-range|explicit|merge-base|narrowed}
+- oat_review_fallback_reason: {missing-anchors, or omit}
+- oat_review_integration_commits: [{INTEGRATION_COMMITS plus named conflict-resolution commits, or omit}]
+- oat_review_narrowed_from: {range before narrowing, or omit}
+- Corrects: {pNN named by a p-revN phase's `**Corrects:**` line, or omit}
+```
+
 Always pass the resolved workflow mode. Never omit it and let the reviewer fall
 back to its spec-driven default.
 
@@ -987,7 +1298,7 @@ If running inline (Tier 3), execute the review and write artifact.
 **Review checklist (from oat-reviewer):**
 
 1. Verify scope (don't review out-of-scope changes)
-2. If code review: verify alignment to available requirements sources (`spec`/`design` for spec-driven mode; `discovery`/import reference for quick/import; plan.md Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria for lite)
+2. If code review: verify alignment to available requirements sources (`spec`/`design` for spec-driven mode; `discovery`/import reference for quick/import; plan.md Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria for lite; the brief's Outcomes, Constraints and Out of Scope, Decisions, and the in-scope phases' Intent and Exit evidence for brief)
 3. If code review: verify code quality (correctness, tests, security, maintainability)
 4. If artifact review: verify completeness/clarity/readiness of the artifact and its alignment with upstream artifacts
 5. Categorize findings (Critical/High/Medium/Low)
@@ -1031,6 +1342,14 @@ oat_gate_runtime: { configured runtime }
 oat_invocation_model: { configured model|provider-default|unknown }
 oat_invocation_reasoning_effort: { configured effort|provider-default|unknown }
 oat_invocation_source: { exec-target-config|unknown }
+# Brief code-review only: copy the Step 5 Brief Anchor Record verbatim.
+oat_review_requested_scope: { scope token as requested }
+oat_review_phase_ids: [{ phase IDs in document order }]
+oat_review_base_sha: { full SHA at the base of the reviewed range }
+oat_review_scope_source: { anchors|merge-base-range|explicit|merge-base|narrowed }
+oat_review_fallback_reason: { missing-anchors, only when it applies }
+oat_review_integration_commits: [{ integration commit SHAs, only when they apply }]
+oat_review_narrowed_from: { range before narrowing, only when narrowed }
 ---
 
 # {Code|Artifact} Review: {scope}

package/assets/skills/oat-project-review-receive/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.6.9
+  version: 1.6.10
 ---
 
 # Receive Review
@@ -385,6 +385,45 @@ Applies to `code` reviews only. (`artifact` reviews are handled via Step 2.6, th
 3. If scope is `pNN-pMM` (contiguous phase range): add fix tasks to the last phase in the range (`pMM`)
 4. If scope is `final` or SHA/range review: add fix tasks to a new "Review Fixes" phase or the last phase
 
+**Brief modes (`oat_workflow_mode: brief`).** The brief never carries planned
+tasks, so fix work becomes execution records in the journal and
+`oat-project-brief/references/brief-contract.md` (sections 3, 7, and 10) wins
+where this skill differs. Resolve the target phase and apply the late-fix rule:
+
+1. **Reviewed phase.** For `pNN` or `p-revN`, the reviewed phase is that
+   phase. For `pNN-pMM`, `final`, or an explicit SHA range, it is the last
+   phase in the artifact's ordered `oat_review_phase_ids`; when that field is
+   absent or empty, it is the last phase in document order whose journal
+   section has a `**Base:**`.
+2. **Late-fix rule.** If no later phase in document order has a `**Base:**`
+   in `implementation.md`, the fixes go under the reviewed phase, whose
+   journal `**Status:** completed` line is rewritten to `**Status:** in_progress`
+   (an `in_progress` phase stays `in_progress`). Its `**Base:**` never changes;
+   the fix commits advance its `**Head:**` when the phase ends again.
+3. Otherwise a later phase has started: append a revision phase with the next
+   unused `p-revN` ID. In `plan.md`, add it after the last phase block (before
+   `## Parallelism` when present) in the exact phase grammar plus the marker:
+
+   ```markdown
+   ## Phase p-revN: Review fixes for pNN
+
+   **Intent:** resolve {finding IDs} from reviews/archived/{REVIEW_FILENAME}
+   **Exit evidence:** a passing re-review of p-revN that re-evaluates pNN's findings
+   **Provisional:** no
+   **Corrects:** pNN
+   ```
+
+   In `implementation.md`, add the matching `## Phase p-revN: Review fixes for pNN`
+   section after the last phase section with `**Status:** pending` and
+   `**Corrects:** pNN` directly under the heading, and a Progress Overview row.
+   Add a pending `p-revN` `code` row to the brief's `## Reviews` table and
+   update the `## Implementation Complete` phase total. The corrected phase
+   keeps its original anchors and status.
+
+Never write `### Task` headings into the brief, and never write `**Base:**` or
+`**Head:**`: `oat-project-implement` records anchors when the phase starts and
+ends.
+
 ### Step 4: Determine Next Task IDs
 
 Read plan.md to find the last task ID in the target phase:
@@ -414,6 +453,12 @@ Derive `TASK_PREFIX` from scope:
 - Find highest task number in target phase using the correct `TASK_PREFIX` (e.g., `prev1-t02`)
 - New tasks continue sequentially: `prev1-t03`, `prev1-t04`, etc.
 
+In brief modes read the execution records under the target phase's section of
+`implementation.md` instead of `plan.md`
+(`^### Task ${TASK_PREFIX}-t[0-9]+:` inside that section). Record IDs take the
+next free ordinal and are never reused, including failed, cancelled, and
+no-change records. A new revision phase starts at `prevN-t01`.
+
 ### Step 5: Convert Findings to Tasks
 
 Each generated fix task initializes `TASK_OWNED_FILES=()` before its first
@@ -462,6 +507,26 @@ guard instead of the branch commit template above.
 - Prefix with `(review)` to indicate review-generated task
 - Use active verb: "Fix...", "Add...", "Update..."
 
+**Brief modes:** record each Critical, High, and Medium finding (and each Low
+the disposition converts) as an execution record under the target phase in
+`implementation.md`, after that phase's existing records, instead of a plan
+task:
+
+```markdown
+### Task {task_id}: (review) {Finding title}
+
+**Status:** pending
+**Source review:** reviews/archived/{REVIEW_FILENAME} ({finding IDs})
+
+Intent: {issue description and fix guidance from the review}
+Files: `{file from finding}`
+Proof: `{verification command from review or standard test command}`
+```
+
+The executor fills `**Executor:**`, the live handle, and the closing
+`**Commit:**` when the work runs, and commits with `fix({task_id}): …` so the
+message keeps `(pNN-tNN)`. Queued records never change phase totals.
+
 ### Step 6: Update Plan.md
 
 Add new tasks to plan.md in the target phase. When adding or editing tasks, preserve/restore shared `plan.md` invariants per the `oat-project-plan-writing` contract (stable task IDs, required sections, review table preservation, accurate `## Implementation Complete` totals).
@@ -484,6 +549,19 @@ Add new tasks to plan.md in the target phase. When adding or editing tasks, pres
   - Update `## Implementation Complete` totals (phase counts + total task count) so downstream PR/review summaries don’t go stale.
   - If the plan includes any phase rollups that reference task counts, update those too.
 
+In brief modes `plan.md` changes only in its `## Reviews` table and, under the
+late-fix rule, by an appended `## Phase p-revN:` block; there are no task
+totals to update. The Reviews event update below is unchanged: the same
+artifact-identified event moves to `fixes_added` with its `Reviewed Head`,
+`Invocation`, and `Gate Target` provenance preserved, and the archived
+artifact keeps its brief anchor record fields (`oat_review_requested_scope`,
+`oat_review_phase_ids`, `oat_review_base_sha`, `oat_review_scope_source`, and
+any `oat_review_fallback_reason`, `oat_review_integration_commits`, and
+`oat_review_narrowed_from`) unchanged. When a `p-revN` review is received with
+no fixes needed, its own event moves to `passed` and the event of the phase
+named by its `**Corrects:**` line that this skill set to `fixes_added` also
+moves to `passed`, citing the revision review in the implementation note.
+
 **Keep plan runnable:**
 
 - Do NOT leave plan.md in a state that blocks `oat-project-implement`.
@@ -563,6 +641,13 @@ After the fix tasks are complete:
     - `oat_phase_status: in_progress`
     - `oat_current_task: {first_fix_task_id}` (or next incomplete)
     - `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`
+  - In brief modes, write the `### Review Received: {scope}` note inside the
+    target phase's journal section after its markers, list the queued
+    execution-record IDs as the new tasks, set both `oat_current_task_id` in
+    `implementation.md` and `oat_current_task` in `state.md` to the target
+    phase ID (the reviewed phase, or the new `p-revN`), and update that phase's
+    Progress Overview row status. The phase-unit totals change only when a
+    revision phase was appended.
 
 ### Step 7.5: Archive the Consumed Review Artifact
 

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.0.5
+  version: 1.0.6
 ---
 
 # Project Revise
@@ -199,13 +199,30 @@ Fix tasks that edit synced artifacts use `oat project push` under the scope
 guard instead of the branch commit template above.
 ````
 
+**Brief modes (`oat_workflow_mode: brief`):** the brief never carries tasks.
+Insert the revision phase after the last phase block of `plan.md` (before
+`## Parallelism` when present), with Intent and Exit evidence and no
+`### Task` headings:
+
+```markdown
+## Phase p-rev{N}: Revision {N}
+
+**Intent:** {the feedback items, one clause each} (source: inline feedback, {today})
+**Exit evidence:** {verification that shows each item is addressed, and a passing review of p-rev{N}}
+**Provisional:** no
+```
+
+Add a pending `p-rev{N}` `code` row to the brief's `## Reviews` table. The
+executor opens `prev{N}-tNN` execution records in `implementation.md` when the
+work starts and commits them as `fix(prev{N}-tNN): …`; revise writes none.
+
 **Task naming:** Prefix with `(revision)` — following the `(review)` convention in review-receive.
 
 **Task IDs:** `prev{N}-t{NN}` format (e.g., `prev1-t01`, `prev1-t02`).
 
 #### 4d: Update plan.md Totals
 
-Update `## Implementation Complete` section to include the new revision phase and tasks in the totals.
+Update `## Implementation Complete` section to include the new revision phase and tasks in the totals. In brief modes the total counts phases only.
 
 #### 4e: Update implementation.md
 
@@ -216,6 +233,12 @@ Update frontmatter to point at the first revision task so `oat-project-implement
 
 Update the Progress Overview table to include the new revision phase (e.g., add a `Phase p-rev{N}` row with task count and `in_progress` status).
 
+In brief modes point the journal at the phase instead of a task: set
+`oat_current_task_id: p-rev{N}`, add a `## Phase p-rev{N}: Revision {N}`
+section after the last phase section with `**Status:** pending` directly under
+the heading (the root writes `**Base:**` when the phase starts), and add a
+`p-rev{N}` Progress Overview row with one unit, `0/1` accepted.
+
 Add a "Revision Received" entry:
 
 ```markdown
@@ -237,7 +260,7 @@ Add a "Revision Received" entry:
 #### 4f: Update state.md
 
 - `oat_phase_status: in_progress`
-- `oat_current_task: prev{N}-t01`
+- `oat_current_task: prev{N}-t01` (brief modes: `p-rev{N}`)
 - `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`
 
 #### 4g: Route to Implement
@@ -265,7 +288,7 @@ This is the key value revise adds: state transition management so agents know th
 - **Review artifact feedback:** Delegate to `oat-project-review-receive`
 - Delegating means loading the selected skill's current `SKILL.md` and following it, or dispatching a child that carries it, if environment supports skill chaining; otherwise tell the user which skill to run and stop. Never act from a remembered delegation outcome.
 
-These skills use their existing conventions: `(review)` task prefix, severity classification, standard task IDs appended to the last plan phase. This is correct — structured review feedback should go through the structured triage model.
+These skills use their existing conventions: `(review)` task prefix, severity classification, standard task IDs appended to the last plan phase. This is correct — structured review feedback should go through the structured triage model. In brief modes `oat-project-review-receive` records the fixes as `(review)` execution records in the journal under its brief-mode late-fix rule, never as plan tasks.
 
 #### 5c: Post-Delegation State