feat: figure Tool CLI, agent-plan receipts and offline evidence console

AGENTS.md

@@ -261,3 +261,7 @@ Do not auto-merge, force-push, or write maintenance repairs directly to `main`.
 ## Public boundary
 
 Do not publish private Jules prompts, repository memory, hidden reasoning, credentials, or unrelated operator context. Public governance may preserve the effect of a rule without copying private control text.
+
+## Native Tool / CLI / Agent and UI interface (2026-10-19 proposal)
+
+`tool_cli.py` exposes local preflight/communication handoff as two allowlisted tools with typed receipts; it does not invoke actual rendering or a model. Declared agent plans stop after failure. The offline `ui/tri_repo_console.html` uses locally selected JSON text only and is not the experimental `core/observer_dashboard.py` or a live observer. See `docs/02-examples-and-contracts/TOOL_CLI_AGENT_CONTRACT.md` and `TOOL_UI_STYLE.md`; do not infer MCP, scientific validity, full WCAG certification, publisher acceptance or completed CI from this proposal.

MANIFEST.yaml

@@ -441,3 +441,24 @@ scientific_boundaries:
 # no A→H synthesis artifact is inferred or manufactured by this annotation.
 # This is routing metadata only: calibrated=2026-09-22 is preserved, and no runtime capability,
 # machine-contract semantics, scientific validation, reproduction status, or release authority is changed.
+
+# Native Tool/CLI and local UI proposal, 2026-10-19
+native_tool_cli:
+  module: tool_cli.py
+  profile: sci-render-kit/tool-execution
+  agent_plan_profile: sci-render-kit/agent-plan
+  declared_plan_max_steps: 32
+  allowlisted_tool_count: 2
+  output_receipt: explicit_atomic_write_only
+  transport: local_json_cli_not_mcp_server
+  model_calls: false
+  remote_tool_execution: false
+  scientific_validity_claim: false
+  independent_reproduction_claim: false
+  proof_scope: local_proposal_requires_real_test_evidence
+native_evidence_ui:
+  path: ui/tri_repo_console.html
+  mode: offline_local_json_file_viewer
+  network_execution: false
+  live_provider_or_ci_data: false
+  wcag_conformance_claim: false

Makefile

