okstra 0.170.3 → 0.172.0

package/runtime/prompts/profiles/implementation-planning.md

@@ -177,7 +177,14 @@
     ```
 
     An `AGREE` note records the counterexample considered and its exclusion reason. If the judgement needs unavailable external material, record `verification-error`, not `DISAGREE`. **Enforced:** `validators/validate-run.py` `_validate_plan_item_extraction_completeness` compares the exact deterministic set, independently rejecting missing, unexpected, and duplicate plan-item IDs, including `P-Prep-*`.
-  - **§5.5.9 Plan Body Verification (BLOCKING).** After report-writer finishes the draft, the lead MUST run a worker peer-review round on the consolidated plan body (Option Candidates / Trade-off Matrix / Recommended Option / Stage Map and per-stage sections / Dependency / Validation Checklist / Rollback / Requirement Coverage) and populate `### 5.5.9 Plan Body Verification` in the final report. The round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics, gate-result classification, and dissent log format are defined in `prompts/lead/plan-body-verification.md`. The four gate-result values are `passed`, `passed-with-dissent`, `blocked-by-disagreement`, `aborted-non-result`. When the gate would have been `blocked-by-disagreement` or `aborted-non-result`, the lead MUST NOT silently flip it to one of the passing values to "unblock" the run — that is a contract violation. **Enforced:** `validators/validate-run.py` `_validate_plan_body_gate_recompute` re-derives the gate from `planItems[].verdicts` and fails when the declared `gateResult` claims a healthier outcome than the recorded votes support; `_validate_plan_item_extraction_completeness` fails when any plan-body deliverable category is under-extracted into `planItems`, so a dropped item can no longer dodge the gate. When `convergence.adversarial=true` (the default for this phase), this round uses the adversarial posture — verifiers confirm cited paths/commands and the burden of proof is on the plan — but the gate threshold stays `majority-disagree` (see that skill's §"Adversarial plan-body posture"). Among the majority-disagree items, those that are majority-`planner-fixable` go through report-writer self-fix rounds (`prompts/lead/plan-body-verification.md` "Self-fix round"). A `planner-fixable` item that survives the budget is **not** promoted to the user — it becomes a Working Assumption in `## 5. Missing Information and Risks` and folds into `passed-with-dissent`, because a defect the planner could have fixed is not a user decision. Only majority-`needs-user-input` items, and correctness-critical defects (`DISAGREE` kind `a`, or `f` on `P-Req-*`) regardless of fixability, become `Blocks=approval` clarifications. Rollback ordering (`d`) is advisory and never blocks approval — a rollback is executed by a human. `validators/validate-run.py` `_validate_self_fix_before_clarification` fails a planner-fixable majority item promoted without a self-fix as `contract-violated`.
+  - **§5.5.9 Plan Body Verification (BLOCKING).** After report-writer finishes the draft, the lead MUST run a worker peer-review round on the consolidated plan body (Option Candidates / Trade-off Matrix / Recommended Option / Stage Map and per-stage sections / Dependency / Validation Checklist / Rollback / Requirement Coverage) and populate `### 5.5.9 Plan Body Verification` in the final report. The round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics, gate-result classification, and dissent log format are defined in `prompts/lead/plan-body-verification.md`. The fixed order is initial verification → one planner self-fix → targeted re-verification → user gate. The initial verification is round 1, the targeted re-verification is round 2, and a second automatic self-fix is a contract violation. The four gate-result values are `passed`, `passed-with-dissent`, `blocked-by-disagreement`, `aborted-non-result`. When the gate would have been `blocked-by-disagreement` or `aborted-non-result`, the lead MUST NOT silently flip it to one of the passing values to "unblock" the run — that is a contract violation. **Enforced:** `validators/validate-run.py` `_validate_plan_body_gate_recompute` re-derives the gate from `planItems[].verdicts` and fails when the declared `gateResult` claims a healthier outcome than the recorded votes support; `_validate_plan_item_extraction_completeness` fails when any plan-body deliverable category is under-extracted into `planItems`, so a dropped item can no longer dodge the gate. When `convergence.adversarial=true` (the default for this phase), this round uses the adversarial posture — verifiers confirm cited paths/commands and the burden of proof is on the plan — but the gate threshold stays `majority-disagree` (see that skill's §"Adversarial plan-body posture"). Among the majority-disagree items, those that are majority-`planner-fixable` receive one report-writer self-fix (`prompts/lead/plan-body-verification.md` "Self-fix round"). A surviving item is classified as `user-decision`, `noncritical-dissent`, or `correctness-critical`, and every classification remains a `Blocks=approval` clarification until its own release condition passes. Self-fix exhaustion alone never accepts `noncritical-dissent`; only an explicit, activity-backed `accept-risk` lowers it to `passed-with-dissent`. `correctness-critical` never permits `accept-risk` and resolves only after targeted re-verification records `AGREE` or an acceptable `SUPPLEMENT` and independent Requirement Coverage blockers are gone. Rollback ordering (`d`) is advisory and never blocks approval — a rollback is executed by a human. A user-directed correction does not consume the automatic self-fix limit, and a verification failure after that correction does not restart the automatic loop. `validators/validate-run.py` `_validate_self_fix_before_clarification`, `_validate_approval_context`, and `_resolved_noncritical_dissent_ids` enforce these rules.
+  - **Approval decision state.** Every activity-contract-v1 approval row carries `approvalContext` with its classification, linked plan item IDs, `user-decision-required` activity IDs, release condition, and classification-appropriate recommended disposition. Every structured option carries its gate `disposition`; `/okstra-user-response` copies that exact value into the sidecar rather than replacing it with `answer`. A resolved row also carries the user's non-empty raw text and `user-decision-evaluated` check references.
+    - `open → answered` when the raw user response is recorded
+    - `answered → resolved` only after the selected disposition is applied and its checks pass
+    - `answered → open` when application or checking fails
+    - `open → obsolete` only when a plan change removes the question
+    `open` and `answered` block approval; only `resolved` and `obsolete` are non-blocking. **Enforced:** `validators/validate-run.py` `_validate_approval_context` plus run-prep `scripts/okstra_ctl/run.py` `_validate_approved_plan`.
+  - **Terminal approval evidence.** A terminal row preserves a pre-correction dissent classification only when the plan-body state sidecar's superseded votes prove it; the validator does not trust `approvalContext.classification` by itself. Every cited `user-decision-required` / `user-decision-evaluated` activity cites exactly the row's `C-NNN` and exactly the linked `approvalContext.planItemIds` set. A resolved correctness-critical row also binds `resolution.checkRefs` to a later successful evaluation, its zero-exit commands and plan-body state result path, one explicit `plan-body-verification:round-N` token, and matching successful state/report verdicts. That human-response round does not increment `selfFixRoundsApplied`; the automatic cap remains one rewrite. After correcting an independent coverage-only blocker, retain its `C-NNN` in the non-blocking Requirement Coverage row's `decisionRefs` and the matching state-sidecar plan item's `clarificationId`; that item must have no historical blocking dissent and must participate in the historical `coverage-gap` round. A run-wide `coverage-gap` without the item-level `C-NNN` link is insufficient. `obsolete` is invalid while a current linked question, disagreement, or coverage blocker remains active, including a current `user-decision`. **Enforced:** `validators/validate-run.py` `_read_approval_history`, `_activity_matches_approval_context`, `_validate_correctness_resolution`, `_historical_coverage_clarification_ids`, and `_validate_approval_context`.
   - **Decision-record evaluation (sole owner)**: this phase is the **single owner** of decision-record evaluation in the okstra lifecycle. The brief never evaluates or drafts decision records — it only forwards `adr-candidate:*` signals. Every `adr-candidate:*` entry inherited from the brief's `Open Questions` is a mandatory evaluation target. In addition, evaluate every decision the recommended option introduces against the three criteria:
     1. **Hard to reverse** — would changing the decision later cost meaningfully more than deciding now?
     2. **Surprising without context** — would a future reader, seeing only the code, wonder "why was it built this way?"?

package/runtime/python/okstra_ctl/adapters/hosts/antigravity/relay.md

@@ -81,7 +81,7 @@ Render every numbered item as its option label followed by its description verba
 | `await_workers` | Await native host workers through the host primitive and CLI workers through their status sidecars, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Materialize and verify a fresh invocation, then start a fresh native worker or deterministic `worker-dispatch` attempt according to the persisted runner. |
 | `shutdown_workers` | Perform host or process cleanup only for resources owned by this run. |
-| `record_lead_event` | Append the required structured event to the manifest-provided `leadEventsPath`; emit the matching user-facing `PROGRESS:` line. |
+| `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`. Emit the matching `PROGRESS:` line and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
 | `collect_usage` | Collect host- or artifact-backed usage through the existing Okstra token-usage path; do not substitute another runtime's session log. |
 
 ## Antigravity dispatch details

package/runtime/python/okstra_ctl/adapters/hosts/claude-code/relay.md

@@ -140,7 +140,7 @@ For a `host-text` mapping, render each numbered item as its option label followe
 | `await_workers` | Arm one background shell poll for the pending Result Paths; the spawn acknowledgement is not completion. |
 | `redispatch_worker` | Materialize and verify a fresh invocation, then use a fresh native `Agent(...)` session or `okstra worker-dispatch` attempt according to the persisted runner. |
 | `shutdown_workers` | For each confirmed-complete worker selected for cleanup, send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to idle the roster member **and** call `TaskStop(task_id: "<name>")` to stop its background task. Both are required; neither subsumes the other. |
-| `record_lead_event` | Emit the required `PROGRESS:` line as assistant text and persist core-required state/artifact updates. |
+| `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`, including activity-contract-v1 records. Emit the matching `PROGRESS:` line and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
 | `collect_usage` | Run `okstra token-usage` against the team-state; it reads the run-scoped `~/.claude/projects` session JSONL evidence. |
 
 ## Dispatch variants

package/runtime/python/okstra_ctl/adapters/hosts/codex/relay.md

@@ -81,7 +81,7 @@ Render every numbered item as its option label followed by its description verba
 | `await_workers` | Await native host workers through the host primitive and CLI workers through synchronous dispatch, then verify team-state terminal records and Result Paths for both. |
 | `redispatch_worker` | Materialize and verify a fresh invocation, then start a fresh native worker or `okstra worker-dispatch` attempt according to the persisted runner. |
 | `shutdown_workers` | Perform process cleanup when a wrapper remains live; otherwise this operation is a no-op recorded in state. |
-| `record_lead_event` | Append the required structured event to the manifest-provided `leadEventsPath`; emit the matching user-facing `PROGRESS:` line. |
+| `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`. Emit the matching `PROGRESS:` line and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
 | `collect_usage` | Collect artifact/rollout-backed usage through the existing Okstra token-usage path; never read Claude session JSONL as a substitute. |
 
 ## Codex dispatch details

package/runtime/python/okstra_ctl/adapters/hosts/external/relay.md

@@ -81,7 +81,7 @@ Render every numbered item as its option label followed by its description verba
 | `await_workers` | Run `okstra team await --project-root <root> --run-manifest <path>` through the host's asynchronous shell facility. |
 | `redispatch_worker` | Create the core-specified fresh jobs file and dispatch it with a new `dispatchKind`; never reuse a live worker conversation. |
 | `shutdown_workers` | Run `okstra team teardown --project-root <root> --run-manifest <path>` only after the user-approved cleanup gate. |
-| `record_lead_event` | Append the required structured event to the manifest-provided `leadEventsPath`; emit the matching user-facing `PROGRESS:` line. |
+| `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`. Emit the matching `PROGRESS:` line and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
 | `collect_usage` | Collect artifact/CLI-log-backed usage through the existing Okstra token-usage path; never substitute another runtime's session log. |
 
 ## External dispatch details

package/runtime/python/okstra_ctl/adapters/hosts/grok/relay.md

@@ -80,7 +80,7 @@ Render every numbered item as its option label followed by its description verba
 | `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |
 | `shutdown_workers` | Clean up only host or process resources owned by this run. |
-| `record_lead_event` | Append the required structured event to `leadEventsPath` and emit the matching progress line. |
+| `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`. Emit the matching `PROGRESS:` line and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
 | `collect_usage` | Return explicit unavailable lead usage until Grok registers a session transcript or CLI usage artifact contract. |
 
 ## Completion, cleanup, and resume

package/runtime/python/okstra_ctl/adapters/hosts/kimi/relay.md

@@ -80,7 +80,7 @@ Render every numbered item as its option label followed by its description verba
 | `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |
 | `shutdown_workers` | Clean up only host or process resources owned by this run. |
-| `record_lead_event` | Append the required structured event to `leadEventsPath` and emit the matching progress line. |
+| `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`. Emit the matching `PROGRESS:` line and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
 | `collect_usage` | Return explicit unavailable lead usage until Kimi registers a session transcript or CLI usage artifact contract. |
 
 ## Completion, cleanup, and resume

package/runtime/python/okstra_ctl/agent_activity.py

@@ -0,0 +1,306 @@
+"""Record lead activity and project it into final-report data."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import tempfile
+from collections.abc import Mapping, Sequence
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from okstra_ctl.lead_events import (
+    LeadEvent,
+    append_activity_event,
+    read_lead_events,
+)
+from okstra_ctl.worker_audit_ledger import (
+    EvidenceCommand,
+    parse_evidence_commands,
+    read_evidence_commands,
+)
+
+
+ACTIVITY_KINDS = frozenset({
+    "worker-dispatched",
+    "worker-completed",
+    "verification-round-completed",
+    "self-fix-applied",
+    "user-decision-required",
+    "user-decision-evaluated",
+})
+ACTIVITY_OUTCOMES = frozenset({
+    "pending",
+    "completed",
+    "failed",
+    "blocked",
+    "resolved",
+})
+ACTIVITY_FIELDS = (
+    "activityId",
+    "kind",
+    "agent",
+    "summary",
+    "planItemIds",
+    "resultPath",
+    "commands",
+    "evidenceRefs",
+    "outcome",
+)
+_ACTIVITY_ID_RE = re.compile(r"^A-(\d{3,})$")
+
+
+class ActivityProjectionError(ValueError):
+    """Raised when activity cannot be recorded or projected safely."""
+
+
+def _read_json_object(path: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ActivityProjectionError(f"cannot read JSON object {path}: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise ActivityProjectionError(f"JSON value must be an object: {path}")
+    return payload
+
+
+def _resolve_project_path(project_root: Path, value: str | Path) -> Path:
+    path = Path(value)
+    return path if path.is_absolute() else project_root / path
+
+
+def _require_string(payload: Mapping[str, Any], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ActivityProjectionError(f"required string missing: {key}")
+    return value.strip()
+
+
+def _manifest_run_seq(manifest: Mapping[str, Any]) -> str:
+    sequences = manifest.get("runSequencesByCategory")
+    if not isinstance(sequences, Mapping):
+        raise ActivityProjectionError(
+            "run manifest has no runSequencesByCategory object"
+        )
+    return _require_string(sequences, "manifests")
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _activity_row(event: LeadEvent) -> dict[str, Any]:
+    details = dict(event.details)
+    missing = [key for key in ACTIVITY_FIELDS if key not in details]
+    if missing:
+        raise ActivityProjectionError(
+            "activity event is missing " + ", ".join(missing)
+        )
+    if details["kind"] not in ACTIVITY_KINDS:
+        raise ActivityProjectionError(
+            f"unsupported activity kind: {details['kind']}"
+        )
+    if details["outcome"] not in ACTIVITY_OUTCOMES:
+        raise ActivityProjectionError(
+            f"unsupported activity outcome: {details['outcome']}"
+        )
+    activity_id = details["activityId"]
+    if (
+        not isinstance(activity_id, str)
+        or _ACTIVITY_ID_RE.fullmatch(activity_id) is None
+    ):
+        raise ActivityProjectionError(f"invalid activityId: {activity_id}")
+    return {key: details[key] for key in ACTIVITY_FIELDS}
+
+
+def _validate_activity_order(rows: Sequence[Mapping[str, Any]]) -> None:
+    ids = [str(row["activityId"]) for row in rows]
+    if len(ids) != len(set(ids)):
+        raise ActivityProjectionError("activityId values must be unique")
+    numbers = [int(_ACTIVITY_ID_RE.fullmatch(value).group(1)) for value in ids]
+    if any(current <= previous for previous, current in zip(numbers, numbers[1:])):
+        raise ActivityProjectionError(
+            "activity events must be in strict activityId order"
+        )
+
+
+def _atomic_write_json(path: Path, payload: Mapping[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as handle:
+            temporary_path = Path(handle.name)
+            json.dump(payload, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+        os.replace(temporary_path, path)
+    finally:
+        if temporary_path is not None and temporary_path.exists():
+            temporary_path.unlink()
+
+
+def record_activity(
+    project_root: Path,
+    run_manifest_path: Path,
+    details: Mapping[str, Any],
+    timestamp: str | None = None,
+) -> LeadEvent:
+    """Append one activity event using identity from its run manifest."""
+    manifest = _read_json_object(run_manifest_path)
+    if manifest.get("activityContractVersion") != 1:
+        raise ActivityProjectionError(
+            "run manifest does not declare activityContractVersion 1"
+        )
+    event = LeadEvent(
+        event_type="activity",
+        lead_runtime=_require_string(manifest, "leadRuntime"),
+        task_key=_require_string(manifest, "taskKey"),
+        task_type=_require_string(manifest, "taskType"),
+        run_seq=_manifest_run_seq(manifest),
+        timestamp=timestamp or _utc_now(),
+        details=dict(details),
+    )
+    events_path = _resolve_project_path(
+        project_root, _require_string(manifest, "leadEventsPath")
+    )
+    return append_activity_event(events_path, event)
+
+
+def project_agent_activity(
+    project_root: Path,
+    run_manifest_path: Path,
+    data_path: Path,
+) -> tuple[dict[str, Any], ...]:
+    """Replace only ``agentActivity`` with this run's canonical events."""
+    manifest = _read_json_object(run_manifest_path)
+    if manifest.get("activityContractVersion") != 1:
+        return ()
+    events_path = _resolve_project_path(
+        project_root, _require_string(manifest, "leadEventsPath")
+    )
+    run_seq = _manifest_run_seq(manifest)
+    task_key = _require_string(manifest, "taskKey")
+    task_type = _require_string(manifest, "taskType")
+    events = (
+        event
+        for event in read_lead_events(events_path)
+        if event.event_type == "activity"
+        and event.task_key == task_key
+        and event.task_type == task_type
+        and event.run_seq == run_seq
+    )
+    rows = tuple(_activity_row(event) for event in events)
+    _validate_activity_order(rows)
+    data = _read_json_object(data_path)
+    data["agentActivity"] = list(rows)
+    _atomic_write_json(data_path, data)
+    return rows
+
+
+def _parse_command_records(raw_records: Sequence[str]) -> tuple[EvidenceCommand, ...]:
+    content = "\n".join(
+        f"- Evidence command: {record}" for record in raw_records
+    )
+    commands, failures = parse_evidence_commands(content)
+    if failures:
+        raise ActivityProjectionError("; ".join(failures))
+    return commands
+
+
+def _activity_commands(args: argparse.Namespace) -> tuple[EvidenceCommand, ...]:
+    commands = list(_parse_command_records(args.command_record))
+    if args.audit_sidecar is not None:
+        audit_commands, failures = read_evidence_commands(args.audit_sidecar)
+        if failures:
+            raise ActivityProjectionError("; ".join(failures))
+        commands.extend(audit_commands)
+    return tuple(commands)
+
+
+def _conversation_activity_line(details: Mapping[str, Any]) -> str:
+    plan_items = ",".join(details["planItemIds"]) or "<none>"
+    result_path = str(details["resultPath"] or "<none>")
+    summary = json.dumps(details["summary"], ensure_ascii=False)
+    return (
+        f"ACTIVITY: id={details['activityId']} agent={details['agent']} "
+        f"summary={summary} items={plan_items} result={result_path} "
+        f"outcome={details['outcome']}"
+    )
+
+
+def _append(args: argparse.Namespace) -> int:
+    commands = _activity_commands(args)
+    details = {
+        "kind": args.kind,
+        "agent": args.agent,
+        "summary": args.summary,
+        "planItemIds": args.plan_item_id,
+        "resultPath": args.result_path,
+        "commands": [command.to_record() for command in commands],
+        "evidenceRefs": args.evidence_ref,
+        "outcome": args.outcome,
+    }
+    event = record_activity(args.project_root, args.run_manifest, details)
+    payload = dict(event.details)
+    payload["ok"] = True
+    payload["activityLine"] = _conversation_activity_line(payload)
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _project(args: argparse.Namespace) -> int:
+    rows = project_agent_activity(args.project_root, args.run_manifest, args.data)
+    print(json.dumps(
+        {"ok": True, "count": len(rows), "agentActivity": rows},
+        ensure_ascii=False,
+        indent=2,
+    ))
+    return 0
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="okstra agent-activity")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    append_parser = subparsers.add_parser("append")
+    append_parser.add_argument("--project-root", type=Path, required=True)
+    append_parser.add_argument("--run-manifest", type=Path, required=True)
+    append_parser.add_argument(
+        "--kind", choices=sorted(ACTIVITY_KINDS), required=True
+    )
+    append_parser.add_argument("--agent", required=True)
+    append_parser.add_argument("--summary", required=True)
+    append_parser.add_argument(
+        "--outcome", choices=sorted(ACTIVITY_OUTCOMES), required=True
+    )
+    append_parser.add_argument("--plan-item-id", action="append", default=[])
+    append_parser.add_argument("--evidence-ref", action="append", default=[])
+    append_parser.add_argument("--command-record", action="append", default=[])
+    append_parser.add_argument("--result-path", default="")
+    append_parser.add_argument("--audit-sidecar", type=Path)
+    project_parser = subparsers.add_parser("project")
+    project_parser.add_argument("--project-root", type=Path, required=True)
+    project_parser.add_argument("--run-manifest", type=Path, required=True)
+    project_parser.add_argument("--data", type=Path, required=True)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        return _append(args) if args.command == "append" else _project(args)
+    except ActivityProjectionError as exc:
+        print(f"okstra agent-activity: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/clarification_items.py

@@ -372,6 +372,13 @@ APPROVAL_BLOCKS = frozenset({"approval"})
 # user-response skill must list them — counting only `approval` made a report
 # whose open items were all `next-phase` look like it had none.
 USER_INPUT_BLOCKS = frozenset({"approval", "next-phase"})
+ANSWER_DISPOSITIONS = frozenset({
+    "answer",
+    "select",
+    "accept-risk",
+    "request-revision",
+    "reject",
+})
 
 
 @dataclass(frozen=True)
@@ -391,28 +398,39 @@ class ClarificationScan:
 def scan_approval_gate(report_path: Path) -> ClarificationScan:
     """Scan for unresolved ``Blocks=approval`` rows (``Status`` in
     ``{open, answered}``), refusing to guess whenever the schema drifted."""
-    return scan_clarification_blockers(report_path, APPROVAL_BLOCKS)
+    return scan_clarification_blockers(
+        report_path, APPROVAL_BLOCKS, honor_sidecar_answers=False
+    )
 
 
 def scan_open_user_input(report_path: Path) -> ClarificationScan:
     """Scan for every unresolved row that still owes the user an answer
     (``Blocks`` in ``{approval, next-phase}``)."""
-    return scan_clarification_blockers(report_path, USER_INPUT_BLOCKS)
+    return scan_clarification_blockers(
+        report_path, USER_INPUT_BLOCKS, honor_sidecar_answers=True
+    )
 
 
 def scan_clarification_blockers(
-    report_path: Path, blocking_values: frozenset[str]
+    report_path: Path,
+    blocking_values: frozenset[str],
+    *,
+    honor_sidecar_answers: bool,
 ) -> ClarificationScan:
     """Shared fail-closed clarification walk for both gates above — schema-v2
-    reads its rows from the data sibling, schema-v1 from the §1 table, and the
-    user's `user-responses/` sidecar outranks whatever the report says about
-    those rows."""
+    reads its rows from the data sibling and schema-v1 from the §1 table.
+    ``honor_sidecar_answers`` controls whether a user's sidecar hides answered
+    rows from this scan; approval deliberately passes ``False``."""
     v2_scan = _scan_v2_blockers(report_path, blocking_values)
     scan = (
         v2_scan if v2_scan is not None
         else scan_section_1_blockers(_read_report_text(report_path), blocking_values)
     )
-    return _resolve_blockers_answered_by_user(report_path, scan)
+    return (
+        _resolve_blockers_answered_by_user(report_path, scan)
+        if honor_sidecar_answers
+        else scan
+    )
 
 
 def _resolve_blockers_answered_by_user(
@@ -422,9 +440,8 @@ def _resolve_blockers_answered_by_user(
 
     답의 정본은 사용자의 `user-responses/` 사이드카다. 리포트의 `Status` 는 그
     run 이 스스로 적어둔 값이고, 답이 사이드카로만 들어오는 경로(HTML 뷰의
-    `Export user response`, `okstra user-response write`)에서는 갱신되지
-    않는다 — 게이트가 리포트만 보면 사용자가 답을 다 채운 뒤에도 같은 항목이
-    영원히 미해결로 남아 다음 phase 를 막는다.
+    `Export user response`, `okstra user-response write`)에서는 갱신되지 않는다.
+    사용자 입력 목록은 사이드카 답변이 있는 항목을 다시 묻지 않는다.
 
     fail-closed 는 그대로다: 행 자체를 못 읽은 스캔(`unreadable_reason`)은
     어떤 id 가 blocker 인지 모르는 상태이므로 사이드카로 덮지 않는다.
@@ -630,10 +647,10 @@ def sidecar_answers(source: Path) -> dict[str, str]:
     사용자가 답한 항목이 무엇인지 아는 단일 참조점 — carry-in 병합도, 승인
     게이트도, 스킬의 열린 항목 목록도 전부 이 한 곳을 본다.
 
-    `disposition` 이 `answer` 인 항목만 답으로 센다. `reframe` 은 "다음 run 에서
-    다시 물어달라" 이지 답이 아니므로(`skills/okstra-user-response/SKILL.md` 의
-    "A reframe is not an answer") 답 집합에서 빠져야 게이트가 그 항목을 계속
-    미해결로 잡는다.
+    `disposition` 이 `ANSWER_DISPOSITIONS` 에 속하는 항목만 답으로 센다.
+    `reframe` 은 "다음 run 에서 다시 물어달라" 이지 답이 아니므로
+    (`skills/okstra-user-response/SKILL.md` 의 "A reframe is not an answer")
+    답 집합에서 빠져야 사용자 입력 목록에 그 항목이 계속 남는다.
 
     같은 id 가 여러 사이드카에 나오면 이름순 마지막(최신 seq)이 이긴다 — 최신이
     reframe 이거나 값이 비면 앞선 답을 지운다. 그래야 답을 물렀을 때 그 항목이
@@ -646,7 +663,7 @@ def sidecar_answers(source: Path) -> dict[str, str]:
         for entry in parse_user_response_entries(
             sidecar.read_text(encoding="utf-8")
         ):
-            if entry.value and entry.disposition == "answer":
+            if entry.value and entry.disposition in ANSWER_DISPOSITIONS:
                 answers[entry.response_id] = entry.value
             else:
                 answers.pop(entry.response_id, None)
@@ -759,7 +776,7 @@ def _v2_section_1_body(entries: list) -> str:
     """schema-v2 `clarificationItems[]` 를 §1 표 본문으로.
 
     메타 셀은 렌더러가 쓰는 모양 그대로다 — `Status:` 는 따옴표 없이 써야
-    `_reconcile_user_input` 이 답을 병합하면서 상태를 resolved 로 넘길 수 있다."""
+    `_reconcile_user_input` 이 답을 병합하면서 상태를 answered 로 넘길 수 있다."""
     rows = [e for e in entries if isinstance(e, dict) and e.get("id")]
     if not rows:
         return f"\n{_SECTION_1_EMPTY_STATE}"
@@ -783,7 +800,7 @@ def _v2_section_1_body(entries: list) -> str:
 # The final-report renderer writes `Status: open` / `Status: answered` unquoted
 # in the stacked meta cell; only those two are unresolved. Resolve in place so
 # the meta cell's other fields (ID, Ticket, Kind, Blocks) are left untouched.
-_STATUS_RESOLVE_RE = re.compile(r"(Status:\s*)(?:open|answered)\b", re.IGNORECASE)
+_STATUS_ANSWER_RE = re.compile(r"(Status:\s*)(?:open|answered)\b", re.IGNORECASE)
 
 
 def _locate_user_input_column(lines: list[str]) -> tuple[int, int]:
@@ -799,7 +816,7 @@ def _locate_user_input_column(lines: list[str]) -> tuple[int, int]:
 
 def _reconcile_row(line: str, ui_col: int, answers: dict[str, str]) -> str:
     """답이 있고 open/answered 인 행이면 `User input` 칸을 그 답으로 채우고 Status 를
-    resolved 로 바꾼 줄을, 그 외에는 원본 줄을 그대로 돌려준다.
+    answered 로 바꾼 줄을, 그 외에는 원본 줄을 그대로 돌려준다.
 
     칸에 이미 값이 있어도 사용자의 사이드카 답이 이긴다. 그 칸을 채우는 것은
     run 자신(직전 렌더가 옮겨 적은 값)이고, 사용자가 나중에 답을 바꾸면 둘이
@@ -819,13 +836,13 @@ def _reconcile_row(line: str, ui_col: int, answers: dict[str, str]) -> str:
     if not 0 <= ui_col < len(raw):
         return line
     raw[ui_col] = answers[item.row_id]
-    raw[0] = _STATUS_RESOLVE_RE.sub(r"\1resolved", raw[0])
+    raw[0] = _STATUS_ANSWER_RE.sub(r"\1answered", raw[0])
     return "| " + " | ".join(to_cell_text(c) for c in raw) + " |"
 
 
 def _reconcile_user_input(section: str, answers: dict[str, str]) -> str:
     """§1 표에서 사이드카 답이 있는 미해결 행의 `User input` 칸을 답으로 채우고
-    Status 를 resolved 로 바꾼 §1 본문을 돌려준다.
+    Status 를 answered 로 바꾼 §1 본문을 돌려준다.
 
     답의 정본 위치를 §1 표 안으로 옮긴다 — 표만 읽는 승인 게이트·프롬프트
     빌더·검증 워커가 모두 답을 보게 하려는 것. 사이드카는 §1 표 밖 별도 섹션에만