feat(research): add vis-lens family, plan-visualization, output_mode, and report bundling

[Trecek]

Summary

This PR completes the full visualization-planning infrastructure for the research recipe, shipping a 12-lens vis-lens skill family plus plan-visualization orchestrator, a bundle-local-report skill that renders self-contained HTML reports with inlined Mermaid diagrams, and an output_mode ingredient (local | pr, default local) that bifurcates the research pipeline between offline HTML export and GitHub PR creation. Supporting work includes vendoring Mermaid v11 UMD, fixing a stale-tarball lifecycle bug, renaming write-report → generate-report, dual-layer output_mode validation (static recipe rule + runtime MCP gate), a 0.7.77-to-0.8.0.yaml migration note, and a version bump to 0.8.0.

Individual Group Plans

Group A: Infrastructure & Assets

Land the two foundational infrastructure assets required by downstream groups in issue #741:

1. Vendor mermaid.min.js v11 (UMD) into src/autoskillit/assets/mermaid/ — with sibling LICENSE.mermaid (MIT attribution) and VERSION metadata — and add a repeatable task vendor-mermaid target for future updates.
2. Mark the blob binary in a new repo-root .gitattributes so git diff never attempts to text-diff it.
3. Declare markdown-it-py>=3.0 in pyproject.toml and regenerate uv.lock.

No recipe, skill, or server logic is touched. This group is the smallest-blast-radius starting point; all other groups in track A, B, C converge on these assets.

Group B: Bundle Lifecycle Refactor (Stale-Tarball Bug Fix)

Fix a pre-existing bug in the research recipe where commit_research_artifacts compresses and commits the artifact directory before the review/rewrite loop runs, causing re_write_report to drop a fresh report.md next to an already-frozen README.md and artifacts.tar.gz — leaving the archival branch with stale conclusions paired with a stale tarball.

The fix splits commit_research_artifacts into three narrowly-scoped steps:

• stage_bundle — idempotent file organizer (no compression, no rename, no commit)
• re_stage_bundle — identical body, called after re_write_report before re_test
• finalize_bundle — single compression point, runs exactly once at the very end

Group C: vis-lens Pack Registration + P0 Lenses

Register the vis-lens pack in PACK_REGISTRY and ship 5 P0 vis-lens skills (vis-lens-chart-select, vis-lens-uncertainty, vis-lens-antipattern, vis-lens-domain-norms, vis-lens-always-on). Each skill is a single SKILL.md file in skills_extended/. Supporting work: canonical yaml:figure-spec schema embedded in vis-lens-chart-select, 5 entries in skill_contracts.yaml, updated test counts, a new parametrized structural test file, an updated write-recipe/SKILL.md bundled skills catalog, and a corrected docs/skills/visibility.md total count. No recipe wiring — deferred to groupF.

Group D: vis-lens P1 Skills

Ship 4 P1 vis-lens skills: vis-lens-multi-compare, vis-lens-temporal, vis-lens-color-access, and vis-lens-figure-table. Each is a leaf skill following the identical P0 shape from groupC. The work is: (1) extend structural test parametrization to cover the new slugs, (2) add 4 SKILL.md files, (3) register 4 contract entries, and (4) update three count assertions and one doc string. No recipe wiring, no catalog update, no helper Python files.

Group E: vis-lens P2 Lenses + Catalog Finalization

Ship the final 3 P2 visualization-planning lenses (vis-lens-caption-annot, vis-lens-story-arc, vis-lens-reproducibility), completing the 12-lens vis-lens family. Update all supporting infrastructure: skill registration (skill_contracts.yaml, defaults.yaml), test parametrization, documentation (catalog.md, visibility.md), and the bundled-skill enumeration in write-recipe/SKILL.md.

Group F (Part A): plan-visualization + Recipe Wiring

Part A covers: creating the plan-visualization orchestrator skill, updating generate-report/SKILL.md body (the skill renamed in Part B), and all research.yaml changes (new step, rerouted GO edge, create_worktree cmd extension, requires_packs update, and write_report → generate_report step renames).

Group F (Part B): Rename + Test Updates

Part B covers: the write-report/ → generate-report/ directory rename, all mechanical test file updates (rename, step assertions), the skill_contracts.yaml key rename (write-report → generate-report), the _analysis.py exemption update, updating skill reference files (plan-experiment/SKILL.md, run-experiment/SKILL.md), and final grep verification.

Group G: bundle-local-report Skill + Recipe Wiring

Create the bundle-local-report skill that converts a research markdown report into a self-contained report.html with inlined exp-lens mermaid diagrams and inserted plot images from yaml:figure-spec blocks. Wire it as a new finalize_bundle_render recipe step that always runs (on_success and on_failure from finalize_bundle) and routes to begin_archival.

