feat(org-plan): project native task progress

Author: jaromil

AGENTS.md

@@ -26,6 +26,14 @@
   The reviewer
   skips already REVIEWED milestones, so appended refinement L1s do not trigger
   repeat audits of accepted work.
+- After every successful `authoring-start`, `supervision-start`, `set`, `l2`,
+  `review`, or external `resync`, the active root runs `org-plan projection
+  PLAN` and calls host `update_plan` with its exact ordered plan items, while
+  reporting the companion explanation separately. This is a
+  best-effort UI projection only: a missing or failed host tool warns once,
+  never changes or rolls back Org state, and is retried at the next lifecycle
+  boundary. Executors report mutations; Bash and MCP code never invoke another
+  Codex tool.
 - Keep one writer active. The read-only root delegates implementation and
   corrective edits only to the active executor. Executor evidence and review
   requests go directly to the root as concise structured summaries.

plugins/gestalt/skills/org-plan/SKILL.md

@@ -34,6 +34,12 @@ changes. Use its `--help` output for exact arguments.
    any required skill is unavailable.
 4. Use helper commands for TODO and review transitions; do not hand-edit them
    during execution.
+   After each successful `authoring-start`, `supervision-start`, `set`, `l2`,
+   `review`, or external `resync`, the active root reads `org-plan projection
+   PLAN` and makes the host-owned `update_plan` call with its `plan` array,
+   reporting its companion explanation separately. This is a best-effort UI
+   projection only: tool unavailability warns without rolling back or changing
+   the authoritative Org state.
 5. Keep one writer. L2 changes remain uncommitted through L1 review.
 6. Review only DONE + UNREVIEWED L1s. A REJECT returns corrections to the same
    L1 writer. REVIEWED is valid only after explicit reviewer acceptance.
@@ -89,6 +95,10 @@ changes. Use its `--help` output for exact arguments.
    those paths and do not commit them. Then record REVIEWED.
 8. Continue until every L1 and L2 is DONE and every L1 is REVIEWED.
 
+The root performs the native projection after every successful lifecycle
+boundary named above; executors only report their successful helper mutation.
+Never ask Bash, an MCP server, or a generated profile to invoke `update_plan`.
+
 Stop only for an unavailable required skill, a material ambiguity not resolved
 by the plan and repository, or an unavailable execution prerequisite. Update
 governing `AGENTS.md` only when the completed work changes durable repository

plugins/gestalt/skills/org-plan/references/cli-state.md

@@ -7,6 +7,7 @@ state.
 |---|---|
 | Validate plan | `org-plan validate PLAN` |
 | Describe stable title, Goal/Why, position, and L1 Skills | `org-plan describe PLAN ID` |
+| Emit the read-only native Codex plan projection | `org-plan projection PLAN` |
 | Select implementation work | `org-plan next PLAN implement` |
 | Select first DONE + UNREVIEWED L1 | `org-plan next PLAN review` |
 | Transition L1 | `org-plan set PLAN L1_ID WIP\|DONE` |
@@ -19,6 +20,26 @@ state.
 
 Signals are safe no-ops when Gestalt Mobile status integration is absent.
 
