okstra 0.143.0 → 0.145.0

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

@@ -115,7 +115,8 @@ That is the entire interactive flow. The wizard handles:
 
 - new-vs-existing task split (remaining work — `workStatus != done` — top-3 newest recommendations + Enter directly), task-group / task-id slug validation (task-group offers the top-3 newest candidates combining recent task use + recent `.okstra/briefs/<group>/` creation activity + Enter directly; task-id offers the top-3 recent candidates from the same group + Enter directly),
 - task-type pick (3 recommendations — `nextRecommendedPhase` recommended / re-run the current phase / the lifecycle's next step — + Enter directly; Enter directly is validated against the full task-type whitelist in a follow-up `text` step),
-- brief path — **asked only for entry task-types (requirements-discovery / error-analysis / improvement-discovery)** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, sorted by the newer of file-created/modified time and latest task-catalog use; direct input last; `Keep / Change` for existing entry tasks). A downstream task-type auto carries in the manifest's brief, and when no registered brief exists a `brief_carry` 3-option prompt appears (recommend switching to entry / Enter directly / Abort). `release-handoff` has no brief step at all — prepare generates the input document that cites the verification report,
+- brief path — **asked only for entry task-types (requirements-discovery / error-analysis / improvement-discovery / project-analysis / feature-analysis / change-impact-analysis)** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, sorted by the newer of file-created/modified time and latest task-catalog use; direct input last; `Keep / Change` for existing entry tasks). `project-analysis`, `feature-analysis`, and `change-impact-analysis` are brief entry task types. A downstream lifecycle task-type auto carries in the manifest's brief, and when no registered brief exists a `brief_carry` 3-option prompt appears (recommend switching to entry / Enter directly / Abort). `release-handoff` has no brief step at all — prepare generates the input document that cites the verification report,
+- analysis-input sub-flow — `project-analysis` has no target or evidence step. `feature-analysis` runs `project_evidence_pick` / `project_evidence`, then `analysis_target_pick` / `analysis_target`; the target is required even when the user skips project evidence. `change-impact-analysis` runs `feature_evidence_pick` / `feature_evidence`, then `project_evidence_pick` / `project_evidence`. The evidence steps show accepted compatible reports first and retain direct-path entry; do not invent a different relation or reorder these steps,
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
 - `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = the earliest incomplete stage whose dependencies are satisfied, or a specific stage number) + executor pick. When an approved plan is selected and a `## APPROVAL` sidecar exported from the report — matching the plan on source-report·seq — is detected in that run's sibling `user-responses/`, the approve-confirm step expands to 3 options (`yes_apply` recommended: approve + apply the option as exported / `yes` approve only / `no` abort) — `yes_apply` validates the option against the plan's `optionCandidates` before applying it via the existing approval·option path,
 - `release-handoff`-only sub-flow: after the approved plan auto-resolves, a `handoff_stage_pick` multi-select — choose an eligible stage bundle (stage-group) or the whole task (when an accepted whole-task verification report exists); the result goes out as render-args' `stages` key (csv, empty when whole-task),
@@ -124,6 +125,15 @@ That is the entire interactive flow. The wizard handles:
 - `release-handoff` PR template override + persist scope,
 - final `Proceed / Edit` confirmation; on `Edit` the wizard asks which step to rewind to and clears every later answer.
 
+### Analysis sidetrack execution rules
+
+When the selected task type is `project-analysis`, `feature-analysis`, or `change-impact-analysis`:
+
+1. Treat the target project as strictly read-only. No edits, tests, builds, migrations, or deployments are allowed, even if the user asks for verification while starting the analysis run.
+2. Pass the wizard's resolved target and evidence values through the render flags exactly as emitted. `project-analysis` emits both values empty; never synthesize an evidence path from a brief or a prior run.
+3. A `revision-requested` report is not evidence. The wizard prioritizes its same-task, same-type full rerun and carries the review sidecar through the existing clarification-response channel; preserve that choice instead of substituting a newer report of another type.
+4. The rendered lead contract reanalyzes the whole confirmed scope and records a resolution for every affected ID. Do not narrow the rerun to only the disputed rows or mutate the previous report.
+
 Do not second-guess the wizard. If the next prompt seems out of place, the bug is in `wizard.py`, not in your interpretation of the user's input.
 
 ## Step 4: Show the confirmation block before the final Proceed