Group H (Part A): output_mode Ingredient + Local/PR Mode Branching

Add an output_mode ingredient (local | pr, default "local") to research.yaml that controls whether the recipe opens a GitHub PR. In local mode the recipe bypasses the PR/review/archival pipeline and exports the finalized HTML bundle to ${source_dir}/research-bundles/{date-slug}/. In pr mode the existing GitHub flow runs on top of the always-generated HTML report.

Group H (Part B): Semantic Validator + Runtime Gate + Version Bump

Supporting infrastructure for the output_mode ingredient added in Part A. This part covers the semantic validator rule (research_output_mode_enum in rules_inputs.py), runtime output_mode value check in tools_kitchen.py, generate-report/SKILL.md update for issue_url injection in local mode, migration note 0.7.77-to-0.8.0.yaml, and version bump 0.7.77 → 0.8.0.

Architecture Impact

Process Flow Diagram

%%{init: {'flowchart': {'nodeSpacing': 42, 'rankSpacing': 54, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;

    %% TERMINALS %%
    START([START])
    COMPLETE([research_complete])
    REJECTED([design_rejected])
    ERROR([escalate_stop])

    subgraph Design ["Design & Planning Phase"]
        direction TB
        Scope["scope<br/>━━━━━━━━━━<br/>Scope experiment"]
        PlanExp["plan_experiment<br/>━━━━━━━━━━<br/>optional_context_refs: revision_guidance"]
        ReviewDesign{"review_design<br/>━━━━━━━━━━<br/>skip_when_false: inputs.review_design<br/>retries: 2"}
        ReviseDesign["revise_design<br/>━━━━━━━━━━<br/>action: route → plan_experiment"]
        ResolveDesign["resolve_design_review<br/>━━━━━━━━━━<br/>retries: 1"]
        PlanViz["★ plan_visualization<br/>━━━━━━━━━━<br/>Tier A: vis-lens-always-on (mandatory)<br/>Tier B: 1-2 experiment-type lenses<br/>Tier C: 0-1 domain lens<br/>Writes: visualization-plan.md<br/>Writes: report-plan.md<br/>Captures: visualization_plan_path, report_plan_path"]
    end

    subgraph ImplPhase ["Implementation Phase"]
        direction TB
        CreateWT["create_worktree<br/>━━━━━━━━━━<br/>Commit plan + scope to research/"]
        ImplLoop["decompose_phases → plan_phase<br/>→ implement_phase (stale: 2400)<br/>━━━━━━━━━━<br/>troubleshoot_implement_failure loop<br/>route: is_fixable → plan_phase"]
        NextPhase{"next_phase_or_experiment<br/>━━━━━━━━━━<br/>more phases?"}
    end

    subgraph ExpExec ["Experiment Execution"]
        direction TB
        RunExp["run_experiment<br/>━━━━━━━━━━<br/>retries: 2, stale_threshold: 2400"]
        AdjustExp["adjust_experiment<br/>━━━━━━━━━━<br/>--adjust flag, stale: 2400"]
        EnsureResults["ensure_results<br/>━━━━━━━━━━<br/>Write placeholder inconclusive file"]
        GenReport["● generate_report<br/>━━━━━━━━━━<br/>renamed from write_report<br/>--output-mode inputs.output_mode<br/>Step 1.5: local mode injects issue blockquote<br/>Step 2.5: run visualization plotting scripts"]
        GenReportInc["● generate_report_inconclusive<br/>━━━━━━━━━━<br/>--inconclusive + --output-mode flags"]
        TestFlow["test → fix_tests → retest<br/>━━━━━━━━━━<br/>push_branch on pass"]
        PrepLenses["prepare_research_pr<br/>+ run_experiment_lenses<br/>━━━━━━━━━━<br/>Parallel lens execution<br/>Captures: selected_lenses, lens_context_paths"]
    end

    subgraph BundleStage ["★ Bundle Staging — NEW"]
        direction TB
        StageBundle["★ stage_bundle<br/>━━━━━━━━━━<br/>Copy phase-groups, phase-plans,<br/>exp-lens diagrams → research_dir/artifacts/<br/>Idempotent, no commit<br/>Non-fatal: always → route_pr_or_local"]
        RoutePRLocal{"★ route_pr_or_local<br/>━━━━━━━━━━<br/>inputs.output_mode == local?"}
    end

    subgraph PRReview ["PR Review Loop  (output_mode == pr)"]
        direction TB
        ComposePR["compose_research_pr<br/>━━━━━━━━━━<br/>Opens GitHub PR<br/>Captures: pr_url"]
        GuardPR{"guard_pr_url<br/>━━━━━━━━━━<br/>context.pr_url truthy?"}
        ReviewAudit["review_research_pr (skip_when_false)<br/>→ audit_claims (skip_when_false, retries: 1)<br/>━━━━━━━━━━<br/>review_verdict + audit_verdict captured"]
        MergeEsc{"merge_escalations<br/>━━━━━━━━━━<br/>needs_rerun?"}
        RerunLoop["re_run_experiment → re_generate_report<br/>→ re_stage_bundle → re_test<br/>━━━━━━━━━━<br/>Full experiment rerun with --adjust<br/>--output-mode flag propagated"]
        RePush["re_push_research<br/>━━━━━━━━━━<br/>git push → finalize_bundle"]
    end

    subgraph FinalizePhase ["★ Finalize Phase — NEW"]
        direction TB
        FinalizeBundle["★ finalize_bundle<br/>━━━━━━━━━━<br/>pr mode: rename report.md → README.md<br/>          archive artifacts, git commit<br/>local mode: keep report.md, skip commit<br/>Captures: report_path_after_finalize"]
        FinalizeRender["★ finalize_bundle_render<br/>━━━━━━━━━━<br/>skill: bundle-local-report (ALWAYS RUNS)<br/>Inline validated mermaid diagrams<br/>Insert figure imgs from visualization-plan.md<br/>Copy mermaid.min.js (UMD, file:// safe)<br/>Writes: report.html<br/>Captures: html_path<br/>Non-fatal: both outcomes → route_archive_or_export"]
        RouteArchExp{"★ route_archive_or_export<br/>━━━━━━━━━━<br/>inputs.output_mode == local?"}
    end

    ExportLocal["★ export_local_bundle<br/>━━━━━━━━━━<br/>Copy research_dir → source_dir/research-bundles/date-slug/<br/>Captures: local_bundle_path<br/>Non-fatal terminal for local mode"]

    subgraph Archival ["Archival (output_mode == pr)"]
        direction TB
        ArchFlow["begin_archival → capture_experiment_branch<br/>→ create_artifact_branch (research/ only)<br/>→ open_artifact_pr → tag_experiment_branch<br/>→ close_experiment_pr (structured comment)"]
    end

    %% MAIN FLOW %%
    START --> Scope --> PlanExp --> ReviewDesign
    ReviewDesign -->|"REVISE"| ReviseDesign --> PlanExp
    ReviewDesign -->|"STOP"| ResolveDesign --> REJECTED
    ReviewDesign -->|"GO — NEW: routes to ★plan_visualization"| PlanViz
    PlanViz --> CreateWT

    CreateWT --> ImplLoop --> NextPhase
    NextPhase -->|"more phases"| ImplLoop
    NextPhase -->|"done"| RunExp
    ImplLoop -->|"fatal failure"| ERROR

    RunExp -->|"success"| GenReport
    RunExp -->|"failure"| AdjustExp
    AdjustExp --> RunExp
    RunExp -->|"exhausted"| EnsureResults
    EnsureResults --> GenReportInc
    GenReport --> TestFlow
    GenReportInc --> TestFlow
    TestFlow -->|"pass"| PrepLenses
    TestFlow -->|"fatal"| ERROR
    GenReport -->|"failure"| ERROR

    PrepLenses --> StageBundle
    StageBundle --> RoutePRLocal

    RoutePRLocal -->|"local — skip entire PR pipeline"| FinalizeBundle
    RoutePRLocal -->|"pr — full PR flow"| ComposePR

    ComposePR --> GuardPR
    GuardPR -->|"no pr_url"| COMPLETE
    GuardPR -->|"has pr_url"| ReviewAudit
    ReviewAudit --> MergeEsc
    MergeEsc -->|"needs rerun"| RerunLoop
    MergeEsc -->|"no rerun"| RePush
    RerunLoop --> RePush
    RePush --> FinalizeBundle

    FinalizeBundle --> FinalizeRender
    FinalizeRender --> RouteArchExp

    RouteArchExp -->|"local"| ExportLocal --> COMPLETE
    RouteArchExp -->|"pr"| ArchFlow --> COMPLETE

    %% CLASS ASSIGNMENTS %%
    class START,COMPLETE,REJECTED,ERROR terminal;
    class Scope,PlanExp,CreateWT,ImplLoop handler;
    class RunExp,AdjustExp,EnsureResults,GenReport,GenReportInc handler;
    class TestFlow,PrepLenses handler;
    class ReviewDesign,GuardPR,MergeEsc stateNode;
    class ReviseDesign,ResolveDesign,NextPhase phase;
    class ReviewAudit,ComposePR,RerunLoop,RePush phase;
    class PlanViz,StageBundle,FinalizeBundle,FinalizeRender,ExportLocal newComponent;
    class RoutePRLocal,RouteArchExp newComponent;
    class ArchFlow output;

Loading

Module Dependency Diagram

%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 70, 'curve': 'basis'}}}%%
graph TB
    %% CLASS DEFINITIONS %%
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef integration fill:#c62828,stroke:#ef9a9a,stroke-width:2px,color:#fff;

    %% ─────────────────────────────────────────────
    %% L3 APPLICATION
    %% ─────────────────────────────────────────────
    subgraph L3 ["L3 — APPLICATION  (server/)"]
        direction LR
        TKITCHEN["● server/tools_kitchen.py<br/>━━━━━━━━━━<br/>+runtime output_mode guard<br/>(pr | local enum check<br/>before load_and_validate)"]
    end

    %% ─────────────────────────────────────────────
    %% L2 DOMAIN
    %% ─────────────────────────────────────────────
    subgraph L2 ["L2 — DOMAIN  (recipe/)"]
        direction TB

        subgraph L2_RULES ["Semantic Rules  (fan-out → _analysis)"]
            direction LR
            RINPUTS["● recipe/rules_inputs.py<br/>━━━━━━━━━━<br/>+research_output_mode_enum<br/>(static enum guard: pr|local)"]
            RPACKS["recipe/rules_packs.py<br/>━━━━━━━━━━<br/>unknown-required-pack<br/>(checks PACK_REGISTRY)"]
            RSKILLS["recipe/rules_skills.py<br/>━━━━━━━━━━<br/>unknown-skill-command<br/>lazy→ workspace.SkillResolver"]
        end

        RANALYSIS["● recipe/_analysis.py<br/>━━━━━━━━━━<br/>ValidationContext  [fan-in: 3]<br/>+generate-report exemption"]
        RCONTRACTS["recipe/contracts.py<br/>━━━━━━━━━━<br/>get_skill_contract<br/>load_bundled_manifest"]
        RSCHEMA["recipe/schema.py<br/>━━━━━━━━━━<br/>RecipeIngredient.default<br/>Recipe.ingredients"]
        RREGISTRY["recipe/registry.py<br/>━━━━━━━━━━<br/>@semantic_rule  [fan-in: 3]"]
    end

    %% ─────────────────────────────────────────────
    %% L1 INFRASTRUCTURE
    %% ─────────────────────────────────────────────
    subgraph L1 ["L1 — INFRASTRUCTURE  (config/ | workspace/ | migration/)"]
        direction LR
        CONFIGDEFAULTS["● config/defaults.yaml<br/>━━━━━━━━━━<br/>+vis-lens in tier2<br/>+plan-visualization<br/>+bundle-local-report"]
        WSKILLS["workspace/skills.py<br/>━━━━━━━━━━<br/>DefaultSkillResolver<br/>scans skills_extended/"]
        MIGLOADER["migration/loader.py<br/>━━━━━━━━━━<br/>applicable_migrations()<br/>via pkg_root()/migrations"]
    end

    %% ─────────────────────────────────────────────
    %% L0 CORE
    %% ─────────────────────────────────────────────
    subgraph L0 ["L0 — CORE  (core/)"]
        direction LR
        TYPECONSTANTS["● core/_type_constants.py<br/>━━━━━━━━━━<br/>PACK_REGISTRY  [fan-in: 5]<br/>+vis-lens PackDef(False)<br/>SKILL_TOOLS, CATEGORY_TAGS"]
        COREPATHS["core/paths.py<br/>━━━━━━━━━━<br/>pkg_root()  [fan-in: 4]<br/>is_git_worktree()"]
    end

    %% ─────────────────────────────────────────────
    %% CONTENT / ASSETS
    %% ─────────────────────────────────────────────
    subgraph CONTENT ["CONTENT / ASSETS  (skills_extended/ | recipes/ | migrations/ | assets/)"]
        direction TB

        subgraph NEWSKILLS ["★ New Skill Content"]
            direction LR
            VISL["★ skills_extended/vis-lens/*<br/>━━━━━━━━━━<br/>12 SKILL.md files<br/>always-on, antipattern,<br/>chart-select, color-access,<br/>domain-norms, figure-table,<br/>multi-compare, temporal,<br/>uncertainty, caption-annot,<br/>story-arc, reproducibility"]
            PLANVIS["★ skills_extended/<br/>plan-visualization<br/>━━━━━━━━━━<br/>orchestrates 2–4 vis-lens skills<br/>(always-on mandatory)"]
            BUNDLEREP["★ skills_extended/<br/>bundle-local-report<br/>━━━━━━━━━━<br/>renders self-contained HTML<br/>copies mermaid.min.js<br/>uses markdown-it-py"]
        end

        subgraph MODCONTENT ["● Modified Recipe / Contracts"]
            direction LR
            RESEARCHYAML["● recipes/research.yaml<br/>━━━━━━━━━━<br/>+output_mode ingredient<br/>default: local (pr|local)<br/>requires_packs: vis-lens"]
            SKILLCONTRACTS["● recipe/skill_contracts.yaml<br/>━━━━━━━━━━<br/>+plan-visualization contract<br/>+bundle-local-report contract<br/>+12 vis-lens contracts"]
        end

        subgraph NEWASSETS ["★ New Assets / Migrations"]
            direction LR
            ASSETS["★ assets/mermaid/<br/>━━━━━━━━━━<br/>mermaid.min.js (UMD)<br/>VERSION, LICENSE"]
            MIGFILE["★ migrations/<br/>0.7.77-to-0.8.0.yaml<br/>━━━━━━━━━━<br/>migration note for 0.8.0"]
        end
    end

    %% ─────────────────────────────────────────────
    %% EXTERNAL
    %% ─────────────────────────────────────────────
    subgraph EXT ["EXTERNAL DEPENDENCIES"]
        MARKDOWNIT["★ markdown-it-py<br/>━━━━━━━━━━<br/>HTML rendering<br/>(graceful ImportError fallback)"]
    end

    %% ═══════════════════════════════════════════
    %% IMPORT RELATIONSHIPS  (solid = import)
    %% ═══════════════════════════════════════════

    %% L3 → L0
    TKITCHEN -->|"imports core"| TYPECONSTANTS

    %% L2 rules → L2 shared (fan-in on _analysis and registry)
    RINPUTS -->|"imports ValidationContext"| RANALYSIS
    RPACKS -->|"imports ValidationContext"| RANALYSIS
    RSKILLS -->|"imports ValidationContext"| RANALYSIS

    RINPUTS -->|"imports @semantic_rule"| RREGISTRY
    RPACKS -->|"imports @semantic_rule"| RREGISTRY
    RSKILLS -->|"imports @semantic_rule"| RREGISTRY

    %% L2 rules → L0 (PACK_REGISTRY / SKILL_TOOLS)
    RINPUTS -->|"imports SKILL_TOOLS"| TYPECONSTANTS
    RPACKS -->|"imports PACK_REGISTRY"| TYPECONSTANTS
    RSKILLS -->|"imports SKILL_TOOLS"| TYPECONSTANTS

    %% L2 rules → contracts / schema
    RINPUTS -->|"imports"| RCONTRACTS
    RSKILLS -->|"imports"| RCONTRACTS
    RANALYSIS -->|"imports"| RCONTRACTS
    RANALYSIS -->|"imports RecipeIngredient"| RSCHEMA
    RINPUTS -->|"imports _TERMINAL_TARGETS"| RSCHEMA

    %% L2 → L0 (core constants)
    RANALYSIS -->|"imports SKILL_TOOLS"| TYPECONSTANTS

    %% L2 lazy cross-layer (L2 → L1)  — valid downward, deferred to avoid circular
    RSKILLS -.->|"lazy import<br/>DefaultSkillResolver"| WSKILLS

    %% L1 → L0
    WSKILLS -->|"imports pkg_root"| COREPATHS
    MIGLOADER -->|"imports pkg_root"| COREPATHS

    %% ═══════════════════════════════════════════
    %% RUNTIME / CONTENT DISCOVERY (dashed)
    %% ═══════════════════════════════════════════

    %% contracts reads skill_contracts.yaml
    RCONTRACTS -.->|"reads"| SKILLCONTRACTS

    %% tools_kitchen validates research.yaml at runtime
    TKITCHEN -.->|"runtime validates<br/>output_mode enum"| RESEARCHYAML

    %% rules_inputs validates research.yaml statically
    RINPUTS -.->|"static rule validates"| RESEARCHYAML

    %% rules_packs validates research.yaml requires_packs
    RPACKS -.->|"validates requires_packs"| RESEARCHYAML

    %% workspace/skills discovers new skills
    WSKILLS -.->|"scans skills_extended/"| VISL
    WSKILLS -.->|"scans skills_extended/"| PLANVIS
    WSKILLS -.->|"scans skills_extended/"| BUNDLEREP

    %% migration loader discovers new migration note
    MIGLOADER -.->|"discovers"| MIGFILE

    %% bundle-local-report copies mermaid asset at runtime
    BUNDLEREP -.->|"copies at runtime"| ASSETS

    %% bundle-local-report imports markdown-it-py
    BUNDLEREP -.->|"imports (optional)"| MARKDOWNIT

    %% plan-visualization orchestrates vis-lens skills
    PLANVIS -.->|"orchestrates 2–4 skills"| VISL

    %% config/defaults.yaml feeds PACK_REGISTRY context
    CONFIGDEFAULTS -.->|"tier2 list mirrors"| TYPECONSTANTS

    %% ═══════════════════════════════════════════
    %% CLASS ASSIGNMENTS
    %% ═══════════════════════════════════════════
    class TKITCHEN cli;
    class RANALYSIS,RINPUTS,RPACKS,RSKILLS phase;
    class RCONTRACTS,RSCHEMA,RREGISTRY handler;
    class TYPECONSTANTS,COREPATHS stateNode;
    class CONFIGDEFAULTS,WSKILLS,MIGLOADER handler;
    class VISL,PLANVIS,BUNDLEREP,MIGFILE,ASSETS newComponent;
    class RESEARCHYAML,SKILLCONTRACTS output;
    class MARKDOWNIT integration;

