@1aboveio/skills 1.0.3 → 1.0.5

package/skills/app-dev/pyspark/references/production-validation.md

@@ -1,9 +1,13 @@
 # Production Validation
 
 Playbook for workflow step 5: **canary → (optional) profile → write →
-reconciliation** on the cluster. Use a **small sample**, typically **one month**
-of source data. Bind canary and write to the same pinned snapshot. Local tests
-do not substitute.
+reconciliation** on the cluster. Start with a **small sample**, typically
+**one month** of source data. Bind each canary and its write to the same pinned
+snapshot. Local tests do not substitute. The sample is not a full-history
+execution batch size. Every backfill/rebuild uses the required
+[Adaptive Batching](adaptive-batching.md) plan: aggregate inventory, measured
+budgets, local wider-versus-smaller equivalence, and a bounded wider
+validate-only production canary before any authorized wider publication.
 
 ## Fail-Closed Admission
 
@@ -11,12 +15,16 @@ Do not launch until all applicable facts are recorded and valid:
 
 - exact commit/module hash;
 - production Spark, Python, Java, and table-format runtimes;
-- source snapshot or date boundary (the one-month sample);
+- immutable source pins and exact half-open output/history boundaries for the
+  small sample or planned execution batch;
 - scheduler pause/ownership state;
 - zero competing warehouse work;
 - explicit validate-only or write-enabled mode;
 - durable writable log and event-log destination;
-- restart/recovery plan for writes.
+- restart/recovery plan for writes;
+- for backfills/rebuilds, a pinned adaptive manifest with measured budgets,
+  verified remaining scope, and complete Hudi partition population, table/key/
+  operation/lock checks and single-writer admission.
 
 Classify existing processes and working-tree changes before touching them. Do
 not kill or overwrite another operator's work.
@@ -100,6 +108,17 @@ Prove the canary did not write:
 
 Do not add `.cache()` or `.persist()` to warm the canary.
 
+### Wider Execution Canary
+
+The small sample proves its scope, not an entire rebuild. Before widening a
+batch, require local wider == union-of-smaller equivalence on the same immutable
+sources, then a bounded wider validate-only canary through the complete
+production call path. It must exercise the proposed width and relevant volume,
+expansion, and hot-key shape within measured budgets. Apply the same requirements
+for zero blockers, explicit skip, zero output, and logs. Keep source
+pins, per-Activity-Date cutoffs, full identity, and partition population intact.
+Follow [Adaptive Batching](adaptive-batching.md) for shape coverage and receipts.
+
 ## 2. Profiling (optional)
 
 After the canary, profile when **either** the small-sample canary exceeds
@@ -110,16 +129,27 @@ After the canary, profile when **either** the small-sample canary exceeds
 ## 3. Write
 
 Write-enabled only after a successful canary and **explicit authorization**.
