create-yss-spec 3.4.8 → 3.4.9

package/template/.codex/skills/competitive-intelligence/SKILL.md

@@ -47,7 +47,7 @@ Use this skill when competitive or market facts are needed to shape product Plan
 5. Hand off to lifecycle assets:
    - Update Plan findings in `docs/.scratch/<feature>/plan/`.
    - Create or update a competitor matrix in `docs/.scratch/<feature>/plan/reports/`.
-   - Feed stable user, pain, MVP, non-goal, and success criteria into `grill-with-docs` and `to-spec`.
+   - Return stable user, pain, MVP, non-goal and success criteria to the current lifecycle/strategic owner for its native Plan and Spec work units. Compatibility entries remain explicit-user-only.
    - Record uncertain claims as assumptions, not requirements.
 
 ## Output Shape

package/template/.codex/skills/data-analytics/mcp/server.cjs

@@ -1913,7 +1913,8 @@ function exportDataScienceArtifactPackage(args) {
     archive_path: archivePath,
     worker_entrypoint: path.join(serverDir, "index.js"),
     appgarden_path: path.join(metaDir, "appgarden.json"),
-    access_default: "workspace_all",
+    access_default: null,
+    access_requirement: "explicit-user-selection-before-deployment",
     routes: ["/", "/api/manifest", "/api/snapshot", "/api/package", "/api/source-file", "/api/inline-chart-widget"],
     message:
       "Exported the validated Data Analytics artifact with the canonical MCP app runtime for Site Creator deployment.",

package/template/.codex/skills/data-analytics/skills/analyze-data-quality/SKILL.md

@@ -12,10 +12,13 @@ dashboards, experiments, or downstream pipelines. Start with the intended use an
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Workflow
 
+Choose checks from the data grain, intended decision and known risk. Reuse fresh checks already covering the same source/query/transform; do not repeat the catalog. A notebook is needed only when reproducibility or multi-step analysis warrants it. Preserve blocking correctness findings and report material limitations.
+
+
 1. Clarify the quality question and operating context.
 
    Establish what the dataset represents, the intended unit of analysis, the downstream use, whether the user cares about raw ingestion quality,
@@ -26,7 +29,7 @@ Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mod
 
 2. Choose an inspectable analysis path.
 
-   When checks require SQL or Python, default to a companion notebook so the user can inspect the exact code behind the findings. Use $jupyter-notebooks when a dedicated notebook scaffold or refactor workflow would help. For queryable tables, use `~~structured_data` to confirm schema, grain, sample rows, and query rules through the relevant source connector before heavier checks. Use `~~operations_logs` for freshness and lineage when those checks matter.
+   When multi-step SQL/Python analysis needs a reproducible narrative, use a companion notebook; a bounded check may provide its query/script and result directly. Use $jupyter-notebooks when a dedicated notebook scaffold or refactor workflow would help. For queryable tables, use `~~structured_data` to confirm schema, grain, sample rows, and query rules through the relevant source connector before heavier checks. Use `~~operations_logs` for freshness and lineage when those checks matter.
 
 3. Build a compact profile.
 
@@ -76,35 +79,9 @@ Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mod
 
 ## Standards
 
-### Core Checks
-
-- Completeness: null rate by column; null rate by partition, segment, and time bucket; unexpected empty strings or sentinel values; required-column population rate.
-- Uniqueness: exact duplicate rows, duplicate primary keys, duplicate composite keys, and proportion unique for semi-unique fields such as emails or device IDs.
-- Validity: type conformance after casting; format checks for IDs, emails, URLs,
-  enums, country codes, and timestamps; range checks for measures, percentages,
-  counts, and dates; allowed-values checks for controlled vocabularies.
-- Consistency: cross-field rule checks, units or currency consistency, status and timestamp alignment, and agreement between duplicated fields from different sources.
-- Integrity: parent-child key coverage, orphan records, unexpected many-to-many joins, and broken slowly changing dimension joins.
-- Timeliness: freshness lag from source event time to load time, freshness lag from load time to report time, missing recent partitions, and unexplained historical rewrites or backfills.
-- Volume and shape: row-count drift, distinct-count drift, distribution drift,
-  share-of-total drift for major categories, and new or disappeared categories.
-
-### Specific Check Guidance
-
-- Duplicates and keys: check exact duplicates, primary key duplicates, composite key duplicates at the intended grain, and near-duplicates caused by whitespace,
-  casing, formatting, or late updates. Report count, share of affected rows,
-  duplicated keys, and whether duplication is isolated to a time range, source,
-  or segment.
-- Missingness: distinguish acceptable sparsity from broken completeness. Check null rates over time, newly null columns after schema or pipeline changes, and sentinel values such as `''`, `'unknown'`, `'n/a'`, `0`, or `-1`.
-- Domain validity: check malformed identifiers, country codes, timestamps,
-  impossible values, values outside allowed sets, and cross-field contradictions such as `is_cancelled = false` with a non-null `cancelled_at`.
-- Join coverage: when multiple datasets are involved, check foreign keys that do not match a parent table, unexpected one-to-many expansion, coverage loss when joining to dimensions or experiments, and row counts before and after joins.
-- Freshness and schema drift: check row-count changes against recent history,
-  lag on important date columns, added/removed/retyped columns, and shifts in sparsity or cardinality that suggest upstream changes.
-- Outliers and distribution shifts: use robust methods such as quantiles, MAD,
-  or IQR before defaulting to z-scores. Check sudden changes in mean, median,
-  variance, zero rate, category share, and long-tail behavior.
-- Leakage, backfill, and time travel: check features populated before they should exist, future-dated records, late-arriving data causing unstable recent partitions, and backfills that change historical counts without annotation.
+### 按影响选择检查
+
+先确认 grain、关键字段和决策风险，再按需读取 [质量检查方法](references/quality-checks.md)。对实际使用的字段/关联执行验证；不把全部目录作为每个任务的固定步骤。
 
 ### Severity
 
@@ -145,7 +122,7 @@ For each finding, include:
 - likely cause when known
 - suggested remediation or automated test
 
-When code was used, include or save a notebook containing the key SQL and Python checks and make the notebook path easy to find.
+When code was used, retain the exact queries/scripts and results. Use a notebook when complexity or the requested output calls for one.
 
 ### Defaults
 

package/template/.codex/skills/data-analytics/skills/analyze-data-quality/references/quality-checks.md

@@ -0,0 +1,29 @@
+### Core Checks
+
+- Completeness: null rate by column; null rate by partition, segment, and time bucket; unexpected empty strings or sentinel values; required-column population rate.
+- Uniqueness: exact duplicate rows, duplicate primary keys, duplicate composite keys, and proportion unique for semi-unique fields such as emails or device IDs.
+- Validity: type conformance after casting; format checks for IDs, emails, URLs,
+  enums, country codes, and timestamps; range checks for measures, percentages,
+  counts, and dates; allowed-values checks for controlled vocabularies.
+- Consistency: cross-field rule checks, units or currency consistency, status and timestamp alignment, and agreement between duplicated fields from different sources.
+- Integrity: parent-child key coverage, orphan records, unexpected many-to-many joins, and broken slowly changing dimension joins.
+- Timeliness: freshness lag from source event time to load time, freshness lag from load time to report time, missing recent partitions, and unexplained historical rewrites or backfills.
+- Volume and shape: row-count drift, distinct-count drift, distribution drift,
+  share-of-total drift for major categories, and new or disappeared categories.
+
+### Specific Check Guidance
+
+- Duplicates and keys: check exact duplicates, primary key duplicates, composite key duplicates at the intended grain, and near-duplicates caused by whitespace,
+  casing, formatting, or late updates. Report count, share of affected rows,
+  duplicated keys, and whether duplication is isolated to a time range, source,
+  or segment.
+- Missingness: distinguish acceptable sparsity from broken completeness. Check null rates over time, newly null columns after schema or pipeline changes, and sentinel values such as `''`, `'unknown'`, `'n/a'`, `0`, or `-1`.
+- Domain validity: check malformed identifiers, country codes, timestamps,
+  impossible values, values outside allowed sets, and cross-field contradictions such as `is_cancelled = false` with a non-null `cancelled_at`.
+- Join coverage: when multiple datasets are involved, check foreign keys that do not match a parent table, unexpected one-to-many expansion, coverage loss when joining to dimensions or experiments, and row counts before and after joins.
+- Freshness and schema drift: check row-count changes against recent history,
+  lag on important date columns, added/removed/retyped columns, and shifts in sparsity or cardinality that suggest upstream changes.
+- Outliers and distribution shifts: use robust methods such as quantiles, MAD,
+  or IQR before defaulting to z-scores. Check sudden changes in mean, median,
+  variance, zero rate, category share, and long-tail behavior.
+- Leakage, backfill, and time travel: check features populated before they should exist, future-dated records, late-arriving data causing unstable recent partitions, and backfills that change historical counts without annotation.

package/template/.codex/skills/data-analytics/skills/build-dashboard/SKILL.md

@@ -15,7 +15,7 @@ This skill owns the dashboard brief, delivery-mode selection, metric definitions
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ### Source Discovery And Verification
 

package/template/.codex/skills/data-analytics/skills/build-report/SKILL.md

@@ -13,7 +13,7 @@ If this skill is selected directly or included by a report-mode workflow, the ru
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 Choose exactly one report delivery mode for each run:
 
@@ -90,7 +90,7 @@ Select exactly one delivery mode per run. Do not build an MCP app report and a s
 
    Build the selected surface so it preserves the report reading path, visible titles, evidence order, caveats, and source metadata. Use the delivery-mode specifications in `Report Standards` as implementation guidance for the selected surface, not as a substitute for the report-building workflow.
 
-   If the user asks to share an MCP app report or dashboard as a hosted link, use the artifact app's Site Creator share path after the MCP app is valid. Call `export_artifact_package` to materialize the current manifest, bounded snapshot, package metadata, inline-safe source text, and real MCP artifact runtime into a Site Creator-compatible app; do not hand-roll standalone HTML or publish a viewer that depends on MCP-only host payload state. Follow the `sites-hosting` workflow and default new hosted report access to `workspace_all` unless the user asks for narrower access.
+   If the user asks to share an MCP app report or dashboard as a hosted link, use the artifact app's Site Creator share path after the MCP app is valid. Call `export_artifact_package` to materialize the current manifest, bounded snapshot, package metadata, inline-safe source text, and real MCP artifact runtime into a Site Creator-compatible app; do not hand-roll standalone HTML or publish a viewer that depends on MCP-only host payload state. Follow the `sites-hosting` workflow and use the audience explicitly selected by the user; if unset, keep the report local/private and ask only when sharing is required.
 
    When revising an existing report, treat the current rendered report and source metadata as the starting artifact. Preserve every existing section, visual, table, source, dataset, title, and caveat exactly unless the user explicitly asks to change it or the requested edit makes a narrow dependent update unavoidable. A request to add a section, swap a chart, restyle a visual, or customize one part of the report is not a request to summarize, replace, reorder, or drop the rest of the report. Render the full revised report in the selected surface; do not hand off a section-only, slimmed, or partial replacement artifact when the prior report was complete.
 
@@ -142,7 +142,7 @@ Read [mcp-app-report.md](specifications/mcp-app-report.md) when the selected rep
 - Keep an obvious top-to-bottom report reading path. Do not turn a report into a dashboard grid unless the user asked for a dashboard. Use a single-column document flow by default; half-width visual blocks are acceptable only when labels, series, and interpretation remain readable in the selected surface.
 - Use report markdown blocks for narrative insights and interpretation. Keep chart/table headers neutral, and put takeaways in adjacent narrative blocks rather than hiding the argument inside visual metadata. Markdown blocks are the primary place for the story.
 - Reports should be substantial enough to stand on their own. Do not deliver a report that is mostly a chart/table bundle with a short summary. The reader should be able to understand the answer, evidence, interpretation, caveats, and recommended next step from the narrative itself.
-- Use flexible section names and story-specific ordering, but make sure the report still does the core jobs: answer the user's question directly; explain the metric, cohort, denominator, time window, and comparison basis when they affect interpretation; pair each important number or visual with plain-English interpretation; explain why the finding matters for the decision; state what remains uncertain or could change the conclusion; and include a practical next step when the evidence supports one.
+- Use flexible section names and story-specific ordering, but make sure the report still does the core jobs: answer the user's question directly; explain the metric, cohort, denominator, time window, and comparison basis when they affect interpretation; pair each important number or visual with plain-language interpretation in the user's language; explain why the finding matters for the decision; state what remains uncertain or could change the conclusion; and include a practical next step when the evidence supports one.
 - Use rich markdown beyond the executive summary when it improves scanning:
   bold topic sentences in important body paragraphs, keep recommendations as real markdown lists, and avoid collapsing list items into run-on paragraphs.
 - When using ordered or unordered lists, put each item on its own Markdown line. Do not put `1.`, `2.`, and `3.` items in the same paragraph, and do not leave an intended list item as an unnumbered continuation line.
@@ -183,7 +183,7 @@ Read [mcp-app-report.md](specifications/mcp-app-report.md) when the selected rep
 
 ### Metrics And Language
 
-- Describe metrics in plain English before exposing implementation details.
+- Describe metrics in the user's language before exposing implementation details.
 - Clarify definitions, cohorts, denominators, filters, and comparison baselines before relying on a metric in the report.
 - Choose the most interpretable audience-facing grain: user, account, workspace, task, turn, session, request, revenue, endpoint, customer, org, or another business-facing unit.
 - Put raw numbers in context: percent of an active base, percent of the previous funnel step, percent of total change, comparison to baseline, target, peer segment, or historical range.

package/template/.codex/skills/data-analytics/skills/build-report/report-to-google-doc/SKILL.md

@@ -5,16 +5,16 @@ description: "Narrow conversion skill. Invoke only when the user explicitly asks
 
 # Report To Google Doc
 
-Use this skill only when the user explicitly needs a shareable Google Drive document from an existing HTML analytics report. The source must be an HTML report: a local file, a downloaded blob-hosted report, or a report produced by `$build-report`
+Use this skill when the user requests a local DOCX, a hosted DOCX, or a native Google Doc from an existing HTML analytics report. The source must be an HTML report: a local file, a downloaded blob-hosted report, or a report produced by `$build-report`
 HTML mode. This skill does not convert a live MCP app report directly.
 
-The expected path is HTML -> DOCX -> Drive upload. It is acceptable for Drive to host the upload as a DOCX-backed viewer file rather than a native Google Docs MIME type. Do not use the old Google Docs batch-update request path.
+Choose the requested target: `local-docx` (default for local conversion), `hosted-docx`, or `native-google-docs`. HTML → DOCX is local work; uploading is a separate external action, performed only when requested. A hosted DOCX viewer is not a native Google Doc. Discover an available conversion/import capability and verify the result MIME/type before claiming native delivery.
 
 ## Skill Configuration
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Workflow
 
@@ -30,6 +30,8 @@ Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mod
      --out-dir /tmp/report_to_google_doc_plan
    ```
 
+   The helper defaults to `--target local-docx`. Only for an explicit cloud request, select `--target hosted-docx` or `--target native-google-docs`; the helper still performs no remote action. If dependencies are unavailable and cannot be installed in the authorized scope, use an available local converter and validate against the source, or report the conversion gap.
+
    Omit `--render-workers` on the normal path. Only pass a worker count after benchmarking the same report family locally. If dependencies are missing,
    use a local virtual environment with `beautifulsoup4`, `pillow`, and `python-docx`; `cairosvg` or headless Playwright are optional renderers.
 
@@ -42,32 +44,20 @@ Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mod
      and rendered visual inventory
    - `preflight_checks.json`: source, width, DOCX, and rendered-image checks
    - `report.docx`: generated local Word document
-   - `docx_upload_plan.json`: compact upload instructions
+   - `docx_upload_plan.json`: selected-target handoff plan (no upload steps for local conversion)
    - `placeholder_queries.json`: source mapping debug labels
 
    Do not upload until `preflight_checks.json` has `status: "passed"` with zero errors. Warnings must either be fixed or called out in the handoff.
 
-4. Upload the DOCX.
-
-   ```json
-   mcp__codex_apps__google_drive._upload_file({
-     "file_uri": "/tmp/report_to_google_doc_plan/report.docx",
-     "file_name": "Report Name.docx",
-     "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
-   })
-   ```
-
-   Treat the returned Drive URL as the deliverable. Do not attempt to force native Google Docs conversion, and do not fall back to `_batch_update_document`.
+4. Complete the selected target.
 
-5. Validate the uploaded result.
+   For `local-docx`, validate the local DOCX against the source inventory and stop with its local link. Do not upload, change sharing, or require a Drive connector.
 
-   Confirm the uploaded file is readable and non-empty. Compare uploaded text against the source inventory: title, section headings, executive summary or answer callout, caveats, recommendations, source notes, and source links.
-   Inspect the local `report.docx` structure when available: heading counts,
-   lists, tables, hyperlink relationships, and image relationships should match `manifest.json`.
+   For explicitly requested `hosted-docx` or `native-google-docs`, discover the currently available upload/import capability and read its schema. Never guess a tool name, plugin ID or parameter. If missing, deliver the validated local DOCX and identify the cloud capability gap; do not claim cloud completion or switch the target silently.
 
-6. Hand off the link.
+5. Verify and hand off.
 
-   Return the Drive/Docs URL, local DOCX path, source HTML path, and validation performed. Connector success alone is not enough; the handoff is complete only after the uploaded file and local DOCX structure have been checked against the source report.
+   Check headings, lists, tables, text, links and image relationships against `manifest.json`. For a cloud target, also reopen the returned document and verify content and actual native/hosted type. Return only the selected deliverable links plus source and validation evidence as useful. Connector success alone is insufficient.
 
 ## Standards
 
@@ -114,5 +104,5 @@ python3 <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py \
 jq '.status, .summary' /tmp/report_to_google_doc_plan_smoke/preflight_checks.json
 test -f /tmp/report_to_google_doc_plan_smoke/report.docx
 test -f /tmp/report_to_google_doc_plan_smoke/docx_upload_plan.json
-git diff --check -- plugins/data-analytics/skills/build-report/report-to-google-doc
+git diff --check -- .codex/skills/data-analytics/skills/build-report/report-to-google-doc
 ```

package/template/.codex/skills/data-analytics/skills/build-report/report-to-google-doc/scripts/report_to_google_doc/cli.py

@@ -1,14 +1,7 @@
-"""Build DOCX upload plans for sanitized HTML reports.
+"""Convert HTML to local DOCX and record the requested delivery target.
 
-The script intentionally does not call Google APIs. It produces deterministic
-artifacts that an agent can feed to the Google Drive connector:
-
-1. report.docx contains the locally converted report for Drive upload.
-2. docx_upload_plan.json gives the compact Google Drive upload sequence.
-3. manifest.json records the source inventory for verification.
-
-The expected deliverable is the uploaded DOCX-backed Drive file. Native Google
-Docs MIME conversion is not required.
+No Google APIs are called. Local delivery is the default. Cloud planning requires
+an explicit target and never substitutes for capability discovery or authorization.
 """
 
 from __future__ import annotations
@@ -47,6 +40,7 @@ def main() -> None:
         action="store_true",
         help="Write preflight_checks.json but do not fail the command when checks fail.",
     )
+    parser.add_argument("--target", choices=["local-docx", "hosted-docx", "native-google-docs"], default="local-docx")
     args = parser.parse_args()
     write_outputs(
         args.html,
@@ -54,4 +48,5 @@ def main() -> None:
         chart_mode=args.chart_mode,
         render_workers=args.render_workers,
         strict_preflight=not args.no_strict_preflight,
+        target=args.target,
     )

package/template/.codex/skills/data-analytics/skills/build-report/report-to-google-doc/scripts/report_to_google_doc/plan.py

@@ -5,41 +5,45 @@ from pathlib import Path
 from typing import Any
 
 from .constants import DEFAULT_RENDER_WORKERS, DOC_CONTENT_WIDTH_PT
-from .docx_writer import write_docx
-from .html_parser import parse_html
-from .quality import build_preflight_checks
-from .rendering import render_chart_images
 
 
 def build_docx_upload_plan(
     manifest: dict[str, Any],
     docx_path: Path,
     preflight: dict[str, Any],
+    target: str = "local-docx",
 ) -> dict[str, Any]:
+    if target not in {"local-docx", "hosted-docx", "native-google-docs"}:
+        raise ValueError(f"Unsupported delivery target: {target}")
+    cloud = target != "local-docx"
+    sequence = []
+    if cloud and preflight["status"] == "passed":
+        sequence = [{
+            "capability": "upload_file" if target == "hosted-docx" else "import_native_google_document",
+            "discovery_required": True,
+            "requires_explicit_user_request": True,
+            "file": str(docx_path),
+            "note": "Discover the actual tool schema; capability names are not callable tools.",
+        }]
     return {
         "title": manifest["title"],
         "source_html": manifest["source_html"],
         "docx_file": str(docx_path),
         "preflight_status": preflight["status"],
         "doc_content_width_pt": DOC_CONTENT_WIDTH_PT,
-        "sequence": [
-            {
-                "tool": "mcp__codex_apps__google_drive._upload_file",
-                "file_uri": str(docx_path),
-                "file_name": docx_path.name,
-                "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-            }
-        ],
-        "expected_drive_result": (
-            "A Drive-hosted DOCX file is acceptable. The file does not need to be "
-            "converted to the native Google Docs MIME type."
-        ),
+        "target": target,
+        "remote_action_performed": False,
+        "sequence": sequence,
+        "expected_result": {
+            "local-docx": "Validated local DOCX; no upload or sharing change.",
+            "hosted-docx": "Readable hosted DOCX; not a native Google Doc.",
+            "native-google-docs": "Reopened native Google Doc; a hosted DOCX does not satisfy this target.",
+        }[target],
         "verification": [
-            "fetch or open the uploaded Drive file and confirm it is readable",
-            "compare extracted text against manifest.json headings, lists, source notes, and links",
-            "inspect local report.docx structure for expected headings, tables, lists, and image relationships",
-            "compare generated chart_images/*.png against the HTML report visuals when visual fidelity matters",
-        ],
+            "compare text and structure against manifest.json and source HTML",
+            "inspect headings, tables, lists, links and image relationships",
+            "compare rendered charts with source visuals when applicable",
+        ] + (["reopen the cloud result and verify content and actual native/hosted type"] if cloud else []),
     }
 
 
@@ -52,38 +56,24 @@ def write_docx_upload_readme(
     manifest: dict[str, Any],
     preflight: dict[str, Any],
     docx_path: Path,
+    target: str = "local-docx",
 ) -> str:
-    return f"""# Report-to-Google-Doc DOCX Upload Plan
+    plan = build_docx_upload_plan(manifest, docx_path, preflight, target)
+    return f"""# HTML report delivery plan
 
 Source: `{html}`
-
 Local DOCX: `{docx_path}`
-
-Inventory:
-- headings: {manifest["counts"]["headings"]}
-- native tables/cards: {manifest["counts"]["tables"]}
-- chart images: {manifest["counts"].get("chart_images", 0)}
-- source two-column blocks: {manifest["counts"].get("two_col_source_blocks", 0)}
-- rendered two-column blocks: {manifest["counts"].get("two_col_image_blocks", 0)}
-- inline style spans: {manifest["counts"]["inline_styles"]}
-- lists: {manifest["counts"]["lists"]}
-- preflight: {preflight["status"]} ({preflight["summary"]["errors"]} errors,
-  {preflight["summary"]["warnings"]} warnings)
-
-Expected connector sequence:
-
-1. Inspect `preflight_checks.json`. Do not upload until preflight passes.
-2. Upload `{docx_path}` with `mcp__codex_apps__google_drive._upload_file`.
-3. Treat the Drive-hosted DOCX as the deliverable; it does not need native
-   Google Docs MIME conversion.
-4. Fetch/open the uploaded file and compare it against `manifest.json` and the
-   source HTML report.
-
-This helper intentionally writes only DOCX-upload artifacts. It does not write
-Google Docs batch-update request files such as `seed_requests.json`,
-`table_requests.json`, `content_replacement_requests_template.json`,
-`chart_image_requests_template.json`, `remote_write_plan.json`, or
-`all_requests*.json`.
+Target: `{target}`
+Preflight: `{preflight["status"]}`
+Expected result: {plan["expected_result"]}
+
+Check the source inventory in `manifest.json` and `preflight_checks.json`.
+For local-docx, validate and return the local file. Do not upload.
+A cloud target requires an explicit user request, passed preflight, actual tool
+capability discovery, and content/type verification after reopening the result.
+Missing capability is a delivery gap; a local file is not proof of cloud completion.
+This helper performs no remote actions. `docx_upload_plan.json` is a planning
+artifact with conditional capabilities, not executable tool instructions.
 """
 
 
@@ -93,7 +83,13 @@ def write_outputs(
     chart_mode: str = "image",
     render_workers: int = DEFAULT_RENDER_WORKERS,
     strict_preflight: bool = True,
+    target: str = "local-docx",
 ) -> None:
+    from .docx_writer import write_docx
+    from .html_parser import parse_html
+    from .quality import build_preflight_checks
+    from .rendering import render_chart_images
+
     out_dir.mkdir(parents=True, exist_ok=True)
     manifest = parse_html(html, chart_mode=chart_mode)
     if manifest.get("chart_images"):
@@ -113,6 +109,7 @@ def write_outputs(
         manifest,
         docx_path,
         preflight,
+        target,
     )
     write_json(out_dir / "docx_upload_plan.json", docx_upload_plan)
     readme = write_docx_upload_readme(
@@ -120,6 +117,7 @@ def write_outputs(
         manifest,
         preflight,
         docx_path,
+        target,
     )
     (out_dir / "README.md").write_text(readme, encoding="utf-8")
     if strict_preflight and preflight["status"] != "passed":

package/template/.codex/skills/data-analytics/skills/build-report/report-to-google-doc/tests/test_delivery_plan.py

@@ -0,0 +1,45 @@
+"""External-action boundaries of the generated delivery plan, without cloud writes."""
+import sys
+from pathlib import Path
+import unittest
+
+sys.path.insert(0, str(Path(__file__).parents[1] / 'scripts'))
+from report_to_google_doc.plan import build_docx_upload_plan, write_docx_upload_readme
+
+
+class DeliveryPlanTests(unittest.TestCase):
+    def plan(self, target='local-docx', status='passed'):
+        return build_docx_upload_plan({'title': '报告', 'source_html': 'report.html'}, Path('report.docx'), {'status': status}, target)
+
+    def test_local_conversion_has_no_remote_sequence(self):
+        plan = self.plan()
+        self.assertEqual(plan['sequence'], [])
+        self.assertFalse(plan['remote_action_performed'])
+        self.assertEqual(plan['target'], 'local-docx')
+
+    def test_cloud_plans_require_discovery_and_explicit_request(self):
+        for target in ['hosted-docx', 'native-google-docs']:
+            plan = self.plan(target)
+            step = plan['sequence'][0]
+            self.assertNotIn('tool', step)
+            self.assertTrue(step['discovery_required'])
+            self.assertTrue(step['requires_explicit_user_request'])
+            self.assertFalse(plan['remote_action_performed'])
+        self.assertNotEqual(self.plan('hosted-docx')['sequence'][0]['capability'], self.plan('native-google-docs')['sequence'][0]['capability'])
+
+    def test_failed_validation_never_emits_cloud_steps(self):
+        for target in ['hosted-docx', 'native-google-docs']:
+            self.assertEqual(self.plan(target, 'failed')['sequence'], [])
+
+    def test_unknown_target_is_rejected(self):
+        with self.assertRaises(ValueError): self.plan('share-everywhere')
+
+    def test_readme_keeps_native_and_hosted_results_distinct(self):
+        readme = write_docx_upload_readme(Path('report.html'), {'title': '报告', 'source_html': 'report.html'}, {'status': 'passed'}, Path('report.docx'), 'native-google-docs')
+        self.assertIn('hosted DOCX does not satisfy', readme)
+        self.assertIn('performs no remote actions', readme)
+        self.assertNotIn('mcp__', readme)
+
+
+if __name__ == '__main__':
+    unittest.main()

package/template/.codex/skills/data-analytics/skills/build-report/report-to-google-slides/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: report-to-google-slides
-description: "Narrow conversion skill. Invoke only when the user explicitly asks to convert an existing HTML analytics report into a native Google Slides deck."
+description: "Narrow conversion skill. Invoke only when the user explicitly asks to convert an existing HTML analytics report into a local PPTX or native Google Slides deck."
 ---
 
 # Report To Google Slides
 
-Use this skill only when the user explicitly has an existing HTML analytics report and wants a Google Slides deliverable. The output should be a deck, not a pasted report. A stakeholder skimming the slides should understand the answer, evidence,
+Use this skill only when the user explicitly has an existing HTML analytics report and wants a local PPTX or native Google Slides deliverable. The output should be a deck, not a pasted report. A stakeholder skimming the slides should understand the answer, evidence,
 caveats, and recommended follow-up without opening the source report.
 
 This skill consumes an HTML report. It does not convert a live MCP app report directly; if only an MCP app report exists, build an HTML report from the same source evidence as a separate report delivery mode first.
@@ -14,7 +14,7 @@ This skill consumes an HTML report. It does not convert a live MCP app report di
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Workflow
 
@@ -46,8 +46,7 @@ Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mod
 
 4. Import and verify in Google Slides.
 
-   Import `deck.pptx` with `mcp__codex_apps__google_drive._import_presentation` using `upload_mode="native_google_slides"`. Verify the imported deck with `_get_presentation_outline` and `_get_slide_thumbnail` for every slide when possible. At minimum, inspect the cover, one chart slide, one table slide,
-   and the caveats/sources slides.
+   For a local PPTX request, validate and hand off `deck.pptx` without upload. For an explicitly requested native Slides deliverable, discover the installed presentation import/readback capabilities and their schemas; do not assume tool names. Verify the imported native type, outline and rendered slides through available readback tools. Missing import/readback capability is a named gap; the local PPTX remains a separate deliverable, not proof of native completion.
 
 5. Repair before handoff.
 

package/template/.codex/skills/data-analytics/skills/build-report/report-to-pdf/SKILL.md

@@ -13,7 +13,7 @@ The expected path is static HTML -> Chrome headless print-to-PDF -> PDF verifica
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Workflow
 

package/template/.codex/skills/data-analytics/skills/build-report/specifications/mcp-app-report.md

@@ -55,5 +55,5 @@ Before creating or revising an MCP app report artifact, read `../../../src/analy
 - Preserve the current manifest, bounded snapshot, inline-safe source text, package metadata, reading order, visuals, tables, source details, and narrative.
 - Keep static HTML and PDF exports content-only: include the report title, narrative, visuals, tables, and source details, but omit the interactive top bar and app-only controls.
 - Use the `sites-hosting` workflow for project resolution, local validation, source provenance, artifact preparation, version creation, deployment polling, and access control.
-- Default new hosted report access to `workspace_all` unless the user explicitly requests narrower access. Report the production URL and the configured access mode.
+- Use only the explicitly selected hosting audience; missing audience does not authorize workspace-wide access. Report the production URL and the configured access mode.
 - If the local report package files or validated artifact payload are unavailable, stop and ask for the missing source instead of publishing an empty, fallback, or stale report.

package/template/.codex/skills/data-analytics/skills/design-kpis/SKILL.md

@@ -11,7 +11,7 @@ Design KPI frameworks, set targets, and develop measurement plans that help team
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ### Source Discovery And Verification
 

package/template/.codex/skills/data-analytics/skills/gather-business-context/SKILL.md

@@ -11,7 +11,7 @@ Use this skill to collect the business context needed to understand an analytica
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Workflow