Loading

Operational Diagram

%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 65, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef gap fill:#ff6f00,stroke:#ffa726,stroke-width:2px,color:#000;
    classDef integration fill:#c62828,stroke:#ef9a9a,stroke-width:2px,color:#fff;
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;

    subgraph CLI_Entry ["CLI / TASK ENTRY POINTS"]
        direction TB
        ORDER["autoskillit order research<br/>━━━━━━━━━━<br/>output_mode: local | pr<br/>Validates recipe before launch"]
        VENDORMERMAID["★ task vendor-mermaid<br/>━━━━━━━━━━<br/>Downloads mermaid v11 UMD<br/>Writes mermaid.min.js + VERSION"]
        MIGRATE["autoskillit migrate<br/>━━━━━━━━━━<br/>Reports pending migrations<br/>--check for CI gating"]
    end

    subgraph Config ["CONFIGURATION (● defaults.yaml)"]
        direction TB
        OUTPUTMODE["● output_mode ingredient<br/>━━━━━━━━━━<br/>local (default, NEW) | pr<br/>BREAKING CHANGE in 0.8.0"]
        DEFAULTS["● defaults.yaml<br/>━━━━━━━━━━<br/>output_mode default: local<br/>Previous default: pr (auto-PR)"]
    end

    subgraph Gate ["KITCHEN GATE"]
        direction TB
        OPENKITCHEN["● open_kitchen / tools_kitchen.py<br/>━━━━━━━━━━<br/>★ Validates output_mode override<br/>Rejects invalid values early<br/>Runtime semantic rule"]
    end

    subgraph Pipeline ["● RESEARCH RECIPE PIPELINE"]
        direction TB
        PLAN["● plan-experiment<br/>━━━━━━━━━━<br/>Plan research phases<br/>Generates experiment design"]
        PLANVIS["★ plan-visualization<br/>━━━━━━━━━━<br/>Select chart types per finding<br/>Apply vis-lens skills"]
        RUNEXP["● run-experiment<br/>━━━━━━━━━━<br/>Execute experiments<br/>Collects results"]
        GENREPORT["● generate-report<br/>━━━━━━━━━━<br/>Renamed from write-report<br/>Produces report artifacts"]
        FINALIZE["★ bundle-local-report<br/>━━━━━━━━━━<br/>finalize_bundle_render step<br/>Always produces report.html<br/>Routes by output_mode"]
    end

    subgraph VisFamily ["★ VIS-LENS SKILL FAMILY (13 new skills)"]
        direction TB
        VISLENSES["★ vis-lens-* (13 skills)<br/>━━━━━━━━━━<br/>always-on · antipattern<br/>caption-annot · chart-select<br/>color-access · domain-norms<br/>figure-table · multi-compare<br/>reproducibility · story-arc<br/>temporal · uncertainty"]
    end

    subgraph MigEngine ["MIGRATION ENGINE"]
        direction TB
        MIGRATENOTE["★ 0.7.77-to-0.8.0.yaml<br/>━━━━━━━━━━<br/>Autodiscovered at recipe load<br/>Explains output_mode breaking change<br/>Guides operators on upgrade"]
    end

    subgraph LocalOut ["★ LOCAL OUTPUT (default mode)"]
        direction TB
        HTMLBUNDLE["★ research-bundles/{slug}/<br/>━━━━━━━━━━<br/>{source_dir}/research-bundles/<br/>report.html (self-contained HTML)<br/>Diagrams via vendored Mermaid"]
        MERMAIDASSET["★ assets/mermaid/mermaid.min.js<br/>━━━━━━━━━━<br/>Vendored Mermaid v11 bundle<br/>Used for HTML diagram rendering"]
    end

    subgraph PROut ["PR OUTPUT (opt-in mode)"]
        direction TB
        GITHUBPR["GitHub Pull Request<br/>━━━━━━━━━━<br/>pr mode: previous default behavior<br/>Opens PR with research report"]
    end

    %% FLOWS %%
    ORDER --> OPENKITCHEN
    ORDER --> OUTPUTMODE
    OUTPUTMODE --> DEFAULTS
    OPENKITCHEN --> PLAN
    PLAN --> PLANVIS
    PLANVIS --> VISLENSES
    PLANVIS --> RUNEXP
    RUNEXP --> GENREPORT
    GENREPORT --> FINALIZE
    FINALIZE -->|local mode default| HTMLBUNDLE
    HTMLBUNDLE -.->|renders diagrams via| MERMAIDASSET
    FINALIZE -->|pr mode opt-in| GITHUBPR
    VENDORMERMAID --> MERMAIDASSET
    MIGRATE --> MIGRATENOTE

    %% CLASS ASSIGNMENTS %%
    class ORDER,VENDORMERMAID,MIGRATE cli;
    class OUTPUTMODE,DEFAULTS phase;
    class OPENKITCHEN detector;
    class PLAN,RUNEXP handler;
    class PLANVIS,GENREPORT,FINALIZE newComponent;
    class VISLENSES newComponent;
    class MIGRATENOTE gap;
    class HTMLBUNDLE,MERMAIDASSET output;
    class GITHUBPR integration;

