AGENT SKILL

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
所属仓库
Kemetra/Seshat-BI
最近更新
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._DISPATCH has no showcase key, and importing seshat.showcase adds 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 validate of 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 pass without 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, different schema_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 status shows 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 pass stage 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 edits explorer.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)

  1. Resolve inputs. Workspace root (default .); optional output path (must resolve inside .seshat-output/); optional rtl render mode; optional two Passport snapshot file paths for the before/after section.
  2. 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's redacted category), and computes the optional comparison if two snapshots were supplied.
  3. 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.
  4. 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).
  5. Render and write. Call seshat.showcase.build.render_showcase_html(bundle, repo=root, rtl=...) and write the result to the resolved path.
  6. 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

Kemetra
Kemetra/Seshat-BI

fake-skill

A fixture skill with declaring frontmatter, used as positive shipped evidence.

★ 2
Kemetra
Kemetra/Seshat-BI

fake-skill

A fixture skill with declaring frontmatter, used as positive shipped evidence.

★ 2
Kemetra
Kemetra/Seshat-BI

bare-skill-no-frontmatter

暂无简介

★ 2
Kemetra
Kemetra/Seshat-BI

fake-skill

A fixture skill with declaring frontmatter, used as positive shipped evidence.

★ 2
Kemetra
Kemetra/Seshat-BI

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.

★ 2
Kemetra
Kemetra/Seshat-BI

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.

★ 2