-Re-check admission. Publish the same pinned sample. Do not present canary time
-as write performance.
-
-If a write is cancelled, prove from logs/source that publication was not
-reached. YARN `KILLED` alone does not prove no commit occurred.
+Re-check admission. Publish the same pinned sample or execution batch proven
+by its own canary. Adaptive planning does not grant write authorization. Do not
+present canary time as write performance. A successful small validate-only
+sample does not require a sample write: the first authorized publication may be
+the wider batch after its own proof. If a sample has already been published,
+reconcile it and exclude compatible completed scope from remaining work without
+creating an incomplete partition replacement.
+
+On cancellation/interruption, stop the old controller from launching more work,
+inspect the existing Spark application/attempts and Hudi timeline, and reconcile
+any committed scope before retrying. YARN `KILLED` alone does not prove no
+commit occurred. Settle inflight or unknown publication state through supported
+recovery before resuming with one controller/writer. Follow the
+[recovery checklist](adaptive-batching.md#7-recover-an-interruption-before-retrying).
 
 ## 4. Reconciliation
 
 Independent cluster read of the published scope — not a reuse of canary
-aggregates. Follow [Reconciliation](reconciliation.md). Fail closed on mismatch.
+aggregates. Follow [Reconciliation](reconciliation.md). For wider writes retain
+monthly or finer full-key/preserved-column checks and manifest receipts. Fail
+closed on mismatch; committed but unreconciled scope is not completed work.
 
 ## Evidence And Ownership
 

package/skills/app-dev/pyspark/references/reconciliation.md

@@ -1,7 +1,9 @@
 # Reconciliation
 
-Cluster check after an authorized write in production validation. Use the **same
-one-month sample** as the canary. Local fixtures do not prove this.
+Cluster check after an authorized write in production validation. Use the same
+pinned source inputs and exact scope proven by that write's canary: the small
+sample or a separately proven wider execution batch. Local fixtures do not
+prove this. Every backfill/rebuild follows [Adaptive Batching](adaptive-batching.md).
 
 Independently read the published table or Hudi commit. Do not reuse canary
 aggregates. Fail closed on mismatch.
@@ -12,7 +14,7 @@ Against the canary metrics and the previous path/oracle:
 
 - row count and distinct identity count
 - schema and required columns
-- date/partition coverage of the sample
+- date/partition coverage of the published scope
 - write mode, commit success, and downstream readability
 - validation blockers still zero on the published scope
 
@@ -32,6 +34,29 @@ assert actual.exceptAll(expected).count() == 0
 Pin `source` to the same snapshot the writer used. Keep the previous
 implementation only as this oracle while parity is being proven.
 
+## Finer Checks Inside Wider Writes
+
+A quarterly/yearly commit does not reduce reconciliation to one total. Check
+monthly or finer subintervals, clipped to partial edges, for complete key sets,
+duplicate multiplicity, required values, preserved columns, and
+per-Activity-Date cutoffs. Independently read the actual Hudi publication instant and verify
+all replaced partitions contain their complete population, including unchanged
+entities. Check that out-of-scope partitions and previously reconciled work
+remain unchanged. Fail closed on any mismatch.
+
+Bind each receipt to the exact half-open scope, immutable source pins, code/
+module identity, destination, publication instant, and bidirectional parity
+results. Store receipts in the resumable manifest. Only reconciled scopes may
+be subtracted from remaining work, and only when their source/code/output
+contract matches the active campaign or explicit equivalence proves reuse.
+Changing the plan revision does not authorize mixing incompatible results.
+Keep old receipt identities immutable; block campaign completion and plan
+authorized rework for affected published scopes when compatibility is unproved.
+Commit success or a killed application alone is not completion. After an
+interruption, inspect Spark attempts and the Hudi
+timeline, including commits without receipts, before retrying. Follow the
+[recovery checklist](adaptive-batching.md#7-recover-an-interruption-before-retrying).
+
 ## Evidence
 
 Safe evidence: counts, distinct counts, null rates, min/max dates, hashes, and

package/skills/app-dev/pyspark/references/transformation-design.md

@@ -11,6 +11,26 @@ ordering, time boundaries, null/tombstone behavior, arithmetic, and required
 history. Performance work preserves this behavior unless the user explicitly
 approves a change.
 
+## Size Backfill Transformations By Expansion And Hot Keys
+
+For every backfill/rebuild, use the required
+[Adaptive Batching](adaptive-batching.md) plan rather than a fixed monthly loop.
+Measure complete output rows, distinct entities, required source history,
+temporal-join/explode expansion, maximum source/expanded rows per key, bytes,
+and runtime/resources. A small output does not bound intermediate work or
+whole-group memory. Derive workload-specific budgets; no universal row cap
+proves safety. Prefer the largest measured-safe contiguous year, quarter,
+month, or smaller interval inside semantic/source boundaries.
+
+Keep each Activity Date's cutoff independent of batch end. Smaller batches
+must still read required earlier history and reconstruct boundary state.
+Compare wider candidates with the union of smaller candidates on identical
+immutable inputs using full-row bidirectional `exceptAll`, complete identity,
+preserved columns, and literal cutoff assertions. Include dense hot keys and
+partial edges. If date splitting cannot bound a lifetime-history group, stop
+for an algorithm/design decision; do not hide that risk with smaller output
+counts, shuffle tuning, or concurrent writers.
+
 ## Choose The Shallowest Sufficient Mechanism
 
 Prefer, in order:

package/skills/app-dev/python-backend/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: python-backend
 description: "Python backend architecture for FastAPI, Tortoise ORM, Pydantic Settings, loguru, and uv. Also: uv.lock installs in CI/Docker via a proxy or mirror (`uv sync --frozen` bypasses it), slow uv installs on runners, relocking."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Python Backend Conventions

package/skills/app-dev/shadcn/SKILL.md

@@ -2,7 +2,7 @@
 name: shadcn
 description: "Add or debug shadcn/ui in a React/Next.js project: components.json, shadcn init/add, presets, registries, Tailwind styling, base/radix/aria composition, component fixes, and list-index pages — where the default is the DiceUI data table with filter/sort/pagination in the URL via nuqs, not a bare shadcn Table."
 allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # shadcn/ui

package/skills/app-dev/zod-v4/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: zod-v4
 description: Zod v4 schema conventions and v3 migration for errors, validators, objects, enums, records, and async parsing.
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Zod v3 to v4 Migration

package/skills/cicd/cloud-build/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cloud-build
 description: "Build or debug Cloud Build pipelines for Cloud Run: cloudbuild.yaml, triggers, Artifact Registry, builds, migrations, deploys, secrets, VPC, notifications. Use cloud-deploy for staged promotion. NOT for GitHub Actions PR checks (github-actions)."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Cloud Build Direct Deploy to Cloud Run

package/skills/cicd/cloud-debug/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cloud-debug
 description: "Debug Cloud Build or Deploy failures: builds, deployments, health checks, and pipeline errors. Inputs: service, build ID, region. NOT for GitHub Actions runs (github-actions) or runtime errors in a running service (app-debug)."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Cloud Build & Cloud Deploy Debug Skill

package/skills/cicd/cloud-deploy/SKILL.md

@@ -5,7 +5,7 @@ description: >
   CI/CD pipelines with staged promotion, verification gates, or GitFlow branching.
   Also use when debugging Cloud Deploy pipeline failures. NOT for simple single-container
   deploys — use cloud-build instead.
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Cloud Deploy + Skaffold + Kustomize for Cloud Run

package/skills/cicd/docker/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: docker
 description: Docker/Podman container architecture and build patterns. Read when designing or reviewing containerization, Dockerfile structure, multi-stage builds, PyPI mirror support, or docker-compose setup for Python/uv projects, and when a Dockerfile's dependency install misses the layer cache on every build (build args such as a commit SHA or version declared too early) or an image build is slow in CI.
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Docker Build Patterns

package/skills/cicd/github-actions/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: github-actions
 description: "Author, review, audit, profile, optimize, or debug GitHub Actions workflows (.github/workflows/*.yml): run-history audits, job and step timing, resource bottlenecks, before/after comparisons, conditional CI by changed path, the one required gate check, PR and merge-queue lanes, sharding, workers, caching, self-hosted runners, timeouts, concurrency, permissions and action pinning, post-deploy verification, npm publishing. Use for 'set up CI', 'CI is slow', 'profile CI', 'optimize our pipeline', 'audit CI for redundant or wasted jobs', 'why is this check stuck expected or never started', 'harden this workflow', or 'browser not found on the runner'. NOT for pushing, opening, or merging a PR, or writing CI conventions into CONTRIBUTING.md (github-flow), queue rules or a check unmet inside Mergify (mergify), Playwright config and specs (e2e-test), cloudbuild.yaml or Cloud Run deploys (cloud-build), or which gates a repo must prove (ensure-coverage)."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # GitHub Actions

package/skills/cicd/github-flow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: github-flow
 description: "Deliver a change after the commit: push, open a PR, wait for checks, and merge to main through the repo's flow (direct push, pull request, or merge queue). Use whenever you commit or finish a change, when CONTRIBUTING.md has a Delivery section, and for asks like 'commit this', 'push it', 'open a PR', 'ship it', 'land it', 'get it merged'. Also: declare a repo's delivery flow, or write the CI conventions and Delivery section into CONTRIBUTING.md on request. NOT for writing workflow YAML (github-actions), Mergify config or a stuck queued PR (mergify), cutting a release (resolve-release), or PRs that resolve-issues or rush-issues deliver."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # GitHub Flow

package/skills/cicd/google-cloud/SKILL.md

@@ -5,7 +5,7 @@ description: >
   project management. Use when configuring GCP resources, managing service
   accounts, setting up IAP access, configuring VPC networks, managing secrets,
   or debugging cloud infrastructure.
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Google Cloud Platform (GCP) Skill

package/skills/cicd/mergify/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: mergify
 description: "Mergify merge queue and stacked PRs (`mergify stack`): config, rules, queue status, delivery. Use whenever a merge queue or stack is involved, including plain asks ('watch #123 till it merges', 'where is #412 in the queue', 'push this stack'): `gh pr view`/`gh pr checks` cannot see a dequeue; use `mergify queue show` and the bundled watcher. Also: a hook saying 'use mergify stack push', a missing Change-Id; authoring or debugging `.mergify.yml`, queue rules, merge protections, batch size, the ruleset making merges queue-only; enqueue policy (`@mergifyio queue` vs `auto_merge_conditions`); a push dequeuing a queued PR; bypass actors; freezing a branch. Failures: a PR stuck, queued but never merging, or merged unqueued; CI green on GitHub but unmet in Mergify; a batch going red or bisecting; a queue check missing rather than failing. Outranks the vendor mergify-* skills. NOT for pushing a PR in a repo without stack hooks (github-flow), workflow YAML (github-actions), or GCP deploy pipelines (cloud-deploy)."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Mergify Merge Queue

package/skills/cicd/podman/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: podman
 description: "Debug, design, or fix Podman: rootless/rootful containers, pods, podman-compose, the socket and systemd services, Docker-compatible API (DOCKER_HOST/CONTAINER_HOST), networking, volumes, SELinux labels, Docker migration, and CI/SSH provisioning of rootless sockets (user lingering, XDG_RUNTIME_DIR). Covers FailedToOpenSocket and systemctl --user DBUS/XDG errors."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Podman Operations

package/skills/content/article-review/SKILL.md

@@ -6,7 +6,7 @@ description: >
   Use when a user shares an article, pastes article text, sends a URL, or asks to
   review, rate, critique, evaluate, 评价, 点评, 分析, or 看看 any article, post, or 文章.
   Default template is 公众号-支付行业.
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # 文章评审引擎

package/skills/content/article-to-image/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: article-to-image
 description: "Generate article cover images: WeChat banner/square (公众号封面), Xiaohongshu (小红书封面), LinkedIn banner, general wide. Brainstorms 4 visual directions from the article, then renders each format with correct aspect ratios and title-safe zones. Use when given an article and asked for covers, banners, or 出图."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Article-to-Image

package/skills/content/flowchart-svg/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: flowchart-svg
 description: Create polished flowcharts directly as SVG and export PNG copies. Use when asked to draw, design, render, or deliver process diagrams, architecture diagrams, consulting workflows, decision flows, swimlanes, or other flowcharts as image files, especially when final outputs must include .svg and .png versions.
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Flowchart SVG

package/skills/content/image-gen/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: image-gen
 description: Generate an image from a text prompt with OpenAI gpt-image-2 or Google Nano Banana (Gemini), saved to an image file. Use whenever the user asks to generate, create, make, draw, paint, render, or design an image, picture, illustration, photo, artwork, logo, icon, avatar, banner, hero image, thumbnail, poster, wallpaper, sticker, or concept art — including phrasings like "an image of X", "a picture of X", "show me what X would look like", or a request for a visual for a slide, blog post, README, or social post. Also triggers on Chinese phrasings such as 生成图片, 画一张图, 做一张海报, 设计一个 logo. NOT for charts or data visualizations (dataviz), flowcharts or architecture diagrams (flowchart-svg), or editing an existing image file.
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Image Generation

package/skills/content/mermaid/SKILL.md

@@ -2,7 +2,7 @@
 name: mermaid
 description: Create and edit Mermaid diagrams for architecture, API flows, database schemas, workflows, and data models.
 user-invocable: true
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Mermaid Diagram Creation

package/skills/content/wechat-article-writer/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wechat-article-writer
 description: "Write WeChat 公众号 articles in Chinese content styles — 踩坑型 (pitfall-story), 实操型 (how-to), 对比型 (comparison), 观察型 (industry insight) — in the account's house style from the nearest WRITING.md. Use for drafting from scratch, rewriting a draft, adapting source material into a publishable article, or picking the right style. NOT for business or technical documents (write-doc)."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # WeChat Article Writer (公众号写作)

package/skills/content/wechat-publisher/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wechat-publisher
 description: "Publish articles to a WeChat Official Account (公众号) via API: push Markdown to the draft box (or auto-publish with --publish), convert Markdown to WeChat HTML, upload images to the media library. Requires AppID + AppSecret + whitelisted server IP on a 认证订阅号/服务号. Consumes wechat-article-writer's Markdown."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # WeChat Publisher (公众号发布)

package/skills/content/wechat-search/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wechat-search
 description: "Search WeChat 公众号 articles via Sogou Weixin, or read/summarize an article from a mp.weixin.qq.com URL (读/分析/总结) — suggest proactively when such a URL appears. Use for Chinese WeChat content, industry reports, competitor or trending topics. Requires Chrome Browser Relay. NOT general web search (web_search)."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # WeChat Article Search & Reader (搜狗微信搜索)

package/skills/content/xai-search/SKILL.md

@@ -9,7 +9,7 @@ metadata:
         type: secret
         required: true
         description: xAI API key (get from console.x.ai)
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # xAI Search (X/Twitter + Web)

package/skills/core/distill-writing/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: distill-writing
 description: "Learn a house writing style from approved sample documents into the project's WRITING.md and writing/templates/, with evidence per rule, conflicts surfaced and manual edits kept. Use when given reference documents to learn from, or to set up or refresh the house style. NOT for writing a document (write-doc)."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Distill a writing style

package/skills/core/doc-to-md/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: doc-to-md
 description: "Convert documents (PDF, DOCX, PPTX, XLSX, images) to Markdown so agents can read them. Use as the preprocessing step whenever binary files need to enter agent context — contract review, compliance audit, document analysis, evidence review."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # doc-to-md

package/skills/core/editorial-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: editorial-review
 description: "Review a document or generated report for what it says (does the reader get the answer, is the argument sound, is anything unsupported, obvious or repeated), then fix the content. Use to review, tighten or clarify a doc or report, and as the review step of write-doc and the report skills. NOT for Chinese wording (polish-cn) or code review (better-review)."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Editorial review

package/skills/core/house-style/SKILL.md

@@ -3,7 +3,7 @@ name: house-style
 description: "Shared reference the writing skills read by path: WRITING.md lookup and precedence, template choice, gap markers, template shape, the bundled templates, and the default English and Chinese style guides. Never select or invoke it as a task."
 disable-model-invocation: true
 user-invocable: false
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # House style

package/skills/core/house-style/references/defaults.md

@@ -47,15 +47,26 @@ the table: "Owners and dates are to be agreed by `<who>`." Never write `[TBD: ow
 
 - **Headings**: sentence case, informative ("Disputes double after the price change", not
   "Analysis"). `#` once for the title; do not skip levels, unless WRITING.md or the template
-  records a house pattern that does (house evidence beats this default).
-- **Paragraphs**: two to five sentences. One line per paragraph in the source file; no hard wraps
-  inside a paragraph unless the project's files already wrap.
-- **Lists**: only for parallel items or steps. Numbered for sequences, bullets otherwise. Not for
-  reasoning that needs "because" and "so".
+  records a house pattern that does (house evidence beats this default). In longer content,
+  prefer a standalone heading for each section or numbered topic, with the body below it.
+  An inline heading can suit a compact note; do not turn every paragraph into a labeled item.
+- **Paragraphs**: use prose for explanation and connected actions. Break at a change of focus,
+  not at a fixed sentence count. A paragraph may be one sentence; do not pad it to meet a quota
+  or force an entire topic into one long paragraph. One line per paragraph in the source file;
+  no hard wraps inside a paragraph unless the project's files already wrap.
+- **Lists**: use them when readers need to identify distinct rules, conditions, options or steps
+  separately. Numbered for sequences, bullets otherwise. Keep reasoning and connected actions
+  in prose. Introduce a list with a complete sentence and put shared context or follow-up
+  explanation outside it. A section may mix prose and a list.
+- **Layout follows meaning**: choose paragraph and list breaks for the content, not for visual
+  symmetry. Do not add, split or merge points just to give every section the same count or
+  layout. Repeated formats are useful for genuinely comparable items and checklists. Preserve
+  the user's chosen structure during an edit unless the requested change requires otherwise.
 - **Tables**: when three or more items share the same attributes. Every column has a header; no
   empty cells (write `n/a` or `TBD`).
 - **Emphasis**: bold for the few words a skimming reader must see; no bold sentences in a row, no
-  italics for emphasis, no ALL CAPS.
+  italics for emphasis, no ALL CAPS. Avoid a bold label on every paragraph or bullet when the
+  text already makes the distinction clear.
 - **Code**: field names, endpoints, commands, file names and config keys in code font, exactly as
   the system spells them.
 - **Links and citations**: link the descriptive words, not "here". Cite a source after the claim it
@@ -64,3 +75,18 @@ the table: "Owners and dates are to be agreed by `<who>`." Never write `[TBD: ow
   than four steps or actors in mind. Every diagram has a sentence saying what it shows.
 - **Callouts**: a blockquote starting `**Note:**` or `**Warning:**` (`**注意：**`, `**警告：**`),
   only for an aside that would derail the paragraph.
+
+### Example: prose, a list, then prose
+
+Keep the purpose and follow-up in paragraphs; list only the items readers need to distinguish:
+
+> **Validate the alert rules**
+>
+> Test the following patterns before enabling automatic holds.
+>
+> - One payer sends repeated payments of the same amount.
+> - Several customers pay the same beneficiary.
+>
+> Review false positives before deciding which alerts should block payouts.
+
+A neighboring section may need only one paragraph. Do not give it a list to match this one.

package/skills/core/plain-language/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plain-language
-description: "Session mode: every reply and status line in plain language — lead with the point, everyday words, full sentences, no filler — in English or Chinese, until turned off. Use for /plain-language, \"plain language mode\", \"talk plainly\", \"说人话\", or when the user's instructions say to use plain-language. Turn off with \"/plain-language off\" or \"normal mode\". NOT for writing a document (write-doc) or reviewing one (editorial-review)."
-release-version: 0.40.0
+description: "Session mode: every reply and status line in plain language — lead with the point, everyday words, full sentences, no filler — in English or Chinese, until turned off. Enable by default when the project has an applicable WRITING.md, even without a slash command. Use /plain-language init to persist that project default and its agent loading instructions. Use for /plain-language, \"plain language mode\", \"talk plainly\", \"说人话\", or when the user's instructions say to use plain-language. Turn off with \"/plain-language off\" or \"normal mode\". NOT for writing a document (write-doc) or reviewing one (editorial-review)."
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Plain language
@@ -10,12 +10,95 @@ Write every reply in this style for the rest of the session, including status li
 summaries, until the user says `/plain-language off` or "normal mode". A switch to another
 reply style (such as caveman) also ends it.
 
-- Invoked with no other request: reply in one line that the mode is on. Otherwise do not
-  mention the mode; just answer in it.
+## Activation and session state
+
+At session start, look for an applicable `WRITING.md` from the current working directory:
+
+1. Walk upward one directory at a time. Use the first `WRITING.md`; do not merge guides.
+2. Include the nearest ancestor containing `.git` (file or directory), then stop there.
+   Without a `.git` ancestor, stop before the user's home directory or any directory above it.
+3. Do not search unrelated subdirectories. A candidate must be a readable file. Report an
+   unreadable, invalid, or uninspectable candidate instead of treating it as absent.
+
+Its presence enables this mode for the session; no special section or opt-in text is needed.
+With no applicable file, keep explicit activation as before; absence alone does not enable
+or disable the mode. These lookup rules are included here so a standalone installation works;
+`house-style` is not required. Do not initialize over an unreadable guide.
+
+An explicit user choice wins over automatic activation. `/plain-language off`, "normal mode",
+or choosing another reply style disables this mode for the rest of the session, even when
+`WRITING.md` exists. Enable it again only if the user asks. Reloading this skill or finding the
+file again must not undo that choice. After compaction, recover the session's latest explicit
+style choice before applying the file-based default.
+
+Keep ordinary on/off choices in session context only; do not edit project files or settings for
+them. Only `/plain-language init` (or an explicit request to save the project default) authorizes
+the setup below. A new session checks for `WRITING.md` again and does not inherit the previous
+session's off choice. Document deliverables still belong to `write-doc` or their owning writing
+skill; this mode governs replies and status lines.
+
+When explicitly enabled without an applicable `WRITING.md`, offer once per session:
+"Use `/plain-language init` to make this the project default." Do not interrupt the task with
+an approval question, repeat the offer on ordinary replies, or offer it after an off command.
+
+- Invoked with no other request: confirm that the mode is on; include the setup offer when it
+  applies. Otherwise do not announce the mode; just answer in it.
 - Invoked with `off`: reply in one line that the mode is off, and stop following this page.
 - Code, commands, file paths, identifiers, error text and commit messages stay exact.
 - Follow the section for the reply's language; a mixed reply follows both.
 
+## Persist the project default: `/plain-language init`
+
+The command authorizes project setup, not a global preference or a permanent on/off toggle.
+
+1. Set the setup scope to the nearest ancestor containing `.git` (file or directory), else
+   the current working directory. Find the applicable `WRITING.md` with the lookup above.
+   A guide outside the setup scope may be read, but does not authorize writes in its directory.
+   Place agent loading instructions beside an in-scope guide, else at the setup root.
+   Resolve all planned write targets before changing any file. Report unreadable files,
+   conflicting policy, broken links, or symlinks escaping the setup scope and stop setup
+   without changing files. Never edit a global agent file.
+
+2. Keep an existing guide unchanged. If none applies, create `WRITING.md` at the setup root.
+   Start with this minimal guide; do not invent a house style or document templates:
+
+   ```markdown
+   <!-- writing-md: 1 -->
+   # Writing guide
+
+   ## Agent replies
+   - Default: use the `plain-language` skill for chat replies and status updates. _(user)_
+   - A user-requested style change applies only to the current session. _(user)_
+   ```
+
+3. At the chosen loading-instruction directory, ensure `AGENTS.md` and every existing
+   `CLAUDE.md` entrypoint can reach the instruction below. Create `AGENTS.md` if missing.
+   For a regular file or a valid in-scope symlink, inspect the resolved file and add the
+   instruction unless it already contains an equivalent loader or loads a configured
+   `AGENTS.md`. This includes symlinks to distinct instruction files, not only a shared
+   `AGENTS.md` target. If `CLAUDE.md` is missing, create a relative symlink to `AGENTS.md`.
+   Preserve unrelated text and existing valid links. Edit a shared target only once, and
+   resolve links relative to each instruction file. Do not claim setup is complete while
+   an entrypoint is unresolved.
+
+   ```markdown
+   ## Reply style
+
+   At session start, if an applicable WRITING.md exists, load the `plain-language` skill
+   and enable it for replies and status updates. After compaction, reload the skill and
+   preserve the session's latest explicit style choice. An off command or another chosen
+   reply style lasts for this session; file detection must not turn it back on.
+   ```
+
+4. Successful init explicitly enables plain language for this session, even if the user
+   previously turned it off. Ordinary file detection or reloading still cannot override off.
+   Report the paths created, updated, or already configured and any inherited guide used.
+   Running init again should leave already-configured files unchanged. Do not change the
+   guide's document-writing rules or install skills as part of setup.
+
+The agent loading instruction makes the file-based default discoverable in future sessions;
+`WRITING.md` alone is not a runtime hook. This setup assumes `plain-language` is installed.
+
 ## Every reply
 
 - **Lead with the point.** The answer or recommendation first, then the reasons.

package/skills/core/polish-cn/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: polish-cn
 description: "Polish the Chinese wording of a finished document or report, with a script proving every number, date, identifier, link and protected term is unchanged; prefers a Chinese model and records which ran. Use for '中文润色' or as a report skill's last step. NOT for cutting or restructuring content (editorial-review) or translating (write-doc)."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Polish Chinese

package/skills/core/reg-parser/SKILL.md

@@ -2,7 +2,7 @@
 name: reg-parser
 version: 1.1.0
 description: "Parse regulatory/scheme documents into structured outputs: convert a regulation (AML, VARS, PCI-DSS, KYC, GDPR) into an audit-ready compliance checklist, or trace contract clauses to a mandate source. Suggest proactively when a regulation PDF accompanies a contract review or compliance task. NOT general summarization (doc-to-md), or writing the gap analysis or policy from the checklist (write-doc)."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # reg-parser

package/skills/core/terminology/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: terminology
 description: "Build and keep a project's TERMINOLOGY.md: the preferred term per concept in English, 简体 and 繁體, and the terms to avoid. Use to set it up from the project's documents, when the user settles or corrects a term, or when another writing skill needs the format. NOT for writing documents (write-doc) or the code domain model (domain-modeling)."
-release-version: 0.40.0
+release-version: 0.42.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Terminology