+## Native Codex plan projection
+
+`org-plan projection PLAN` validates and emits a read-only JSON document with
+a companion `explanation` plus ordered `plan` items ready for the host-owned
+`update_plan` tool. Current Codex tool items accept only `step` and `status`,
+so the root passes the exact `plan` array and reports the companion explanation
+as status context. Its item statuses use tool spelling: `pending`,
+`in_progress`, and `completed` (not app-server notification spelling
+`inProgress`). It projects only L1s: `TODO` is pending, `WIP` is in progress,
+`DONE + UNREVIEWED` is in progress with “Awaiting review”, and `DONE +
+REVIEWED` is completed. The Org file remains authoritative.
+
+After every successful `authoring-start`, `supervision-start`, `set`, `l2`,
+`review`, or external `resync`, the active root runs `org-plan projection PLAN`
+and invokes host `update_plan` with its exact ordered plan items, reporting the
+companion explanation separately.
+This second action is best effort: if the host tool is absent or errors, warn
+once concisely, preserve the valid Org mutation, and retry only at the next
+lifecycle boundary. Bash helpers and MCP code never invoke `update_plan`.
+
 ## Legal progression
 
 ```text

plugins/gestalt/skills/org-plan/references/plan-format.md

@@ -15,6 +15,12 @@ prohibition. Before every implementation commit, inspect
 `git diff --cached --name-only`; it must exclude the active Org Plan and every
 `.gestalt/*.org` path.
 
+After authoring or externally correcting a valid plan, the active root reads
+`org-plan projection PLAN` and best-effort synchronizes its exact `plan` array
+to host `update_plan`, reporting the companion explanation separately. Native
+status is only a compact UI projection; it never
+authorizes an Org transition, review, or completion.
+
 ## Document metadata
 
 Include:

plugins/gestalt/skills/org-plan/references/supervised-execution.md

@@ -21,7 +21,9 @@ director (depth 0, org-plan-reviewer, Sol or Terra, read-only root)
 
 ## Start supervision
 
-1. The root signals `supervision-start`.
+1. The root signals `supervision-start`, then runs `org-plan projection PLAN`
+   and calls host `update_plan` with its exact `plan` items, reporting the
+   companion explanation separately.
 2. Before each L1, verify the preceding L1 is REVIEWED, terminate the previous
    executor, confirm closure, and resolve the next milestone with
    `org-plan describe`.
@@ -35,6 +37,12 @@ director (depth 0, org-plan-reviewer, Sol or Terra, read-only root)
 After each L2, the root verifies intended dirty paths, inspects the L2
 diff, and requires current focused-test evidence before DONE.
 
+After every successful `authoring-start`, `set`, `l2`, `review`, or external
+`resync`, the executor reports the helper mutation to the root. The root then
+runs `org-plan projection PLAN` and calls host `update_plan`; executors never
+create a competing native projection. A missing or failed host tool produces
+one concise warning and never reverses a valid Org mutation.
+
 After all L2s, require a current full-suite pass and intended complete L1 diff.
 Use `org-plan next PLAN review`; request review only for the selected DONE +
 UNREVIEWED L1. The request contains:

plugins/gestalt/skills/org-plan/scripts/org-plan

@@ -2,7 +2,7 @@
 # Strict helper for the small Org dialect used by the org-plan skill.
 set -Eeuo pipefail
 
-usage() { printf 'usage: org-plan {validate|next|summary|describe|review|l2|measure|set|signal|prepare-executor|prepare-supervision} [args]\n' >&2; exit 2; }
+usage() { printf 'usage: org-plan {validate|next|summary|describe|projection|review|l2|measure|set|signal|prepare-executor|prepare-supervision} [args]\n' >&2; exit 2; }
 die() { printf '%s: %s\n' "$plan" "$*" >&2; return 1; }
 declare -a ids states levels lines titles parents starts ends review_status review_status_count review_lines skills skills_count
 declare -A seen field field_value
@@ -126,6 +126,60 @@ json_escape() {
   printf '%s' "$output"
 }
 
+# Native Codex plans are a compact display projection, so keep individual
+# strings bounded even when an Org author supplies unusually long prose.
+bounded_text() {
+  local value=$1 limit=${2:-240}
+  if (( ${#value} > limit )); then printf '%s…' "${value:0:limit-1}"; else printf '%s' "$value"; fi
+}
+
+projection() {
+  local i j position=0 total=0 reviewed=0 active=0 active_index=-1 active_position=0 status title goal current_l2='' explanation l2_position l2_total
+  for ((i=0; i<count; i++)); do (( levels[$i] == 1 )) && total=$((total + 1)); done
+  for ((i=0; i<count; i++)); do
+    (( levels[$i] == 1 )) || continue
+    [[ ${states[$i]} == DONE && ${review_status[$i]} == REVIEWED ]] && reviewed=$((reviewed + 1))
+    if [[ ${states[$i]} == WIP || (${states[$i]} == DONE && ${review_status[$i]} == UNREVIEWED) ]]; then
+      active=$((active + 1)); active_index=$i
+    fi
+  done
+  (( active <= 1 )) || die 'native projection has multiple in_progress L1 items'
+  if (( active_index >= 0 )); then
+    for ((i=0; i<count; i++)); do (( levels[$i] == 1 && i <= active_index )) && active_position=$((active_position + 1)); done
+    goal=${field_value[$active_index:Goal]:-${field_value[$active_index:Why]:-}}
+    current_l2=''; l2_position=0; l2_total=0
+    for ((j=0; j<count; j++)); do (( levels[$j] == 2 && parents[$j] == active_index )) && l2_total=$((l2_total + 1)); done
+    for ((j=0; j<count; j++)); do
+      (( levels[$j] == 2 && parents[$j] == active_index )) || continue
+      l2_position=$((l2_position + 1))
+      if [[ ${states[$j]} == WIP ]]; then current_l2="Current L2 $l2_position/$l2_total: ${titles[$j]} (${states[$j]})"; break; fi
+      [[ -n $current_l2 || ${states[$j]} != TODO ]] || current_l2="Next L2 $l2_position/$l2_total: ${titles[$j]} (${states[$j]})"
+    done
+    [[ -n $current_l2 ]] || current_l2='All L2 milestones complete.'
+    explanation="L1 $active_position/$total — ${titles[$active_index]}. Goal: $(bounded_text "$goal" 180). $current_l2"
+    [[ ${states[$active_index]} != DONE ]] || explanation="Awaiting review. $explanation"
+  else
+    explanation="No L1 is active. $reviewed/$total L1 milestones are reviewed. Org state remains authoritative."
+  fi
+  printf '{"explanation":"%s","plan":[' "$(json_escape "$(bounded_text "$explanation")")"
+  local first=1
+  for ((i=0; i<count; i++)); do
+    (( levels[$i] == 1 )) || continue
+    position=$((position + 1))
+    case "${states[$i]}:${review_status[$i]}" in
+      TODO:*) status=pending ;;
+      WIP:*) status=in_progress ;;
+      DONE:UNREVIEWED) status=in_progress ;;
+      DONE:REVIEWED) status=completed ;;
+      *) die "invalid native projection state for ${ids[$i]}" ;;
+    esac
+    title="L1 $position/$total — ${titles[$i]}"
+    (( first )) || printf ','; first=0
+    printf '{"step":"%s","status":"%s"}' "$(json_escape "$(bounded_text "$title")")" "$status"
+  done
+  printf ']}\n'
+}
+
 canonical_plan_path() {
   local original=$1 path parent base target hops=0
   case $original in /*) path=$original ;; *) path=$PWD/$original ;; esac
@@ -353,7 +407,7 @@ write_profile() {
 
 prepare_executor() {
   local model='gpt-5.6-terra' profile_name='org-plan-executor' agents_dir="${HOME:?HOME is required}/.codex/agents"
-  local lifecycle_requirements=' During supervised execution, direct TODO keyword or property edits are forbidden. Use org-plan set PLAN L1_ID WIP|DONE for L1 transitions and org-plan l2 PLAN L2_ID WIP|DONE for L2 transitions. Use org-plan next PLAN review and org-plan review PLAN L1_ID REVIEWED|UNREVIEWED for review selection and state. After any externally corrected plan file, run org-plan signal PLAN resync. Org Plan files are never Git deliverables: no user request, repository instruction, or release workflow overrides the ban on staging, committing, force-adding, cherry-picking, or otherwise introducing an Org Plan into Git history. Immediately before every accepted L1 commit, inspect git diff --cached --name-only; it must exclude the active Org Plan and every .gestalt/*.org path, including force-added paths. Status publication is optional when neither GESTALT_MOBILE_ORG_PLAN_STATUS_DIRECTORY nor the legacy GESTALT_MOBILE_ORG_PLAN_STATUS_FILE is present.'
+  local lifecycle_requirements=' During supervised execution, direct TODO keyword or property edits are forbidden. Use org-plan set PLAN L1_ID WIP|DONE for L1 transitions and org-plan l2 PLAN L2_ID WIP|DONE for L2 transitions. Use org-plan next PLAN review and org-plan review PLAN L1_ID REVIEWED|UNREVIEWED for review selection and state. After any externally corrected plan file, run org-plan signal PLAN resync. After every successful authoring-start, supervision-start, set, l2, review, or resync helper action, report the mutation to the active root; executors never invoke host update_plan or create a competing native projection. Org Plan files are never Git deliverables: no user request, repository instruction, or release workflow overrides the ban on staging, committing, force-adding, cherry-picking, or otherwise introducing an Org Plan into Git history. Immediately before every accepted L1 commit, inspect git diff --cached --name-only; it must exclude the active Org Plan and every .gestalt/*.org path, including force-added paths. Status publication is optional when neither GESTALT_MOBILE_ORG_PLAN_STATUS_DIRECTORY nor the legacy GESTALT_MOBILE_ORG_PLAN_STATUS_FILE is present.'
   while (( $# )); do
     case $1 in
       --model) (( $# >= 2 )) || usage; model=$2; shift 2 ;;
@@ -376,7 +430,7 @@ prepare_supervision() {
   local executor_model='gpt-5.6-terra' reviewer_model='gpt-5.6-sol'
   local executor_name='org-plan-executor' reviewer_name='org-plan-reviewer'
   local agents_dir="${HOME:?HOME is required}/.codex/agents"
-  local lifecycle_requirements=' Before the first L1, run org-plan signal PLAN supervision-start. During supervised execution, direct TODO keyword or property edits are forbidden. Require the executor to use org-plan set PLAN L1_ID WIP|DONE and org-plan l2 PLAN L2_ID WIP|DONE for all state transitions, retain org-plan next PLAN review and org-plan review PLAN L1_ID REVIEWED|UNREVIEWED for review selection and state, and run org-plan signal PLAN resync after any externally corrected plan file. Org Plan files are never Git deliverables: no user request, repository instruction, or release workflow overrides the ban on staging, committing, force-adding, cherry-picking, or otherwise introducing an Org Plan into Git history. Immediately before every accepted L1 commit, inspect git diff --cached --name-only; it must exclude the active Org Plan and every .gestalt/*.org path, including force-added paths. Status publication is optional when neither GESTALT_MOBILE_ORG_PLAN_STATUS_DIRECTORY nor the legacy GESTALT_MOBILE_ORG_PLAN_STATUS_FILE is present.'
+  local lifecycle_requirements=' Before the first L1, run org-plan signal PLAN supervision-start. During supervised execution, direct TODO keyword or property edits are forbidden. Require the executor to use org-plan set PLAN L1_ID WIP|DONE and org-plan l2 PLAN L2_ID WIP|DONE for all state transitions, retain org-plan next PLAN review and org-plan review PLAN L1_ID REVIEWED|UNREVIEWED for review selection and state, and run org-plan signal PLAN resync after any externally corrected plan file. After every successful authoring-start, supervision-start, set, l2, review, or resync helper action, the active root runs org-plan projection PLAN and makes the host-owned update_plan call with its exact plan items, reporting the companion explanation separately. Executors report mutations and never invoke host update_plan or create a competing native projection. If update_plan is absent or fails, warn once, keep Org state authoritative, and retry only at the next lifecycle boundary; Bash and MCP code never invoke it. Org Plan files are never Git deliverables: no user request, repository instruction, or release workflow overrides the ban on staging, committing, force-adding, cherry-picking, or otherwise introducing an Org Plan into Git history. Immediately before every accepted L1 commit, inspect git diff --cached --name-only; it must exclude the active Org Plan and every .gestalt/*.org path, including force-added paths. Status publication is optional when neither GESTALT_MOBILE_ORG_PLAN_STATUS_DIRECTORY nor the legacy GESTALT_MOBILE_ORG_PLAN_STATUS_FILE is present.'
   while (( $# )); do
     case $1 in
       --executor-model) (( $# >= 2 )) || usage; executor_model=$2; shift 2 ;;
@@ -455,6 +509,8 @@ case $cmd in
       label=Why
       printf 'L2 %s\n%s: %s\n' "${titles[$target]}" "$label" "${field_value[$target:$label]}"
     fi ;;
+  projection)
+    [ $# = 1 ] || usage; parse "$1"; projection "$1" ;;
   review)
     [ $# = 3 ] || usage; original=$1; parse "$original"; target=$(find_id "$2") || die "unknown ID $2"; new=$3
     (( levels[$target] == 1 )) || die "ID $2 is not an L1"