okstra 0.220.1 → 0.221.0

package/runtime/skills/okstra-setup/references/project-config.md

@@ -301,3 +301,37 @@ preserves it:
   records that it read no rules and the run still passes. Whether a pack that
   does resolve was actually read and applied stays the phase's own
   `project-review-rules:` record — no machine check reads a worker's reasoning.
+
+## H. MCP servers (`mcpServers`)
+
+`mcpServers` declares the MCP servers a run may use — a Figma file server for a
+visual check, for example. Without a declaration the launch prompt and the
+analysis packet tell every worker that MCP is unavailable, even when a provider
+CLI has the server configured.
+
+Register each server with `okstra mcp add`. `--tool` repeats per tool;
+`--alias` repeats per name a provider CLI lists the server under (one provider
+may list Figma as `claude.ai Figma`, another as `figma-desktop`):
+
+```bash
+okstra mcp add --name figma --description "Figma design files" --tool get_screenshot --tool get_metadata --alias "claude.ai Figma" --alias figma-desktop
+```
+
+Then check which providers can reach it:
+
+```bash
+okstra mcp check
+```
+
+Each provider adapter lists its own CLI's MCP servers without an inference
+call. `reachable` means the provider listed the server enabled; `disabled`
+means listed but disabled or awaiting authentication; `missing` means not
+listed; `unknown` means the adapter cannot list. Show the result to the user.
+For a provider that is not `reachable`, tell the user to add the server to that
+provider CLI's own MCP configuration — okstra never edits a provider's
+configuration. `okstra mcp list` and `okstra mcp remove --name <name>` manage
+existing entries.
+
+prepare repeats the check for the providers a run selects and prints a warning
+for each gap; it never refuses the run. It also warns when the task brief cites
+a Figma URL and no declared server name or alias contains `figma`.

package/runtime/templates/report-writer-prompt-preamble.md

@@ -30,7 +30,7 @@ The narrative is not free-form Markdown. A narrative file is the line `# OKSTRA
 
 Blank lines are ignored. **Every other line is rejected**, including Markdown headings (`#`, `##`, `###`), a pipe table written at column 0, code fences, bare paragraphs, JSON, YAML, and JSON Pointer. A heading or table that belongs in the reader's report is written as the text of a `> ` value, never as a narrative line of its own.
 
-Follow the task-specific schema order. Write every `> ` prose value directly in the language named by `**Report Language:**`; do not draft in English first, because no translation step follows. Field names, `Verdict Token` and other enum or status values, finding and requirement ids, paths, symbols, commands, and model names stay exactly as the schema and sources spell them.
+Follow the task-specific schema order. Write every `> ` prose value directly in the language named by `**Report Language:**`; do not draft in English first, because no translation step follows. A host, project or global instruction file (`CLAUDE.md`, `AGENTS.md`) does not change that language for report artifacts. Field names, `Verdict Token` and other enum or status values, finding and requirement ids, paths, symbols, commands, and model names stay exactly as the schema and sources spell them.
 
 ### Top-level fields you may author
 

package/runtime/templates/reports/task-brief.template.md

@@ -154,13 +154,13 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Available MCP Servers
 
-The MCP servers available to this run are declared in `.okstra/project.json`'s `mcpServers` array and rendered into the Okstra lead's launch prompt under `## Available MCP Servers`. The lead is responsible for forwarding the rendered list verbatim into worker prompts (Phase 2) so each assignment can determine whether its selected runner exposes the named tools.
+The MCP servers available to this run are declared in `.okstra/project.json`'s `mcpServers` array. Prepare renders them, with the providers that list each server, into the lead's launch prompt and the analysis packet under `## Available MCP Servers`.
 
-To declare servers, add entries shaped `{ "name": "<server>", "description": "...", "tools": ["..."], "notes": "..." }` to that array. If the array is empty or absent, treat MCP as unavailable for this run.
+To declare a server, run `okstra mcp add --name <server> --description <text> --tool <tool>... [--alias <name-as-a-provider-lists-it>...]`, then `okstra mcp check` to see which providers reach it. If nothing is declared, treat MCP as unavailable for this run.
 
 How to invoke (worker-by-worker):
 
-- **Native-session assignments**: invoke an MCP tool directly by its tool name (e.g. `mcp__<server>__<tool>`) only when the selected host adapter exposes it. Do not call an MCP tool name through a shell.
+- **Native-session assignments**: invoke an MCP tool directly through the host's tool interface, under the name the host adapter exposes, only when it exposes the server. Do not call an MCP tool name through a shell.
 - **CLI-wrapper assignments**: use only the MCP or tool configuration explicitly supported and forwarded by that provider wrapper. If the wrapper has no matching MCP configuration, record `MCP not available in this CLI` in `Missing Information or Assumptions`; do not attempt a shell fallback.
 - All workers: cite the exact server, tool, and SELECT (or `WHERE` filters) used in the result file. Tool-call failures must be logged in the worker's `*-errors.json` (commandKind `mcp_call`) so the lead can decide whether to retry under a different worker.
 

package/runtime/validators/validate-run.py

@@ -2342,6 +2342,15 @@ def _validate_conformance_surfaces(
         )
 
 
+def _stage_ended_without_a_commit(report_data: dict) -> bool:
+    implementation = report_data.get("implementation")
+    if not isinstance(implementation, dict):
+        return False
+    evidence = implementation.get("stageSidecarEvidence")
+    withheld = isinstance(evidence, dict) and str(evidence.get("withheld") or "").strip()
+    return bool(withheld) and not implementation.get("commitList")
+
+
 def _validate_conformance(
     report_path: Path,
     failures: list[str],
@@ -2389,6 +2398,10 @@ def _validate_conformance(
         )
         if declared_manifest is None:
             return warnings
+        # 스크립트와 manifest 항목은 stage 를 실행한 run 이 쓴다. 커밋 없이 carry 를
+        # 보류한 run(첫 편집 전 정지 후 재계획)은 그것을 쓸 기회가 없었다.
+        if _stage_ended_without_a_commit(report_data):
+            declared_manifest = None
     if declared_manifest is not None:
         scoped_declared = _scope_manifest_entries(declared_manifest, stage_name)
         for error in missing_declared_scripts(