showcase-build
Compose a shareable, disclosure-safe, OFFLINE proof bundle of Seshat BI's committed readiness truth -- stages, evidence, blockers, approvals, next actions, metric lineage, a truthful badge/project card, and a four-category disclosure manifest -- for a maintainer or analyst to hand to a reviewer, stakeholder, or prospective contributor. Use when someone asks for a "shareable proof", a "showcase bundle", a "project card", or "something I can send to show what Seshat has governed here". This is a Product Module, artifact-writing: it READS the shipped Explorer projection (`build_explorer_projection`), the Passport (`seshat.passport`), and the disclosure scanner (`seshat.disclosure.scan_disclosure`), composes ONE offline HTML bundle, and STOPS. It recomputes NO readiness, defines NO new evidence schema, invents NO meaning, and grants NO approval. It is fail-closed: a disclosure finding over the FULL composed body blocks generation and writes nothing. Generation is local-only (`.seshat-output/`); publishing the bundle anywhere is a separate, explicit human action this skill never performs.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-11
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- showcase-build
- description
- Compose a shareable, disclosure-safe, OFFLINE proof bundle of Seshat BI's committed readiness truth -- stages, evidence, blockers, approvals, next actions, metric lineage, a truthful badge/project card, and a four-category disclosure manifest -- for a maintainer or analyst to hand to a reviewer, stakeholder, or prospective contributor. Use when someone asks for a "shareable proof", a "showcase bundle", a "project card", or "something I can send to show what Seshat has governed here". This is a Product Module, artifact-writing: it READS the shipped Explorer projection (`build_explorer_projection`), the Passport (`seshat.passport`), and the disclosure scanner (`seshat.disclosure.scan_disclosure`), composes ONE offline HTML bundle, and STOPS. It recomputes NO readiness, defines NO new evidence schema, invents NO meaning, and grants NO approval. It is fail-closed: a disclosure finding over the FULL composed body blocks generation and writes nothing. Generation is local-only (`.seshat-output/`); publishing the bundle anywhere is a separate, explicit human action this skill never performs.
03 SKILL.md 正文
showcase-build
- Roadmap feature / spec:
specs/127-showcase-build/(Shareable Seshat Proof / Showcase Bundle). - Authority category: Product Module /
artifact-writing(docs/architecture/product-modules.md). - Delivery shape: a read-only skill over a reusable library function
(
src/seshat/showcase/build.py), per the ratified Option B decision (docs/roadmap/decisions/cli-verbs-vs-skill-driven.md, 2026-07-07). No new top-level CLI verb is added --seshat.cli._DISPATCHhas noshowcasekey, and importingseshat.showcaseadds no network/driver import (mirrors the B1/B3 lazy-import guard).
A "shareable proof" is a single offline folder that answers "what has Seshat governed here, and can I trust it?" -- the readiness spine, the evidence, the blockers, the approvals, and the metric lineage together, a truthful badge (never a fabricated score), and a disclosure manifest stating exactly what is included, redacted, omitted, and unavailable. This skill is the COMPOSER: it fills the bundle from surfaces that already ship (the Explorer projection, the Passport, the disclosure scanner); it originates no readiness truth of its own.
Module contract (the filled F024 declaration)
- Authority category: Product Module
- Capability level:
artifact-writing(exactly one) - Product layer:
6(delivery/handoff rendering, sibling of the F013 handoff pack and the F026/F028 read-only lenses) - Owner: the analyst or maintainer requesting the proof
- Status: Authored
What it does (one line)
Composes the already-committed readiness projection, an evidence-derived badge, and a four-category disclosure manifest into one offline HTML bundle, running the fail-closed disclosure scan over the FULL composed body before ever writing a file.
Core Authority it READS
seshat.explorer.build.build_explorer_projection-- stages, evidence states (available/missing/deferred), blockers, approvals, next actions, metric lineage, and input-defect entries.seshat.passport(verify_passport) -- ONLY when two snapshot paths are supplied, to compute the optional before/after section.seshat.disclosure.scan_disclosure-- the shared fail-closed scanner, run over the full composed bundle body (not merely the base projection).seshat.cli.guards.resolve_local_output-- the contained-output guard.
Derived evidence it WRITES
- One offline HTML file (default
showcase/index.html) under the contained.seshat-output/root, plus any inlined/embedded sidecar content (nothing external is ever referenced).
Approved step it EXECUTES
- none. It composes and writes ONE local file, then STOPS. It runs no
seshat check/retail validateof its own, opens no database, and calls no Power BI execution adapter.
Forbidden operations
- MUST NOT recompute readiness, define a new evidence schema, or invent a new Explorer/Passport (FR-001/FR-002) -- it renders the existing ones.
- MUST NOT show any stage as
passwithout inspectable evidence (FR-003). - MUST NOT write outside the contained
.seshat-output/root (FR-006). - MUST NOT publish, upload, track users, or call any external network/API (FR-007/FR-008) -- every asset is inlined or a data URI.
- MUST NOT grant or imply any approval or publish sign-off (FR-011).
- MUST NOT express a percentage, grade, or any other fabricated confidence number anywhere in the badge, card, or manifest (FR-013, FR-026; hard rule #9).
- MUST NOT modify
src/seshat/explorer/assets/explorer.css/explorer.js, or any source readiness artifact (FR-025). - MUST NOT add a new top-level CLI verb (FR-005; ratified Option B).
How it handles a missing or unsafe input
- A missing artifact renders as missing; a malformed readiness file renders as an input defect; a deferred live check renders as unavailable -- never as a pass (FR-003; Principle V, stop-and-ask, never invent).
- A live disclosure finding (secret, DSN, PII value, or a residual absolute path that survives portability normalization) in the FULL composed body BLOCKS generation fail-closed: no partial or redacted file is written; the findings are printed (FR-009/FR-010).
- Two Passport snapshots that are not comparable (different
scope, differentschema_version, or fewer than two supplied) omit the before/after section gracefully with a truthful note -- never a fabricated delta (FR-020/FR-021).
Scope boundary (read first)
- Composes, never invents. Every fact in the bundle traces to the reused Explorer projection or a supplied Passport snapshot. A missing artifact is missing; a deferred live check is unavailable; a malformed file is an input defect. Nothing is inferred into a pass.
- Read-only over every source. Generating or browsing the bundle never
modifies a readiness status file, a database, or a Power BI model. After a
run,
git statusshows only new files under.seshat-output/(typically git-ignored). - Fail-closed disclosure, full body. The scan runs over tables, enriched lineage, approval receipts, the badge, the manifest, and any before/after content -- INCLUDING user-supplied snapshot content the base projection never saw. A blocking finding writes nothing.
- No fake confidence, ever. The badge states the highest CONTIGUOUS
passstage and the passed-stage count (e.g. "3/7 stages ready -- Gold: blocked"). It never states a percentage, a grade, or an invented score (hard rule #9). When no stage has passed, it states the truthful onboarding status, never an empty or celebratory claim. - Four-category manifest, no silent drops. Every composed item lands under exactly one of included / unavailable / omitted / redacted, each with a locator. "Redacted" names ONLY the composer's own by-design portability normalizations (an absolute path reduced to repo-relative, a private/internal URL stripped) -- never the suppression of a disclosure finding (those block, they are not redacted).
- Own shell, untouched Explorer. The bundle renders
showcase.css/showcase.js(its own assets); it never reads or editsexplorer.css/explorer.js. - Generation is not publication. Producing the bundle never grants a publish approval or PII sign-off. Sharing the file anywhere is a separate, explicit human action outside this skill.
- Generic. No worked-example specifics baked in;
retail_store_sales(docs/worked-examples/retail-store-sales.md) is a cited filled instance, never hard-coded (Principle VII). ASCII + UTF-8 no BOM for any text this skill's caller writes back into the repo (the skill itself only writes under.seshat-output/, which is not tracked).
Procedure (numbered; do not reorder)
- Resolve inputs. Workspace root (default
.); optional output path (must resolve inside.seshat-output/); optionalrtlrender mode; optional two Passport snapshot file paths for the before/after section. - Compose. Call
seshat.showcase.build.build_showcase_bundle(root, snapshots=...). This reads the Explorer projection, derives the badge and manifest, applies portability normalization (absolute path -> repo-relative; private URL stripped -- each listed under the manifest'sredactedcategory), and computes the optional comparison if two snapshots were supplied. - Disclosure gate. If
bundle["disclosure"]["status"] != "pass": STOP fail-closed. Print every finding (rule,locator,message). Write NOTHING. This is not a partial-write case -- no file appears. - Resolve the output path. Call
seshat.cli.guards.resolve_local_output(root, output). If the path escapes.seshat-output/, refuse and write nothing (FR-006). - Render and write. Call
seshat.showcase.build.render_showcase_html(bundle, repo=root, rtl=...)and write the result to the resolved path. - Report and STOP. Print the written path and this reminder verbatim: "This is a local offline snapshot generated from committed evidence only. Publishing it anywhere is a separate, explicit human action." Do not publish, upload, or record any approval. Any judgment call surfaced in the bundle (an unresolved assumption, a blocked gate, a retracted approval) is a stop-and-ask for the named human (Principle V) -- this skill only renders it.
Refusals
- Uncontained output path -- refuse before writing; nothing is written
outside
.seshat-output/. - Blocking disclosure finding -- refuse fail-closed; print the findings; write nothing (no partial/redacted bundle).
- A request to publish, upload, or otherwise distribute the bundle -- out of scope. This skill only writes a local file; publishing is the named human's separate, explicit action.
- A request for a numeric confidence/health/percent-ready score -- refuse; the badge/manifest already state the truthful stage-and-count summary (hard rule #9).
Honest-state rules (never invent, never silently resolve)
| Situation | What the skill does |
|---|---|
| No table has reached any stage (or the workspace has no onboarded table) | badge states the truthful onboarding status; never an empty or celebratory claim |
| A readiness file is malformed | rendered as an input defect in the table panel AND listed under the manifest's omitted category |
| A secret / DSN / PII value / residual absolute path is present anywhere in the composed body | generation blocks fail-closed; findings printed; nothing written |
| A metric contract is unreadable | rendered as an input-defect lineage node, never a valid metric |
| Two snapshots share scope but one is malformed or a different schema | treated as not comparable; the before/after section is omitted with a note |
| Only one snapshot (or none) is supplied | no before/after section; no fabricated delta |
See also
- The spec:
specs/127-showcase-build/spec.md,plan.md,data-model.md,contracts/showcase-contract.md,quickstart.md,research.md. - The library it composes:
src/seshat/showcase/build.py,src/seshat/showcase/badge.py,src/seshat/showcase/manifest.py,src/seshat/showcase/compare.py. - The reused shipped surfaces:
src/seshat/explorer/build.py,src/seshat/passport.py,src/seshat/disclosure.py,src/seshat/cli/guards.py. - The nearest sibling read-only lenses:
.claude/skills/readiness-viewer/(stage matrix),.claude/skills/evidence-pack-generator/(late-stage pack) -- this skill's delta is that it renders an OFFLINE, SHAREABLE, disclosure-scanned bundle with a badge and a manifest, not an in-repo markdown artifact. - The Option B ratification this delivery shape applies:
docs/roadmap/decisions/cli-verbs-vs-skill-driven.md. - A cited filled worked example:
docs/worked-examples/retail-store-sales.md.
04 同仓库更多 Skills
fake-skill
A fixture skill with declaring frontmatter, used as positive shipped evidence.
fake-skill
A fixture skill with declaring frontmatter, used as positive shipped evidence.
bare-skill-no-frontmatter
暂无简介
fake-skill
A fixture skill with declaring frontmatter, used as positive shipped evidence.
retail-kpi-knowledge
Retail KPI / metric-contract reasoning layer for BI agents in the Seshat BI project. Use when an agent must reason about the BUSINESS MEANING of a retail KPI before any implementation — defining a KPI in business terms, classifying additivity (fully/semi/non-additive), identifying grain, listing required source fields, resolving ambiguity (gross vs net, VAT, returns, cost method, same-store), choosing an MVP KPI pack, reviewing a metric contract for completeness, or preparing a clean handoff to an implementation layer. Also use it to classify KPI sufficiency or prepare an owner policy decision packet. This is a meaning/definition + review layer, not an executor: it does not write DAX/SQL/Python, grant readiness, approve policy, or design dashboards. See INDEX.md for live/planned routes; registry.yaml is the authoritative machine-readable inventory.
bi-sql-knowledge
SQL reasoning, validation, reconciliation, transformation, diagnostics, and anti-pattern knowledge layer for Seshat BI agents. Use when a task involves reasoning about source SQL: source profiling, table grain, keys & uniqueness, joins & fan-out amplification, aggregation correctness, COUNT/NULL semantics, deduplication, validation queries, reconciliation queries, silver/gold transformation logic, window/date-time analytics, SQL anti-patterns, or basic SQL performance reasoning, or interpretation of a supplied sanitized PostgreSQL JSON execution plan. The SQL counterpart to bi-dax-knowledge. It is a thinking & validation layer, not a database executor, runtime validator, dbt/Dagster project, or automatic tuning service.