Loading

Closes #741

Implementation Plan

Plan files:

• .autoskillit/temp/make-plan/groupA_infra_assets_plan_2026-04-12_130117.md
• .autoskillit/temp/make-plan/bundle_lifecycle_refactor_plan_2026-04-12_130100.md
• .autoskillit/temp/make-plan/groupC_vis_lens_p0_plan_2026-04-12_125200.md
• .autoskillit/temp/make-plan/groupD_vis_lens_p1_skills_plan_2026-04-12_130000.md
• .autoskillit/temp/make-plan/groupE_vis_lens_p2_finalize_plan_2026-04-12_130000.md
• .autoskillit/temp/make-plan/groupF_plan_visualization_generate_report_plan_2026-04-12_130200_part_a.md
• .autoskillit/temp/make-plan/groupF_plan_visualization_generate_report_plan_2026-04-12_130200_part_b.md
• .autoskillit/temp/make-plan/bundle_local_report_plan_2026-04-12_125900.md
• .autoskillit/temp/make-plan/output_mode_local_pr_branch_plan_2026-04-12_130500_part_a.md
• .autoskillit/temp/make-plan/output_mode_local_pr_branch_plan_2026-04-12_130500_part_b.md

🤖 Generated with Claude Code via AutoSkillit

Token Usage Summary