@@ -178,6 +188,8 @@ okstra render-bundle \
   --task-id      "<args.task-id>" \
   --task-type    "<args.task-type>" \
   --task-brief   "<args.task-brief>" \
+  --analysis-target "<args.analysis-target>" \
+  --evidence-inputs "<args.evidence-inputs>" \
   --executor     "<args.executor>" \
   --critic       "<args.critic>" \
   --approved-plan "<args.approved-plan>" \

package/runtime/templates/reports/change-impact-analysis-input.template.md

@@ -0,0 +1,58 @@
+---
+title: OKSTRA Change Impact Analysis Input - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: ready-for-agent
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
+---
+
+# OKSTRA Change Impact Analysis Input
+
+## Identity
+
+- Project ID:
+- Task Group:
+- Task ID:
+- Related Tasks:
+- Issue / Ticket:
+- Task Type: `change-impact-analysis`
+- Requested Outcome:
+
+## Proposed Change and User Intent
+
+- Change being assessed (without prescribing an implementation):
+- User intent and decision this analysis should support:
+- Explicitly excluded changes or systems:
+
+## Impact Scope
+
+- Directly affected components, interfaces, or integrations:
+- Potential dependency propagation:
+- Expected test and operational impact:
+
+## Preserved Behavior and Constraints
+
+- Behavior, contracts, or outcomes that must be preserved:
+- Compatibility, security, or operational constraints:
+- Open decisions that a later planning phase must resolve:
+
+## Questions for Analysers
+
+1. Which behaviors must be preserved and which items are affected?
+2. How could impacts propagate through dependencies, tests, and operations?
+3. Which constraints and open decisions should be passed to implementation-planning without producing an execution plan?
+
+## Input Limit
+
+- Collect user intent, impact scope, and preserved behavior only.
+- Do not add worker-produced result tables to this input.
+- The final report `data.json` is the result source of truth.
+
+## Conversion Note
+
+- This input can be used as a starting draft before creating `okstra-task-brief.md`.

package/runtime/templates/reports/feature-analysis-input.template.md

@@ -0,0 +1,59 @@
+---
+title: OKSTRA Feature Analysis Input - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: ready-for-agent
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
+---
+
+# OKSTRA Feature Analysis Input
+
+## Identity
+
+- Project ID:
+- Task Group:
+- Task ID:
+- Related Tasks:
+- Issue / Ticket:
+- Task Type: `feature-analysis`
+- Requested Outcome:
+
+## User Intent and Confirmed Target
+
+- Confirmed feature, journey, or capability to analyse:
+- User intent and expected value:
+- Explicitly excluded feature areas:
+
+## Behavior Scope
+
+- Normal flow to preserve or understand:
+- Alternate flows:
+- Failure flows:
+- Rules, state changes, or external calls that need attention:
+
+## Preserved Behavior
+
+- Contracts or outcomes that must remain unchanged:
+- Compatibility, security, or operational constraints:
+- Unknown behavior that requires clarification:
+
+## Questions for Analysers
+
+1. What normal, alternate, and failure flows define the confirmed target?
+2. Which rules, state transitions, and external calls are in scope?
+3. What test coverage scope should a later task consider without proposing implementation changes?
+
+## Input Limit
+
+- Collect user intent, behavior scope, and preserved behavior only.
+- Do not add worker-produced result tables to this input.
+- The final report `data.json` is the result source of truth.
+
+## Conversion Note
+
+- This input can be used as a starting draft before creating `okstra-task-brief.md`.

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

@@ -837,6 +837,226 @@ Single scan of every agreed check that this run did NOT confirm — requirement
 - All agreed checks were executed or covered — nothing left unverified.
 {%- endif %}
 
