cloudxy/book-plugin

book-workflow — Distill → Diagram → Audit → Release/Rework

Path Conventions (Read this first)

• Plugin root (= repository root) = two levels up from this SKILL.md file's directory (i.e., ../../ from skills/book-workflow/), denoted as $PLUGIN.
• Workspace = the user's current project root (cwd), denoted as $WS. Distillation artifacts (books/, .work/, tools/, .dsh/) all reside under $WS.
• Bridge/audit scripts are NOT inside the workspace; when calling them, you MUST pass --ws $WS, otherwise they cannot find the workspace root.
• Principle: audit first, compile later — Phase 5's compile only runs on bundles where all gate verdicts are green.

cangjie distillation (Phase 0-4) → SVG diagram (on demand) → Bridge (character-level source) → Four-gate audit → All-green compile delivery
        ▲                                                        │
        └────────────────── Rework (mapped by verdict) ◀── Red ────────────┘

Step 0 — Workspace Bootstrap (one time per workspace, idempotent)

python3 $PLUGIN/scripts/bootstrap.py $WS

It creates $WS/.venv (Python ≥3.10 + PyYAML + PyMuPDF), installs the dsh gate suite ($WS/tools/ and $WS/.dsh/), and checks for node (the diagram gate's svg-lint dependency; if missing, that gate verdicts as "not applicable"). All subsequent commands should use $WS/.venv/bin/python (hereafter denoted as $PY).

Phase One — Cangjie Distillation (Generation Side)

First, confirm the input: source text (path to PDF/EPUB/TXT/transcript — if no text, stop and ask the user, never distill from memory), book title + author + publication year, and usage intent (learning/reference → single; daily use/cross-book combination → pack).

Then read $PLUGIN/vendor/cangjie-skill/SKILL.md in full and strictly follow its instructions (RIA-TV++ five phases: Adler whole-book understanding → 5-way parallel extraction → triple verification → promotion gate → RIA++ capability cards → Zettelkasten → stress testing). This workflow requires:

• Artifacts go into $WS/books/<slug>/ (contains verified.md, candidates/, rejected/, .cangjie/capabilities/);
• Stop after Phase 4 (stress testing) and before Phase 5 (compile and deliver), then proceed to this workflow's diagram generation and audit;
• Preserve the entire audit trail, and update the checkpoint state (PIPELINE_STATE.md) after each phase.

Phase 1.5 — Diagram Generation (SVG, On Demand)

When a framework/process/computation capability card or DIGEST requires an illustration, first read $PLUGIN/vendor/svg-diagram/SKILL.md for the house rules then hand-draw the SVG (CJK font stack, five-group semantic color scheme, box height = font size × 3, spacing between boxes ≥25px, C/Q curve connections, draw correctly the first time). Placement:

Scenario	Location	Reference Method
Capability card diagram	$WS/books/<slug>/.cangjie/capabilities/resources/<cap-slug>.svg	Write the resource name in card body + declare resources: in the Bundle's capability
DIGEST/OVERVIEW diagram	$WS/books/<slug>/assets/<name>.svg	Relative path 

Self-check (errors must be zero):

node $PLUGIN/vendor/svg-diagram/tools/svg-lint/bin/svg-lint.mjs <diagram.svg>

Phase Two — Bridging (Character-Level Source Verification)

$PY $PLUGIN/bridge/cangjie_to_dsh.py --book-dir $WS/books/<slug> --source <original.txt|.md|.pdf> --task <slug> --ws $WS

This places the source text into $WS/.work/<task>/book_text.md (PDF auto-extracted — the audit anchor object is always the original book text), parses each capability card's R section citations and compares them character-by-character (after whitespace removal) against the original, creates stable pool IDs (CJ-NNN) and generates dsh-format pools and skill audit copies. Any citation mismatch ⇒ rc=1 red card, go back to Phase 1 to fix the R layer.

Phase Three — Four-Gate Audit (Verdict)

$PY $PLUGIN/bridge/run_audit.py --task <slug> --ws $WS

Runs in sequence: Evidence package constructor → G-66 pool coverage → G-67 anchor consistency → G-68 evidence closure → Diagram gate (SVG reference completeness + svg-lint compliance). Verdicts are appended to $WS/.work/<task>/audit-verdict.md (audit timeline).

Phase Four — Release or Rework

Verdict	Action
All green	Release → $PY $PLUGIN/vendor/cangjie-skill/scripts/cangjie.py compile --bundle $WS/books/<slug>/.cangjie/capabilities --out <user-confirmed installation target> --output auto
Bridge source red / G-67 red	Return to cangjie Phase 2 (fix R layer citations/date anchors), re-run bridge
G-66 red (selected items not in R layer)	Return to cangjie Phase 1/1.5 (re-capture candidates/recheck eliminations), re-run bridge
G-68 red (closure/drift)	First re-run the audit entry; if still red, inspect Phase 3/4 ID mapping
Diagram gate red	Fix the diagram or add references per house rules, re-run audit entry

Rework is normal, not failure — target the specific failing items given by the gates (which citation, which ID, which diagram), never redo the whole thing from scratch.

Judgment Criteria (Who Checks What)

• Source alignment: After whitespace removal, citations must be contiguous character-level substrings of the original text — prevents "cited but not in source".
• G-66: Citations of critical/high capabilities (marked by bridge as "overview") must fall within some card's R layer — prevents important units from being silently omitted.
• G-67: A "date × citation" pair in the same line must co-occur within a 400-character window in the original text — prevents misattributed temporal anchors.
• G-68: Every pool ID referenced by a skill must have a sha256 closure and the pool must not drift — prevents "reference to non-existent source / pool modified without rebuild".
• Diagram gate: Every referenced SVG must exist, all SVGs must pass lint error=0 — prevents broken links and bad diagrams.

Quality Red Lines

1. No original text = no distillation; citations ≤150 characters/segment (English ≤100 words).
2. Synthetic exercises must not impersonate real book examples; when A1 has no original book example, mark it truthfully.
3. Do not compile or install until audit is all green.
4. Rejected items (rejected/) must retain their reason; note significant gaps truthfully, do not falsely claim zero omissions.
5. Diagrams must be consistent with the text — if data changes, diagrams must change too; a diagram contradicting the text is worse than no diagram.
6. Copyright compliance is the user's responsibility based on the original book's license; this workflow only guarantees "criteria are executable and citations are verifiable".

Niche Position

• cangjie-skill (bundled at $PLUGIN/vendor/): Authoritative definition of distillation methodology and workflow.
• dsh-distillation-director (same): Authoritative implementation of the three-gate verdicts, zero API cost as local scripts.
• svg-diagram (same): House rules for diagram generation and lint.
• This skill only handles orchestration and verdict consolidation; upstream specifications follow the SKILL.md/README of the three vendors. In case of conflict, the vendor original takes precedence, and deviations are documented here.