Step	uncached	output	cache_read	cache_write	count	time
group	2.7k	68.8k	3.1M	200.8k	1	22m 49s
plan	3.5k	202.1k	6.8M	531.0k	8	1h 10m
verify	4.0k	164.2k	9.5M	546.4k	10	47m 58s
implement	8.1k	254.1k	31.3M	694.5k	11	1h 27m
fix	2.5k	168.4k	17.4M	619.4k	10	1h 31m
audit_impl	1.8k	8.8k	267.9k	35.7k	1	3m 10s
prepare_pr	68	15.8k	461.3k	111.5k	1	4m 24s
run_arch_lenses	2.9k	42.0k	629.3k	242.1k	3	16m 19s
compose_pr	59	12.7k	247.4k	41.6k	1	3m 18s
Total	25.7k	936.9k	69.7M	3.0M		5h 47m

[Trecek]

AutoSkillit PR Review — Verdict: changes_requested

34 findings: 3 critical, 19 warning, 3 decision (requires_decision=true), 9 info.

[Trecek]

[warning] arch: The dead-output exemption for 'local_bundle_path' anchors to step_name ('export_local_bundle') while every other exemption checks skill_command content. This is architecturally inconsistent — a rename of the recipe step would silently re-enable the warning without any type error or test failure. The exemption should anchor to the skill command string like the other exemptions, or document why skill_command is unavailable for run_cmd steps.