+{% endif %}
+{% if analysisCommon %}
+## 5.9 Analysis Basis
+
+{{ t("analysis.basisIntro") }}
+
+### 5.9.1 Snapshot and Scope
+
+| Item | Value |
+|------|-------|
+| Run sequence | `{{ analysisCommon.runSeq | mdcell }}` |
+| Source commit | `{{ analysisCommon.sourceCommit | mdcell }}` |
+| Included paths | {{ analysisCommon.scope.includedPaths | join(', ') | mdcell }} |
+| Excluded paths | {{ analysisCommon.scope.excludedPaths | join(', ') | mdcell }} |
+| Unscanned paths | {{ (analysisCommon.scope.unscannedPaths | join(', ') or '--') | mdcell }} |
+| Resolved target mode | `{{ (analysisCommon.scope.resolvedTarget.inputMode or '--') | mdcell }}` |
+| Resolved target | {{ (analysisCommon.scope.resolvedTarget.requestedValue or '--') | mdcell }} |
+
+### 5.9.2 Evidence Inputs
+
+{% if analysisCommon.evidenceInputs | length == 0 -%}
+{{ t("analysis.empty") }}
+{%- else %}
+| Task key | Task type | Report path | Run | Source commit | Relation | Freshness | Review status |
+|----------|-----------|-------------|-----|---------------|----------|-----------|---------------|
+{% for row in analysisCommon.evidenceInputs -%}
+| {{ row.taskKey | mdcell }} | `{{ row.taskType | mdcell }}` | `{{ row.reportPath | mdcell }}` | `{{ row.runSeq | mdcell }}` | `{{ row.sourceCommit | mdcell }}` | `{{ row.relation | mdcell }}` | `{{ row.freshness | mdcell }}` | `{{ row.reviewStatus | mdcell }}` |
+{% endfor %}
+{%- endif %}
+
+### 5.9.3 Confirmed Facts
+
+{% if analysisCommon.confirmedFacts | length == 0 -%}
+{{ t("analysis.empty") }}
+{%- else %}
+| ID | Claim | Current code evidence | Confidence | Review resolution |
+|----|-------|-----------------------|------------|-------------------|
+{% for row in analysisCommon.confirmedFacts -%}
+{% set review = namespace(value=t("analysis.reviewNotRecorded")) -%}
+{% for resolution in analysisCommon.analysisReviewResolution if resolution.affectedId == row.id -%}
+{% set review.value = resolution.outcome ~ ': ' ~ resolution.resolution -%}
+{% endfor -%}
+| {{ row.id | mdcell }} | {{ row.statement | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} | confirmed | {{ review.value | mdcell }} |
+{% endfor %}
+{%- endif %}
+
+### 5.9.4 Inferences and Unknowns
+
+{% if analysisCommon.inferences | length == 0 -%}
+{{ t("analysis.empty") }}
+{%- else %}
+| ID | Claim | Evidence IDs | Confidence |
+|----|-------|--------------|------------|
+{% for row in analysisCommon.inferences -%}
+| {{ row.id | mdcell }} | {{ row.statement | mdcell }} | {{ row.evidenceIds | join(', ') | mdcell }} | `{{ row.confidence | mdcell }}` |
+{% endfor %}
+{%- endif %}
+
+{% if analysisCommon.unknowns | length > 0 %}
+| ID | Question | Reason | Affects verdict |
+|----|----------|--------|-----------------|
+{% for row in analysisCommon.unknowns -%}
+| {{ row.id | mdcell }} | {{ row.question | mdcell }} | {{ row.reason | mdcell }} | `{{ row.affectsVerdict | mdcell }}` |
+{% endfor %}
+{% endif %}
+
+### 5.9.5 Analysis Review Resolution
+
+{% if analysisCommon.analysisReviewResolution | length == 0 -%}
+{{ t("analysis.empty") }}
+{%- else %}
+| Affected ID | Outcome | Resolution | Evidence |
+|-------------|---------|------------|----------|
+{% for row in analysisCommon.analysisReviewResolution -%}
+| {{ row.affectedId | mdcell }} | `{{ row.outcome | mdcell }}` | {{ row.resolution | mdcell }} | {{ row.evidence | join('<br>') | mdcell }} |
+{% endfor %}
+{%- endif %}
+
+{% endif %}
+{% if projectAnalysis %}
+## 5.10 Project Analysis
+
+{{ t("analysis.projectIntro") }}
+
+### 5.10.1 Components
+
+| ID | Name | Responsibility | Paths | Current code evidence |
+|----|------|----------------|-------|-----------------------|
+{% for row in projectAnalysis.components -%}
+| {{ row.id | mdcell }} | {{ row.name | mdcell }} | {{ row.responsibility | mdcell }} | {{ row.paths | join(', ') | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} |
+{% endfor %}
+
+### 5.10.2 Dependencies and Boundaries
+
+| From | To | Direction | Current code evidence |
+|------|----|-----------|-----------------------|
+{% for row in projectAnalysis.dependencies -%}
+| {{ row.fromComponentId | mdcell }} | {{ row.toComponentId | mdcell }} | {{ row.direction | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} |
+{% endfor %}
+
+| Kind | Path | Symbol | Role | Current code evidence |
+|------|------|--------|------|-----------------------|
+{% for row in projectAnalysis.entryPoints -%}
+| {{ row.kind | mdcell }} | `{{ row.path | mdcell }}` | `{{ row.symbol | mdcell }}` | {{ row.role | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} |
+{% endfor %}
+
+### 5.10.3 Stores and External Systems
+
+| Store | Owner | Read boundary | Write boundary | Current code evidence |
+|-------|-------|---------------|----------------|-----------------------|
+{% for row in projectAnalysis.dataStores -%}
+| {{ row.name | mdcell }} | {{ row.ownerComponentId | mdcell }} | {{ row.readBoundary | mdcell }} | {{ row.writeBoundary | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} |
+{% endfor %}
+
+| External system | Adapter | Direction | Current code evidence |
+|-----------------|---------|-----------|-----------------------|
+{% for row in projectAnalysis.externalSystems -%}
+| {{ row.name | mdcell }} | {{ row.adapter | mdcell }} | {{ row.direction | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} |
+{% endfor %}
+
+### 5.10.4 Feature Index
+
+| ID | Name | Description | Representative entry point | Related components | Current code evidence |
+|----|------|-------------|----------------------------|--------------------|-----------------------|
+{% for row in projectAnalysis.featureIndex -%}
+| {{ row.id | mdcell }} | {{ row.name | mdcell }} | {{ row.description | mdcell }} | `{{ row.representativeEntryPoint.path | mdcell }}:{{ row.representativeEntryPoint.symbol | mdcell }}` | {{ row.componentIds | join(', ') | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} |
+{% endfor %}
+
+- Scan coverage: `{{ projectAnalysis.scanCoverage.scannedPathCount }}` scanned / `{{ projectAnalysis.scanCoverage.unscannedPathCount }}` unscanned — {{ projectAnalysis.scanCoverage.reason }}
+
+{% endif %}
+{% if featureAnalysis %}
+## 5.11 Feature Analysis
+
+{{ t("analysis.featureIntro") }}
+
+### 5.11.1 Confirmed Target
+
+| Mode | Requested value | Feature ID | Entry points |
+|------|-----------------|------------|--------------|
+| `{{ featureAnalysis.target.inputMode | mdcell }}` | {{ featureAnalysis.target.requestedValue | mdcell }} | {{ (featureAnalysis.target.featureId or '--') | mdcell }} | {% for row in featureAnalysis.target.entryPoints %}`{{ row.path | mdcell }}:{{ row.symbol | mdcell }}`{% if not loop.last %}<br>{% endif %}{% endfor %} |
+
+### 5.11.2 Flows, Rules, and State Changes
+
+| ID | Kind | Claim | Current code evidence | Source reports |
+|----|------|-------|-----------------------|----------------|
+{% for row in featureAnalysis.flows -%}
+| {{ row.id | mdcell }} | `{{ row.kind | mdcell }}` | {% for step in row.steps %}{{ step.sequence | mdcell }}. {{ step.action | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} | {{ row.sourceReportRefs | join(', ') | mdcell }} |
+{% endfor %}
+{% for row in featureAnalysis.domainRules -%}
+| {{ row.id | mdcell }} | `rule` | {{ row.condition | mdcell }} → {{ row.outcome | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} | {{ row.sourceReportRefs | join(', ') | mdcell }} |
+{% endfor %}
+{% for row in featureAnalysis.stateChanges -%}
+| {{ row.id | mdcell }} | `state-change` | {{ row.dataStore | mdcell }}.{{ row.field | mdcell }} — {{ row.change | mdcell }}{% if row.sideEffects %}<br>Side effects: {{ row.sideEffects | join(', ') | mdcell }}{% endif %} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} | {{ row.sourceReportRefs | join(', ') | mdcell }} |
+{% endfor %}
+
+### 5.11.3 External Interactions and Tests
+
+| Target | Input | Output | Failure handling | Current code evidence |
+|--------|-------|--------|------------------|-----------------------|
+{% for row in featureAnalysis.externalInteractions -%}
+| {{ row.target | mdcell }} | {{ row.input | mdcell }} | {{ row.output | mdcell }} | {{ row.failureHandling | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} |
+{% endfor %}
+
+| ID | Target IDs | Test paths | Gaps |
+|----|------------|------------|------|
+{% for row in featureAnalysis.testCoverage -%}
+| {{ row.id | mdcell }} | {{ row.targetIds | join(', ') | mdcell }} | {{ row.testPaths | join(', ') | mdcell }} | {{ (row.gaps | join(', ') or '--') | mdcell }} |
+{% endfor %}
+
+{% endif %}
+{% if changeImpactAnalysis %}
+## 5.12 Change Impact Analysis
+
+{{ t("analysis.changeImpactIntro") }}
+
+### 5.12.1 Change and Preserved Behavior
+
+- Change request: {{ changeImpactAnalysis.changeRequest.summary }} — evidence: `{{ changeImpactAnalysis.changeRequest.briefEvidence }}`
+
+| Preserved behavior | Current code evidence |
+|--------------------|-----------------------|
+{% for row in changeImpactAnalysis.preservedBehaviors -%}
+| {{ row.statement | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} |
+{% endfor %}
+
+### 5.12.2 Impact Items and Blast Radius
+
+| ID | Target | Impact kind | Level | Confidence | Source reports | Current code evidence |
+|----|--------|-------------|-------|------------|----------------|-----------------------|
+{% for row in changeImpactAnalysis.impactItems -%}
+| {{ row.id | mdcell }} | {{ row.target | mdcell }} | {{ row.impactKind | mdcell }} | `{{ row.level | mdcell }}` | `{{ row.confidence | mdcell }}` | {{ row.sourceReportRefs | join(', ') | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} |
+{% endfor %}
+
+| Source impact ID | Affected target | Direction | Current code evidence |
+|------------------|-----------------|-----------|-----------------------|
+{% for row in changeImpactAnalysis.dependencyBlastRadius -%}
+| {{ row.sourceImpactId | mdcell }} | {{ row.affectedTarget | mdcell }} | {{ row.direction | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} |
+{% endfor %}
+
+### 5.12.3 Test, Operational, and Planning Inputs
+
+| Test scope | Action | Test paths | Current code evidence |
+|------------|--------|------------|-----------------------|
+{% for row in changeImpactAnalysis.testImpact -%}
+| {{ row.scope | mdcell }} | `{{ row.action | mdcell }}` | {{ row.testPaths | join(', ') | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} |
+{% endfor %}
+
+| Operational area | Impact | Current code evidence |
+|------------------|--------|-----------------------|
+{% for row in changeImpactAnalysis.operationalImpact -%}
+| {{ row.area | mdcell }} | {{ row.impact | mdcell }} | {% for evidence in row.currentCodeEvidence %}`{{ evidence.path | mdcell }}:{{ evidence.line | mdcell }}` — {{ evidence.claim | mdcell }}{% if not loop.last %}<br>{% endif %}{% endfor %} |
+{% endfor %}
+
+| Planning constraint | Unknown |
+|---------------------|---------|
+{% for row in changeImpactAnalysis.planningInputs -%}
+| {{ row.constraint | mdcell }} | `{{ row.unknown | mdcell }}` |
+{% endfor %}
+
 {% endif %}
 {# `improvement-discovery` is not in the data.json TaskType enum — its
    `## 5.9 Improvement Candidates` report is authored directly by the report

package/runtime/templates/reports/i18n/en.json

@@ -60,6 +60,14 @@
       "readerSummary": "The shortest reader path: what was decided, what a human must do next, and which audit details can wait until a deeper review.",
       "endStateCoverage": "One row per end-state id the brief pinned, and how this phase accounted for it. A row that is not `addressed` must say why."
     },
+  "analysis": {
+    "basisIntro": "Immutable run snapshot, bounded scan scope, current-code facts, inferences, unknowns, and review disposition for this analysis.",
+    "projectIntro": "Project components, boundaries, entry points, dependencies, stores, external systems, and the shallow feature index.",
+    "featureIntro": "The confirmed feature target's flows, rules, state changes, external interactions, and test coverage.",
+    "changeImpactIntro": "The proposed change's preserved behavior, impacted targets, dependency propagation, test and operational effects, and planning constraints.",
+    "empty": "- No rows recorded.",
+    "reviewNotRecorded": "not reviewed"
+  },
   "tokenSummary": {
     "heading": "Token Usage Summary",
     "tableHeaderItem": "Item",

package/runtime/templates/reports/i18n/ko.json

@@ -60,6 +60,14 @@
       "readerSummary": "가장 짧은 읽기 경로입니다. 무엇이 결정됐는지, 사람이 다음에 무엇을 해야 하는지, 어떤 감사 세부사항은 나중에 봐도 되는지 먼저 보여줍니다.",
       "endStateCoverage": "브리프가 고정한 종료 상태 id 별로 이번 phase 가 어떻게 처리했는지 기록합니다. `addressed` 가 아닌 행은 사유가 있어야 합니다."
     },
+  "analysis": {
+    "basisIntro": "이 분석의 불변 실행 스냅샷, 제한된 스캔 범위, 현재 코드 사실, 추론, 미확인 항목, 검토 처리 결과입니다.",
+    "projectIntro": "프로젝트 구성요소, 경계, 진입점, 의존성, 저장소, 외부 시스템, 얕은 기능 인덱스입니다.",
+    "featureIntro": "확인된 기능 대상의 흐름, 규칙, 상태 변화, 외부 상호작용, 테스트 범위입니다.",
+    "changeImpactIntro": "제안 변경의 보존 동작, 영향 대상, 의존성 전파, 테스트·운영 영향, 계획 제약입니다.",
+    "empty": "- 기록된 행이 없습니다.",
+    "reviewNotRecorded": "검토되지 않음"
+  },
   "tokenSummary": {
     "heading": "토큰 사용량 요약",
     "tableHeaderItem": "항목",

package/runtime/templates/reports/project-analysis-input.template.md

@@ -0,0 +1,58 @@
+---
+title: OKSTRA Project Analysis Input - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: ready-for-agent
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
+---
+
+# OKSTRA Project Analysis Input
+
+## Identity
+
+- Project ID:
+- Task Group:
+- Task ID:
+- Related Tasks:
+- Issue / Ticket:
+- Task Type: `project-analysis`
+- Requested Outcome:
+
+## User Intent
+
+- What decision or understanding should this project map support?
+- Who will use the analysis and for what next action?
+
+## Scan Scope
+
+- Repositories and directories to inspect:
+- Entry points or components to prioritise:
+- External systems or integrations to include:
+- Explicitly excluded repositories, directories, or systems:
+
+## Preserved Boundaries
+
+- Behavior or contracts that must be treated as unchanged:
+- Ownership, security, compatibility, or operational boundaries:
+- Unknown boundaries that require clarification:
+
+## Questions for Analysers
+
+1. Which components, dependency directions, entry points, repositories, and external integrations are in scope?
+2. What shallow feature index best helps a later task navigate this area?
+3. Which scan boundaries prevent the analysis from becoming a detailed feature or implementation plan?
+
+## Input Limit
+
+- Collect user intent, scan scope, and preserved boundaries only.
+- Do not add worker-produced result tables to this input.
+- The final report `data.json` is the result source of truth.
+
+## Conversion Note
+
+- This input can be used as a starting draft before creating `okstra-task-brief.md`.

package/runtime/templates/reports/report.js

@@ -8,7 +8,8 @@
  *      data-response-id> (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">, offer a
+ *   3. Collect the analysis-only Accept / Request revision / Reject control.
+ *   4. 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
@@ -105,6 +106,47 @@
     return { approved: true, implementationOption: option };
   }
 
+  function validateAnalysisReview(review) {
+    if (!review) return null;
+    var allowed = ["accepted", "revision-requested", "rejected"];
+    if (allowed.indexOf(review.status) < 0) {
+      throw new Error("ANALYSIS REVIEW Status is invalid");
+    }
+    if (
+      (review.status === "revision-requested" || review.status === "rejected") &&
+      ((!review.affectedIds || review.affectedIds.length === 0) || !trimMultiline(review.reason))
+    ) {
+      throw new Error(
+        "ANALYSIS REVIEW " + review.status + " requires Affected-IDs and Reason"
+      );
+    }
+    return review;
+  }
+
+  function collectAnalysisReview() {
+    var selected = document.querySelector(
+      'input[name="analysis-review-status"]:checked'
+    );
+    if (!selected) return null;
+    var affected = document.getElementById("analysis-review-affected-ids");
+    var affectedIds = [];
+    if (affected) {
+      for (var i = 0; i < affected.options.length; i++) {
+        if (affected.options[i].selected) affectedIds.push(affected.options[i].value);
+      }
+    }
+    var reason = document.getElementById("analysis-review-reason");
+    var evidence = document.getElementById("analysis-review-evidence");
+    var scope = document.getElementById("analysis-review-scope-change");
+    return validateAnalysisReview({
+      status: selected.value,
+      affectedIds: affectedIds,
+      reason: reason ? trimMultiline(reason.value) : "",
+      additionalEvidence: evidence ? trimMultiline(evidence.value) : "",
+      requestedScopeChange: scope ? trimMultiline(scope.value) : "",
+    });
+  }
+
   // Toggle the visibility of the "기타" companion input next to each
   // select whose current value is "__other__". Wired at bind() time and
   // also called once for the initial state.
@@ -124,7 +166,27 @@
     }
   }
 
-  function buildUserResponseMarkdown(runMeta, entries, createdAt, approval) {
+  function quotedReviewField(label, value) {
+    var cleaned = trimMultiline(value);
+    if (!cleaned) return "- " + label + ":\n";
+    return "- " + label + ":\n" + cleaned.split("\n").map(function (line) {
+      return "  > " + line + "\n";
+    }).join("");
+  }
+
+  function serialiseAnalysisReview(review) {
+    review = validateAnalysisReview(review);
+    return (
+      "\n## ANALYSIS REVIEW\n" +
+      "- Status: " + review.status + "\n" +
+      "- Affected-IDs: " + (review.affectedIds || []).join(", ") + "\n" +
+      quotedReviewField("Reason", review.reason) +
+      quotedReviewField("Additional-Evidence", review.additionalEvidence) +
+      quotedReviewField("Requested-Scope-Change", review.requestedScopeChange)
+    );
+  }
+
+  function buildUserResponseMarkdown(runMeta, entries, createdAt, approval, analysisReview) {
     var head =
       "---\n" +
       "task-key: " + (runMeta["task-key"] || "") + "\n" +
@@ -139,6 +201,7 @@
 
     entries = entries || [];
     var hasApproval = !!(approval && approval.approved);
+    var hasAnalysisReview = !!analysisReview;
     var chunks = "";
     for (var i = 0; i < entries.length; i++) {
       var e = entries[i];
@@ -155,7 +218,7 @@
       }
       chunks += chunk;
     }
-    if (entries.length === 0 && !hasApproval) {
+    if (entries.length === 0 && !hasApproval && !hasAnalysisReview) {
       chunks += "\n_(No user responses recorded.)_\n";
     }
     if (hasApproval) {
@@ -165,6 +228,9 @@
           "- Implementation-Option: " + trimMultiline(approval.implementationOption) + "\n";
       }
     }
+    if (hasAnalysisReview) {
+      chunks += serialiseAnalysisReview(analysisReview);
+    }
     return head + chunks;
   }
 
@@ -187,13 +253,25 @@
     var runMeta = readRunMeta();
     var entries = collectEntries();
     var approval = collectApproval();
-    var md = buildUserResponseMarkdown(runMeta, entries, isoNowUtc(), approval);
     var out = document.getElementById("user-response-output");
+    var analysisReview;
+    try {
+      analysisReview = collectAnalysisReview();
+    } catch (e) {
+      if (out) out.textContent = e.message || String(e);
+      showDismiss(true);
+      return "";
+    }
+    var md = buildUserResponseMarkdown(
+      runMeta, entries, isoNowUtc(), approval, analysisReview
+    );
     if (out) out.textContent = md;
     showDismiss(true);
     // Nothing answered yet — show the empty serialisation as feedback but
     // don't download a useless file.
-    if (entries.length > 0 || approval) downloadUserResponse(md, runMeta);
+    if (entries.length > 0 || approval || analysisReview) {
+      downloadUserResponse(md, runMeta);
+    }
     return md;
   }
 
@@ -312,6 +390,7 @@
       buildUserResponseMarkdown: buildUserResponseMarkdown,
       collectEntries: collectEntries,
       collectApproval: collectApproval,
+      collectAnalysisReview: collectAnalysisReview,
       exportUserResponse: exportUserResponse,
       setReaderMode: setReaderMode,
     };

package/runtime/templates/reports/user-response.template.md

@@ -9,7 +9,7 @@ This file defines the standard format of the markdown produced by the **Export u
 
 ```yaml
 task-key: <task-group>/<task-id>
-task-type: <requirements-discovery | error-analysis | implementation-planning | implementation | final-verification | release-handoff>
+task-type: <requirements-discovery | error-analysis | implementation-planning | implementation | final-verification | release-handoff | project-analysis | feature-analysis | change-impact-analysis>
 seq: <3-digit zero-padded run sequence>
 source-report: <project-relative path to the final-report .md the HTML was derived from>
 created-by: user
@@ -78,6 +78,24 @@ When you check approval in the Plan Approval widget and Export, the following bl
 - The parser is `parse_user_response_approval` in `scripts/okstra_ctl/user_response.py`, and it accepts only the lowercase `Approved: true` that is byte-identical to the producer output (hand-edited values such as `TRUE` are rejected fail-closed).
 - `--resume-clarification` attaches the sidecar verbatim, so the APPROVAL block is carried along as-is — it is harmless residual information in a planning re-run input.
 
+## ANALYSIS REVIEW block (analysis reports only)
+
+The Analysis Review control appends one decision block. `revision-requested` and `rejected` require at least one affected structured analysis ID and a reason. Optional empty values keep their field lines but do not emit an empty quote line.
+
+```markdown
+## ANALYSIS REVIEW
+- Status: <accepted | revision-requested | rejected>
+- Affected-IDs: <comma-separated structured analysis IDs>
+- Reason:
+  > <one quoted line per input line>
+- Additional-Evidence:
+  > <optional evidence>
+- Requested-Scope-Change:
+  > <optional scope change>
+```
+
+The block is the review decision's sole storage location. Export never changes the source final-report markdown. A later analysis rerun receives the sidecar through `--clarification-response` and records one `analysisReviewResolution` row for each imported affected ID.
+
 ## Compatibility Rules
 
 - If `Kind` has an unknown value, the form renders with a `<textarea>` fallback, and the received `Kind` string is preserved as-is during serialization.