okstra 0.71.2 → 0.73.0

package/runtime/python/okstra_token_usage/cursor.py

@@ -18,7 +18,9 @@ from pathlib import Path
 
 from okstra_project.dirs import okstra_home
 
-CACHE_SCHEMA_VERSION = 1
+# v2: usage 이벤트에 `p`(lead PROGRESS 마커) 키 추가 — v1 캐시는 이미 스캔한
+# 구간의 마커가 없으므로 폐기하고 전체 재스캔한다(fail-open).
+CACHE_SCHEMA_VERSION = 2
 IDENTITY_PREFIX_BYTES = 256
 MAX_NEEDLES = 16
 

package/runtime/schemas/final-report-v1.0.schema.json

@@ -625,6 +625,31 @@
       }
     },
 
+    "fixCycle": {
+      "type": "object",
+      "description": "RENDER_IF fixCycle present — the post-release bug-fix cycle this run belongs to.",
+      "required": ["cycle", "targetReport", "symptom"],
+      "additionalProperties": false,
+      "properties": {
+        "cycle": { "type": "string", "pattern": "^fc-[0-9]{2,}$" },
+        "targetReport": { "type": "string" },
+        "symptom": { "type": "string" },
+        "runs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["taskType", "runSeq"],
+            "additionalProperties": false,
+            "properties": {
+              "taskType": { "type": "string" },
+              "runSeq": { "type": "integer" },
+              "runManifest": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+
     "clarificationItems": {
       "type": "array",
       "items": { "$ref": "#/$defs/ClarificationRow" }
@@ -1217,9 +1242,10 @@
 
     "ValidationCheckRow": {
       "type": "object",
-      "required": ["phase", "ticketId", "check", "commandOrObservation", "expectedOutcome"],
+      "required": ["id", "phase", "ticketId", "check", "commandOrObservation", "expectedOutcome"],
       "additionalProperties": false,
       "properties": {
+        "id": { "type": "string", "pattern": "^VC-\\d{3,}$" },
         "phase": { "enum": ["pre", "mid", "post"] },
         "ticketId": { "$ref": "#/$defs/TicketId" },
         "check": { "type": "string", "minLength": 1 },

package/runtime/skills/okstra-brief/SKILL.md

@@ -431,6 +431,9 @@ never error:
 1. **okstra-internal (authoritative)** — always check first:
    - `<PROJECT_ROOT>/.okstra/glossary.md` if present
    - `<PROJECT_ROOT>/.okstra/decisions/` titles if present
+   - Fix history (when the brief targets an existing task):
+     `<PROJECT_ROOT>/.okstra/tasks/<task-group>/<task-id>/history/fix-cycles.jsonl`
+     — read every `opened`/`closed` row.
 2. **Explicit source material only** — if the reporter cited a path outside
    okstra's subtree, read it as source evidence only; do not treat it as
    okstra memory.
@@ -602,6 +605,11 @@ Required sections:
 - **Related Artifacts** — files, URLs, issues, prior task-keys.
 - **Open Questions** — anything the user already flagged as undecided
   (becomes raw material for `requirements-discovery`).
+- **Task Continuity Notes** — if the target task's
+  `history/fix-cycles.jsonl` exists, cite each cycle here as one line —
+  `fix-cycle fc-NN (open|closed): <symptom> (target: <target_report>)`.
+  An open cycle means the new brief continues a bug-fix in progress; say
+  so explicitly.
 
 Sections **deliberately omitted** (do NOT add them, do NOT prompt for them):
 

package/runtime/skills/okstra-convergence/SKILL.md

@@ -519,14 +519,18 @@ Schema rules:
 Runs only when `convergence.critic.enabled == true` (set by `--critic <provider>` or the okstra-run `critic_pick` step; default off). Applies to the three finding-producing phases (`requirements-discovery`, `error-analysis`, `implementation-planning`); for `final-verification` the critic runs in a different mode — see §"Acceptance critic pass (final-verification)". This pass targets **coverage** (missed findings), distinct from convergence which targets **agreement quality**.
 
 ### When
-After Phase 5.5 finding convergence completes (findings classified) and BEFORE the Phase 6 report-writer dispatch.
+
+The critic input is the Round 0 consolidated finding list. Reverify rounds only classify findings — they never add or remove them (in-round queue insertions are forbidden, see §"Convergence State Artifact" `carriedForwardCount`) — so the critic dispatch MUST NOT wait for classification to finish:
+
+- **Dispatch**: immediately after Round 0 grouping, CONCURRENTLY with the first reverify round's dispatches. When the verification queue is empty after Round 0 (no reverify round runs), dispatch right after grouping. Concurrent dispatch to the same provider is safe — the critic result path (`<provider>-critic-...`) never collides with a reverify result path.
+- **Gap verification + merge**: only after BOTH the finding-convergence loop has exited AND the critic result is collected, and BEFORE the Phase 6 report-writer dispatch. If the loop exited `aborted-non-result`, do NOT dispatch a gap-verification round — surface the gaps as unverified `clarification` items per §"Gap verification" and record that fact.
 
 ### Dispatch (reused worker)
 Dispatch ONE pass to the `config.critic.provider`'s existing subagent (`claude-worker` / `codex-worker` / `gemini-worker`) with `model = config.critic.modelExecutionValue` — no new agent type. If `config.critic.modelExecutionValue` is null/empty (model could not be resolved), skip the critic pass and record `critic-skipped: model-unresolved` in the convergence state rather than dispatching with no model. Result path: `runs/<task-type>/worker-results/<provider>-critic-<task-type>-<seq>.md`. The critic prompt seeds the consolidated findings and asks ONLY for coverage gaps:
 
 ```
-You are the coverage critic for <task-key>. Below are the findings the workers
-already agreed on. Your ONLY job is to name what is MISSING:
+You are the coverage critic for <task-key>. Below are the consolidated findings
+the workers produced. Your ONLY job is to name what is MISSING:
 - files / directories / execution paths nobody inspected,
 - requirements or acceptance points with zero findings,
 - claims raised but never verified.
@@ -543,7 +547,7 @@ Each critic gap enters the verification queue as a finding with `originWorker =
 
 ## Acceptance critic pass (final-verification)
 
-The `final-verification` phase reuses the SAME reused-worker dispatch as §"Coverage critic pass" (provider + `config.critic.modelExecutionValue` from the `convergence.critic` block; default off; same model-unresolved skip rule). Only the prompt, the verification semantics, and the output sink differ — final-verification's findings are defects/blockers, so the critic acts as an **acceptance devil's advocate** (find reasons NOT to accept), and its candidate blockers are NEVER dropped (that would suppress real defects).
+The `final-verification` phase reuses the SAME reused-worker dispatch AND the same dispatch timing as §"Coverage critic pass" §"When" (provider + `config.critic.modelExecutionValue` from the `convergence.critic` block; default off; same model-unresolved skip rule) — the delivered work the critic inspects is likewise fixed before the reverify round starts. Only the prompt, the verification semantics, and the output sink differ — final-verification's findings are defects/blockers, so the critic acts as an **acceptance devil's advocate** (find reasons NOT to accept), and its candidate blockers are NEVER dropped (that would suppress real defects).
 
 ### Prompt
 

package/runtime/skills/okstra-inspect/SKILL.md

@@ -425,6 +425,15 @@ Display rule for `workerId` vs `agent`:
 
 Never write `claude (claude)` — the parenthesized agent is shown only when it adds information.
 
+**C. Per-run phase breakdown (when `phaseTimeline` is present):**
+
+team-state written by collector ≥ v0.73 carries a `phaseTimeline` block — the Phase 7 collector reconstructs lead operating-phase boundaries from the lead session's `PROGRESS: phase-*` checkpoint lines (`{source: "lead-progress-markers", phases: [{phase, firstAt, lastAt, markerCount, wallMsToNext}]}`).
+
+- When the user asks for a per-phase / per-run breakdown ("단계별", "phase별", "어느 단계가 오래"), render one table per requested run: `| Phase | Start | Wall to next |` using `firstAt` and `wallMsToNext`.
+- `wallMsToNext` is `null` on the last phase (the run-end signal is not a marker) — render `--`.
+- `phases: []` means the lead emitted no markers (run predates the contract, or markers were skipped) — say "phase timeline 측정 불가(마커 없음)" rather than estimating from other fields.
+- Older team-state files have no `phaseTimeline` key at all — omit the section silently.
+
 **Timestamp parsing:** for `startedAt` / `endedAt`, normalize ISO-8601: replace trailing `Z` with `+00:00`, accept explicit offsets as-is, parse via `datetime.fromisoformat(s.replace("Z", "+00:00"))`. Strings without an offset are assumed UTC. Mixed-form comparisons must be done as `datetime` objects, never raw strings.
 
 ### time.4 — Format output
@@ -458,6 +467,17 @@ Never write `claude (claude)` — the parenthesized agent is shown only when it
 | report-writer  | 2    | 00:01:00 | 00:00:30 |
 
 > Unavailable: 1 run (implementation / 2026-04-30_03-03-48) — team-state has no durationMs (Phase 7 not reached)
+
+### Phase breakdown — requirements-discovery (run 002)
+
+| Phase                  | Start (UTC)      | Wall to next |
+|------------------------|------------------|--------------|
+| phase-1-intake         | 2026-06-11 09:00 | 00:04:00     |
+| phase-2-prompts        | 2026-06-11 09:04 | 00:02:10     |
+| phase-4-dispatch       | 2026-06-11 09:06 | 00:18:30     |
+| phase-5.5-convergence  | 2026-06-11 09:25 | 00:21:00     |
+| phase-6-synthesis      | 2026-06-11 09:46 | 00:15:00     |
+| phase-7-persist        | 2026-06-11 10:01 | --           |
 ```
 
 **Rules:**

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -105,7 +105,7 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    ```
 
    Output (idempotent — re-running overwrites):
-   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view, **generated only when the report has at least one §5 `C-*` clarification row**. Those rows with `Status` ∈ {`open`, `answered`} embed form widgets (`<select>` for enum-style decisions, `<input>` for material / data-point kinds, `<textarea>` fallback); an `Export user response` button serialises form values to a markdown sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) that the user pastes to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`. The original final-report MD is **never** mutated by user input — the sidecar is the single write target.
+   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view, **generated only when the report has at least one §5 `C-*` clarification row**. Those rows with `Status` ∈ {`open`, `answered`} embed form widgets (`<select>` for enum-style decisions, `<input>` for material / data-point kinds, `<textarea>` fallback); an `Export user response` button serialises form values to a markdown sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) and downloads it as `user-response-<task-type>-<seq>.md`; the user saves it to `runs/<task-type>/user-responses/`, and `--resume-clarification` auto-appends every sidecar found there to the next run's `clarification-response.md` (`clarification_items.clarification_response_with_sidecars`). The original final-report MD is **never** mutated by user input — the sidecar is the single write target.
    - When the report has **no** `C-*` clarification rows, the html carries no interactive forms (it would only duplicate the MD), so the renderer prints `html: skipped (...)` and writes nothing. This is the expected state for clarification-free runs — `validators/validate-report-views.py` treats "no C-* rows + no html" as a pass, not a missing artifact.
 
    Must run AFTER step 1 (so token placeholders are substituted in any rendered html) and BEFORE step 2 (so the html artifact, when generated, exists for the validator step that checks it).
@@ -276,9 +276,11 @@ Section numbering follows `templates/reports/final-report.template.md` exactly
 3. **Evidence and Detailed Analysis** — primary evidence rows (file path, line, snippet); secondary evidence / alternate interpretations. If `reference-expectations.md` lists explicit expected values, record match/gap per row.
 4. **Missing Information and Risks** — uncertain / "I don't know" items. `implementation-planning` adds §5.5 (see heading contract below); `release-handoff` adds §5.6.
 5. **Clarification Items** — single unified `C-*` table; column schema (4 columns with the short fields stacked in one record-meta cell), ID convention, and rerun behaviour are owned by `_common-contract.md §Clarification request policy` (SSOT). The deprecated `5.5.9 Open Questions` / `1.1 추가 자료 요청` / `1.2 사용자 확인 질문` sub-sections are removed; the validator fails reports that reintroduce them.
-6. **Recommended Next Steps** — prioritized actions. After Phase 7's follow-up spawner runs, append a row per newly created task-key (see "Phase 6 → Phase 7 execution sequence" above).
+6. **Recommended Next Steps** — prioritized actions. After Phase 7's follow-up spawner runs, append a row per newly created task-key (see "Phase 6 → Phase 7 execution sequence" above). **Approval-gate consistency:** when §1 carries any `Blocks: approval` row with `Status` ∈ {open, answered}, the Verdict Card `Next Step` and the first recommended step MUST point to the clarification rerun (`resume-clarification` of the SAME task-type) — never to "frontmatter `approved: true` 플립 → `implementation` 직행". Run-prep enforces this gate (`run.py _validate_approved_plan` fail-closes on those rows and on a blocking data.json `gateResult`), so a direct-implementation next-step is an instruction the reader cannot actually follow.
 7. **Follow-up Tasks** — auto-spawn-eligible table. Each row drives `okstra-spawn-followups.py`; see template §7 for the row schema.
 
+**§5.10 Fix History (data-presence gated).** When the run-manifest carries a `fixCycleId`, fill the data.json `fixCycle` block (`cycle` / `targetReport` / `symptom` / `runs`). Read the values from the task root's `history/fix-cycles.jsonl`: `cycle` MUST equal `fixCycleId`, `targetReport` / `symptom` come from that cycle's `opened` row, and `runs` lists its attached `run` rows (`taskType` / `runSeq` / `runManifest`). The validator (`validators/validate-run.py` → `_validate_fix_cycle`) fails the run when the block is missing or `fixCycle.cycle` does not match `fixCycleId`. When the run-manifest has no `fixCycleId`, OMIT the `fixCycle` block entirely — the renderer omits §5.10.
+
 ### Writing Guidelines
 
 - Write in Markdown. **Prefer tables over prose bullet lists** for any section that enumerates multiple items with the same shape (evidence rows, risks, options, dependencies, rollback steps, follow-ups, open questions). Bullets are reserved for short, single-line standalone statements (e.g., "- 추가 정보 요청 없음."). When the template provides a table form, do NOT degrade it back to bullets in the rendered report.

package/runtime/skills/okstra-run/SKILL.md

@@ -178,7 +178,8 @@ okstra render-bundle \
   --report-writer-model "<args.report-writer-model>" \
   --related-tasks "<args.related-tasks>" \
   --clarification-response "<args.clarification-response>" \
-  --pr-template-path "<args.pr-template-path>"
+  --pr-template-path "<args.pr-template-path>" \
+  --fix-cycle "<args.fix-cycle>"
 ```
 
 `render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, and the full rendered lead prompt. Parse the labelled lines for `TASK_ROOT` and `INSTRUCTION_SET_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "동시-run 감지 분기" below).

package/runtime/templates/project-docs/task-index.template.md

@@ -37,6 +37,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - Next Recommended Phase: `{{WORKFLOW_NEXT_RECOMMENDED_PHASE}}`
 - Awaiting Approval: `{{WORKFLOW_AWAITING_APPROVAL}}`
 - Routing Status: `{{WORKFLOW_ROUTING_STATUS}}`
+- Fix cycles: {{FIX_CYCLES_SUMMARY}}
 
 ## Phase States
 

package/runtime/templates/reports/final-report.template.md

@@ -202,10 +202,10 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 
 ### Validation Checklist{% if t("sectionAside.validationChecklist") != "Validation Checklist" %} ({{ t("sectionAside.validationChecklist") }}){% endif %}
 
-| Phase | Ticket ID | Check | Command / Observation | Expected outcome |
-|-------|-----------|-------|------------------------|-------------------|
+| ID | Phase | Ticket ID | Check | Command / Observation | Expected outcome |
+|----|-------|-----------|-------|------------------------|-------------------|
 {% for row in implementationPlanning.validationChecklist -%}
-| {{ row.phase }} | `{{ row.ticketId }}` | {{ row.check }} | `{{ row.commandOrObservation }}` | {{ row.expectedOutcome }} |
+| {{ row.id }} | {{ row.phase }} | `{{ row.ticketId }}` | {{ row.check }} | `{{ row.commandOrObservation }}` | {{ row.expectedOutcome }} |
 {% endfor %}
 
 ### Rollback Strategy{% if t("sectionAside.rollbackStrategy") != "Rollback Strategy" %} ({{ t("sectionAside.rollbackStrategy") }}){% endif %}
@@ -556,6 +556,20 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | Cand ID | Lens | Title | Scope | Severity | Effort | Consensus | Source workers | Recommended next-phase | Evidence |
 |---------|------|-------|-------|----------|--------|-----------|----------------|------------------------|----------|
 
+{% endif %}
+{% if fixCycle and fixCycle.cycle %}
+## 5.10 Fix History
+
+> This run belongs to a post-release bug-fix cycle registered in `history/fix-cycles.jsonl`.
+
+- Cycle: `{{ fixCycle.cycle }}` — {{ fixCycle.symptom }}
+- Target report: `{{ fixCycle.targetReport }}`
+{% if fixCycle.runs %}
+- Runs in this cycle so far:
+{% for r in fixCycle.runs %}
+  - {{ r.taskType }} seq {{ r.runSeq }}{% if r.runManifest %} (`{{ r.runManifest }}`){% endif %}
+{% endfor %}
+{% endif %}
 {% endif %}
 ## 6. Cross Verification Results
 

package/runtime/templates/reports/report.js

@@ -9,8 +9,11 @@
  *      (everything else / fallback).
  *   2. Serialise the entries into markdown whose bytes are IDENTICAL
  *      to scripts/okstra_ctl/report_views.py serialize_user_response.
- *   3. Write the result to <pre id="user-response-output"> and offer a
- *      [Copy] button.
+ *   3. Write the result to <pre id="user-response-output">, offer a
+ *      [Copy] button, and download it as
+ *      user-response-<task-type>-<seq>.md — the user drops that file in
+ *      runs/<task-type>/user-responses/ and --resume-clarification
+ *      auto-appends it to the next run's clarification-response.md.
  *
  * The byte-identity contract is enforced by tests/test_report_views.py
  * which spawns Node to execute buildUserResponseMarkdown and diffs the
@@ -143,12 +146,30 @@
     return head + chunks;
   }
 
+  function downloadUserResponse(md, runMeta) {
+    var name =
+      "user-response-" + (runMeta["task-type"] || "report") + "-" +
+      (runMeta["seq"] || "000") + ".md";
+    var blob = new Blob([md], { type: "text/markdown" });
+    var url = URL.createObjectURL(blob);
+    var a = document.createElement("a");
+    a.href = url;
+    a.download = name;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    setTimeout(function () { URL.revokeObjectURL(url); }, 0);
+  }
+
   function exportUserResponse() {
     var runMeta = readRunMeta();
     var entries = collectEntries();
     var md = buildUserResponseMarkdown(runMeta, entries, isoNowUtc());
     var out = document.getElementById("user-response-output");
     if (out) out.textContent = md;
+    // Nothing answered yet — show the empty serialisation as feedback but
+    // don't download a useless file.
+    if (entries.length > 0) downloadUserResponse(md, runMeta);
     return md;
   }
 

package/runtime/validators/validate-run.py

@@ -1369,6 +1369,19 @@ def _data_path_for(report_path: Path) -> Path:
     return report_path.with_suffix(".data.json")
 
 
+def _load_final_report_data(report_path: Path) -> dict:
+    """Best-effort parse of the final-report data.json sibling. Returns {} when
+    absent or unparseable — those conditions are already surfaced as failures by
+    validate_final_report_data; this loader only feeds cross-field checks."""
+    data_path = _data_path_for(report_path)
+    if not data_path.is_file():
+        return {}
+    try:
+        return json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
 def validate_final_report_data(report_path: Path, failures: list[str]) -> None:
     """Validate the final-report data.json against the v1.0 schema.
 
@@ -1748,6 +1761,31 @@ def _validate_improvement_discovery(
             failures.append(f"improvement-discovery: {err}")
 
 
+def _validate_fix_cycle(run_manifest: dict, data: dict, failures: list[str]) -> None:
+    """Enforce: when the run-manifest carries a fixCycleId, the final-report
+    data.json MUST contain a fixCycle block whose ``cycle`` matches it.
+
+    Direction is one-way: a fixCycle block present without a run-manifest
+    fixCycleId is NOT rejected — same posture as the schema-optional block.
+    This check owns only the run→report direction (no missing/mismatched
+    block when the run is attached), never the reverse."""
+    cycle_id = (run_manifest or {}).get("fixCycleId", "")
+    if not cycle_id:
+        return
+    block = (data or {}).get("fixCycle")
+    if not isinstance(block, dict):
+        failures.append(
+            f"fix-cycle: run-manifest fixCycleId={cycle_id} but data.json has "
+            "no fixCycle block"
+        )
+        return
+    if block.get("cycle") != cycle_id:
+        failures.append(
+            f"fix-cycle: data.json fixCycle.cycle={block.get('cycle')!r} does "
+            f"not match run-manifest fixCycleId={cycle_id!r}"
+        )
+
+
 def _validate_session_conformance(
     team_state: dict,
     team_state_path: Path,
@@ -2157,6 +2195,9 @@ def main() -> int:
     # safety net for hand-edited or pre-v1.0 reports.
     task_type = effective_run_task_type(run_manifest, task_manifest)
     validate_final_report_data(report_path, failures)
+    _validate_fix_cycle(
+        run_manifest, _load_final_report_data(report_path), failures
+    )
     validate_report(report_path, contract["required_agent_status_entries"], failures)
     validate_team_state_usage(team_state, failures)
 

package/src/render-bundle.mjs

@@ -18,11 +18,14 @@ Usage:
     [--gemini-model <m>] [--report-writer-model <m>] \\
     [--related-tasks <list>] [--base-ref <ref>] \\
     [--clarification-response <path>] [--work-category <cat>] \\
-    [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>]
+    [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>] \\
+    [--fix-cycle <yes|no>]
 
   --stage             implementation / final-verification only
   --stages            release-handoff only: PR stage bundle csv (empty = whole-task)
   --pr-template-path  release-handoff only
+  --fix-cycle         entry phase only: record this re-entry of a done task as a
+                      bug-fix cycle (yes opens/continues the cycle)
 
 release-handoff takes NO --task-brief (briefs belong to entry phases) —
 prepare generates the run's input document from the cited verification