[Trecek]

Investigated — this is intentional. export_local_bundle uses tool: run_cmd (no skill_command). step_name is the only viable discriminator for run_cmd steps — all other exempted captures are on run_skill steps that carry skill_command. Intentional structural necessity, documented in inline comment at _analysis.py L544-547.

[Trecek]

[warning] arch: Recipe-specific ingredient validation logic (output_mode enum check for the 'research' recipe) is embedded in the L3 server layer. The semantic rule _check_research_output_mode_enum already exists in recipe/rules_inputs.py (L2 — the correct home). Duplicating it in the server layer creates a split-brain enforcement model: validation runs twice via different code paths, and future changes to allowed values must be kept in sync across two layers.

[Trecek]

Investigated — this is intentional. _check_research_output_mode_enum validates recipe YAML ingredient.default; the runtime gate validates caller-supplied overrides dict at open_kitchen time (before load_and_validate). These guard different inputs at different execution points — complementary not duplicate. See commit 5c69e67.

[Trecek]

[warning] cohesion: generate_report_inconclusive uses step_name: generate_report (unchanged from the old write_report value) instead of generate_report_inconclusive. Every other renamed step (re_generate_report at L685, generate_report at L396) correctly updates step_name to match the step key. This breaks naming symmetry.

[Trecek]