@@ -12,10 +12,14 @@ clean:
 	rm -rf __pycache__ .pytest_cache output/*
 	@echo "Cleaned local caches and generated artifacts"
 
-test: test-core test-accessibility
+test: test-core test-accessibility test-tool-interface
 
 test-core:
 	python3 tests/test_all.py
 
 test-accessibility:
 	python3 -m unittest tests.test_accessibility -v
+
+.PHONY: test-tool-interface
+test-tool-interface:
+	python3 -m unittest tests.test_tool_cli tests.test_tool_ui -v

README.md

@@ -6,6 +6,12 @@
 
 [Architecture](docs/01-source-and-explanation/ARCHITECTURE.md) · [Research Contract](docs/02-examples-and-contracts/RESEARCH_CONTRACT.md) · [Figure Claim Contract](docs/02-examples-and-contracts/FIGURE_CLAIM_CONTRACT.md) · [Communication Transfer](docs/02-examples-and-contracts/COMMUNICATION_TRANSFER_CONTRACT.md) · [Assertion Basis & Communication Coverage](docs/02-examples-and-contracts/ASSERTION_BASIS_AND_COMMUNICATION_COVERAGE.md) · [Maintenance](docs/03-maintenance-and-audit/MAINTENANCE_CADENCE.md) · [Document Status](docs/03-maintenance-and-audit/DOCUMENT_STATUS.md) · [August Stage Close](docs/03-maintenance-and-audit/history/STAGE_2026_08_MAINTENANCE.md) · [Frontier Alignment](docs/03-maintenance-and-audit/history/FRONTIER_ALIGNMENT.md) · [Examples](examples/README.md)
 
+## Native Tool / CLI / Agent interface (2026-10-19 integration)
+
+The repository exposes `tool_cli.py` for allowlisted local JSON tool discovery, calls, and deterministic declared agent plans: `python3 tool_cli.py list`, `python3 tool_cli.py call figure.preflight --input request.json`, or `python3 tool_cli.py agent --input examples/tool_plan.json --output output/agent-plan.json`.
+
+[Tool/CLI/Agent contract](docs/02-examples-and-contracts/TOOL_CLI_AGENT_CONTRACT.md) · [Offline Evidence Console](ui/tri_repo_console.html) · [UI style/interaction contract](docs/02-examples-and-contracts/TOOL_UI_STYLE.md). The Console only visualizes locally selected receipts; neither UI nor preflight is a render engine, MCP server, CI monitor, independent reproduction or publisher acceptance claim.
+
 ## Positioning
 
 `sci-render-kit` does not decide whether a scientific conclusion is correct. It compiles a declarative recipe into a supported visual artifact while keeping communication semantics inspectable and portable

docs/02-examples-and-contracts/README.md

@@ -104,3 +104,8 @@ For a new figure/communication integration:
 6. keep scientific claim support and publication/accessibility status separately sourced.
 
 Architecture and implementation explanation live under [`../01-source-and-explanation/`](../01-source-and-explanation/). Maintenance/audit material in class 03 is operational/historical context, not scientific validity.
+
+## Native Tool / CLI / Agent and UI interface (2026-10-19)
+
+- [TOOL_CLI_AGENT_CONTRACT.md](TOOL_CLI_AGENT_CONTRACT.md) — allowlisted tools, JSON receipts, declared-plan runner and validation limits
+- [TOOL_UI_STYLE.md](TOOL_UI_STYLE.md) — offline tri-repository evidence console style, interaction and status boundaries

docs/02-examples-and-contracts/TOOL_CLI_AGENT_CONTRACT.md

@@ -0,0 +1,61 @@
+# Native Tool / CLI / Agent Contract — 2026-10-19
+
+本仓 Tool CLI 是对已有 canonical core 模块的显式封装，不是第二套算法、独立运行时、MCP Server 或 LLM 自动 Agent
+
+## Invocation contract
+
+Tool discovery: python3 tool_cli.py list
+
+Single call: python3 tool_cli.py call TOOL --input request.json --output output/tool-receipt.json
+
+Plan runner: python3 tool_cli.py agent --input examples/tool_plan.json --output output/agent-plan.json
+
+--input 默认为 stdin (-)，--output 为可选的显式原子文件写入。未指定 --output 时只向 stdout 打印 JSON；本接口不会主动远程请求、运行 shell 或调用 LLM
+
+### Envelope
+
+单工具输出 profile = REPOSITORY/tool-execution，包含 repository、tool、status、input_sha256、assertion_basis、output 或 error。input_sha256 是排序键、紧凑序列化后的参数 SHA-256，属于输入身份，不证明内容正确
+
+Agent 输出 profile = REPOSITORY/agent-plan，包含 plan_sha256、status、completed_steps、requested_steps、steps 和 execution_mode。Plan 输入为带 steps 数组的 JSON 对象，元素包含唯一 id、tool、arguments，允许 1–32 步，失败时停止并保留已经执行的步骤，后续步骤保持未执行而非虚报完成
+
+Tools 白名单定义在 tool_cli.py 中，未知工具、错误类型、缺失必需参数、重复 step ID 均为显式错误。exit 0 代表调用正常结束，不代表输出业务 status 或 scientific validity 通过。工具结果中的 valid、evaluation_status、audit_state 由原生模块单独解释
+
+## Tool map
+
+figure.preflight — required recipe_path, optional profile_name; delegates to current YAML schema, sci_render.evaluate_pre_render_rules and core.claim_binding_audit. Does NOT render a figure. evaluation_status:failed can appear inside a successfully executed tool receipt
+
+communication.transfer — required figure_evidence_path, optional destination/purpose; delegates to core.communication_transfer.build_communication_transfer, with non-inheritance constraints
+
+## Human / Agent / UI boundary
+
+Human 或外部 Agent -> JSON parameters / plan -> local allowlisted Tool CLI -> canonical core -> tool/agent receipt -> sci-render-kit offline Evidence Console
+
+- 这不是 MCP transport。不能只因使用 inputSchema / JSON 或工具清单，就宣称支持某个 MCP revision。需要正式 MCP 时应另行使用经核验的 SDK
+- 这是确定性声明式 Agent 计划执行，不会执行模型生成的任意代码，不具备自主推理、持久调度或用户权限认证
+- 本地进程能访问传入的文件路径，不具备 OS 级沙箱和网络隔离保证，不能直接执行不可信计划
+- GUI 位于 sci-render-kit/ui/tri_repo_console.html，本地浏览器手动选择 JSON，不向服务器上传，也不验证 GitHub / CI 实时状态
+- 科学有效性、独立复现和 publisher acceptance 不会从工具成功或绿色 UI 徽标中推导出来
+- 测试入口：python3 -m unittest tests.test_tool_cli -v；仓库 make test 仍属人工可选检查，而非合并门禁
+
+## Demo
+
+Run from repository root:
+
+    python3 tool_cli.py list
+    echo '{"recipe_path":"examples/line_chart.yaml","profile_name":"nature"}' | python3 tool_cli.py call figure.preflight
+    python3 tool_cli.py agent --input examples/tool_plan.json --output output/agent-plan.json
+    python3 sci_render.py examples/line_chart.yaml --profile nature --backend matplotlib
+
+Open ui/tri_repo_console.html, select an exported receipt JSON, inspect step status and original bytes as JSON text. UI never invokes the renderer
+
+## Evidential constraints
+
+operation result != scientific truth
+
+claim transfer != acceptance
+
+figure preflight != generated figure
+
+UI rendering != current repository state
+
+Draft PR != merged or CI validated

docs/02-examples-and-contracts/TOOL_UI_STYLE.md

@@ -0,0 +1,48 @@
+# Three-Repository Evidence Console — UI Style & Interaction Contract
+
+**Owner:** sci-render-kit communication/presentation plane, 2026-10-19
+**Artifact:** [ui/tri_repo_console.html](../../ui/tri_repo_console.html)
+
+## Purpose
+
+Offline, local-first viewer for JSON receipts produced by each repository's tool_cli.py. It is a human review surface, not an execution engine, provider terminal, live GitHub dashboard, automatic scientific evaluator, or WCAG certification
+
+## Design language
+
+Visual direction: calm research operations console — dark navy workbench, restrained mint state highlights, high density with generous card padding, explicit state text. No gradient-as-evidence, no scores fabricated from source data
+
+| Token | Hex | Use |
+|---|---|---|
+| bg | #09111d | page background |
+| panel | #111e2d | evidence surfaces |
+| panel2 | #162537 | local distinction |
+| line | #293d51 | neutral boundaries |
+| fg | #e8f0f6 | primary reading text |
+| muted | #9db1c5 | descriptive metadata |
+| accent | #62ddc1 | selected state/action |
+| warn | #ffd18a | warnings (only with text) |
+| danger | #ffa39c | failure (only with text) |
+
+Typography: operating-system sans stack for body, monospaced pre for exact JSON; heading 30–47 px responsive, body 15 px. Layout: 235 px static sidebar at wide widths; single-column responsive mobile; summary cards wrap at 900 / 500 px
+
+## Observable interaction
+
+1. User selects or drags one local JSON file, limited to 2 MiB
+2. Browser parses JSON locally using File.text; page issues no fetch or storage calls
+3. Profile whitelist: <repo>/tool-execution, <repo>/agent-plan, <repo>/tool-catalog
+4. Text nodes use textContent rather than HTML injection; no dynamic innerHTML with user JSON
+5. Show repository, execution status, actual requested vs completed steps, per-step tool status and input digest; raw JSON can be expanded for review
+6. Unknown and failure status remain textual and are not guessed from badge colors
+
+## Accessibility and boundaries
+
+- File chooser, focus-visible buttons, keyboard Enter/Space upload zone, semantic summary and live region
+- No screenshots or color contrast tests in this PR demonstrate WCAG compliance
+- Green success means a local tool returned a success envelope, NOT source truth, CI success or independent reproduction
+- Importing a receipt is not executing its tool or approving a write
+- Current repository/CI state is not fetched or represented; display is point-in-time evidence from the imported file
+- The historical experimental core/observer_dashboard.py remains untouched and unintegrated; name similarity is not evidence of runtime support
+
+## Next verification gate
+
+Test visually with desktop/mobile viewport, keyboard-only navigation, screen reader if available, and malicious JSON containing angle brackets or script-looking strings. Review both pass and fail snapshots. Browser-based visual verification is **NOT_EXECUTED** unless a matching run report is attached to the change

docs/03-maintenance-and-audit/DOCUMENT_STATUS.md

@@ -102,6 +102,12 @@ later template revision != earlier stage rewrite
 
 Instantiated Stage and Part records remain bounded by their declared evidence window and executed method. Later corrections move interpretation forward without silently rewriting earlier research artifacts.
 
+## Tool / CLI / Agent interface router — 2026-10-19 (additive)
+
+The new current implementation surface is `tool_cli.py` with its read-only allowlisted core calls, deterministic declared agent-plan runner, and `tests/test_tool_cli.py` as an optional local contract check. The active invocation/boundary document is `docs/02-examples-and-contracts/TOOL_CLI_AGENT_CONTRACT.md`, and `examples/tool_plan.json` is a synthetic usage fixture. The additional current presentation surfaces are `ui/tri_repo_console.html`, `docs/02-examples-and-contracts/TOOL_UI_STYLE.md` and `tests/test_tool_ui.py`; they consume local receipts without using the experimental observer dashboard.
+
+This additive router does not advance the recorded Stage/calendar baseline, rewrite historical snapshots, certify MCP compliance, imply LLM agent execution, or assert a full GitHub CI/independent reproducibility result. Real behavior remains subordinate to the current code and machine contract; a Draft PR is not merged authority.
+
 ## Historical and dated evidence
 
 Dated maintenance records and materials under `history/` remain point-in-time evidence. The August stage, frontier material, FOUR/FIVE/SIX_DAY consolidations, correction records, demonstrations, and later dated reconciliations remain recoverable at their original time boundary.

examples/README.md

@@ -5,6 +5,19 @@ They are not GitHub workflow instructions and do not imply scientific validation
 
 See [../DOCUMENT_STATUS.md](../DOCUMENT_STATUS.md) for current-versus-historical document authority
 
+## Native Tool / CLI / Agent and offline console
+
+The missing baseline fixture `examples/line_chart.yaml` is now supplied for the documented render command. The recipe uses **synthetic illustrative data**, not measured science or a publication-ready claim.
+
+```bash
+python3 tool_cli.py list
+python3 tool_cli.py call figure.preflight --input examples/tool_request.json
+python3 tool_cli.py agent --input examples/tool_plan.json --output output/agent-plan.json
+python3 sci_render.py examples/line_chart.yaml --profile nature --backend matplotlib
+```
+
+Open `ui/tri_repo_console.html` in a local browser and select an exported Tool/Agent JSON receipt. It is a **read-only offline review UI**, not a real-time renderer or MCP server. Read `docs/02-examples-and-contracts/TOOL_UI_STYLE.md` for design/interaction constraints.
+
 ## Baseline render
 
 ```bash
@@ -159,7 +172,7 @@ The renderer preserves this declaration but does not validate the upstream stati
 
 ```bash
 python3 sci_render.py examples/line_chart.yaml --profile presentation --backend ggplot2
-python3 sci_render.py examples/line_chart.yaml --profile presentation --backend observable
+python3 sci_render.py examples/line_chart_observable.yaml --profile presentation --backend observable
 ```
 
 Adapter source presence does not prove optional R/Node runtime availability
@@ -215,3 +228,7 @@ The dated first complete three-cadence demonstration is recorded under `maintena
 ## Local maintenance boundary
 
 Local checks are optional maintenance aids, not GitHub merge gates, scientific validation, WCAG certification or publisher acceptance
+
+### Backend-specific fixture boundary (2026-10-19)
+
+The default `examples/line_chart.yaml` requests PNG. Observable supports only HTML in the current backend matrix; its example uses a separate `line_chart_observable.yaml` with `output.format: html`. This is a synthetic fixture and requires an available Node runtime plus browser-side CDN dependency; no offline browser execution or feature parity with Matplotlib is implied.

examples/line_chart.yaml

@@ -0,0 +1,24 @@
+# Bounded synthetic fixture for CLI demonstration; not scientific source data.
+id: line-chart-example
+name: Synthetic two-series tool/CLI fixture
+type: line-chart
+data:
+  control: [1, 2, 3, 4]
+  treatment: [2, 3, 4, 5]
+aesthetics:
+  title: Synthetic observations (fixture)
+  x_label: Sample
+  y_label: Value (arbitrary units)
+  palette: ["#0072B2", "#D55E00"]
+accessibility:
+  require_alt_text: true
+  alt_text: "Synthetic example: control rises from 1 to 4 and treatment from 2 to 5."
+  redundant_encoding: required
+process_disclosure:
+  ai_assistance: not_declared
+  human_review: not_declared
+output:
+  dir: output
+  filename: line_chart.png
+  format: png
+notes: "Illustrative numbers only; no measured experiment, model claim, or publisher acceptance."

examples/line_chart_observable.yaml

@@ -0,0 +1,21 @@
+# Synthetic data: optional Observable HTML fixture, not offline/render verification
+id: line-chart-observable-example
+name: Synthetic two-series HTML output
+type: line-chart
+data:
+  control: [1, 2, 3, 4]
+  treatment: [2, 3, 4, 5]
+aesthetics:
+  title: Synthetic observations (fixture)
+  x_label: Sample
+  y_label: Value (arbitrary units)
+  palette: ["#0072B2", "#D55E00"]
+accessibility:
+  require_alt_text: true
+  alt_text: "Synthetic example, two increasing series across four samples."
+  redundant_encoding: off
+output:
+  dir: output
+  filename: line_chart_observable.html
+  format: html
+notes: "HTML output requires optional Node/browser/CDN runtime; not an offline or publisher validity claim."

examples/tool_plan.json

@@ -0,0 +1,12 @@
+{
+  "steps": [
+    {
+      "id": "figure-preflight",
+      "tool": "figure.preflight",
+      "arguments": {
+        "recipe_path": "examples/line_chart.yaml",
+        "profile_name": "nature"
+      }
+    }
+  ]
+}

examples/tool_request.json

@@ -0,0 +1,4 @@
+{
+  "recipe_path": "examples/line_chart.yaml",
+  "profile_name": "nature"
+}