[warning] bugs: re_stage_bundle is byte-for-byte identical to stage_bundle but routes directly to re_test (L718), bypassing route_pr_or_local entirely. stage_bundle → route_pr_or_local → (local: finalize_bundle | pr: compose_research_pr). re_stage_bundle → re_test, never passing through the local/pr branch. For pr mode this is harmless (re_test → re_push_research → finalize_bundle). But the routing asymmetry is load-bearing and hidden by the duplication. REQUIRES DECISION: Is the re_ path intentionally skipping route_pr_or_local because finalize_bundle is always reached via re_push_research in the review cycle, or is this a bug that bypasses local-mode export after re-generation?

[Trecek]

Investigated — this is intentional. By design: in the re-validation path the PR already exists; route_pr_or_local's sole purpose is to branch between PR creation vs direct finalize_bundle. re_stage_bundle→re_test is intentional — re_push_research.on_success routes to finalize_bundle which handles both output_mode values.

[Trecek]

[warning] tests: test_gitattributes_marks_mermaid_binary uses 'assert "mermaid" in content or "assets" in content'. This OR condition is too loose — it passes even if mermaid.min.js has no binary rule, as long as the word 'assets' appears anywhere. The check should require both a mermaid/JS reference AND the 'binary' attribute to appear together (e.g. use a regex to ensure they appear on the same line).

[Trecek]

Investigated — this is intentional. OR condition is intentional: test comment states 'The rule may use a glob (assets//*.js) or the explicit path — either form is valid'. .gitattributes has no mermaid token at all (uses assets//*.js glob). Changing to AND would break the test.

[Trecek]

[warning] tests: test_vis_lens_count_is_12 hard-codes the expected count as 12. If a new vis-lens skill is added without updating this constant, the test fails without a clear signal. Consider deriving the count from VIS_LENS_SLUGS defined in test_vis_lens_structural.py to keep the two in sync automatically.

[Trecek]

Investigated — this is intentional. Hardcoding 12 IS the regression guard design — consistent with test_arch_lens_count_is_13 and test_exp_lens_count_is_18. The live filesystem count (_count_vis_lens_skills()) compared to the sentinel is exactly the right pattern.

[Trecek]

[warning] tests: test_catalog_states_vis_lens_count_is_12 asserts '12' in text — a substring match. For a small number like 12, collision with other numeric context in the catalog is likely (e.g. '12 hooks'). Prefer a regex like r'12\s+vis-lens' or assert the exact expected sentence.

[Trecek]

Investigated — this is intentional. No ambiguous '12' in catalog.md: occurs only in vis-lens section header, prose, and table row. Same pattern used for '13' and '18' in test_catalog_states_arch_and_exp_lens_counts without issue.

[Trecek]

[warning] tests: Duplicate 'or' condition: 'assert "inputs.output_mode" in cmd or "inputs.output_mode" in cmd' — both operands are identical, making the right branch unreachable dead code. The intent was likely to check two distinct patterns (e.g. the raw key and the template form '${{ inputs.output_mode }}'). Fix to assert both distinct patterns.

[Trecek]

[warning] tests: test_finalize_bundle_pr_mode uses cmd.find('report.md') to establish rename_pos for ordering assertions, but 'report.md' appears multiple times in a typical finalize_bundle cmd (rename source AND the grep -vE exclusion). str.find() returns the first occurrence, which may not be the rename position, making the rename_pos < tar_pos assertion fragile. Use a more specific search string such as the full rename command fragment.

[Trecek]

AutoSkillit review found 22 blocking issues. See inline comments for details. (own-PR restriction: REQUEST_CHANGES converted to COMMENT)