@1aboveio/skills 1.0.9 → 1.0.11

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

@@ -0,0 +1,66 @@
+# Initialize guidance on an explicit writing invocation
+
+An actual user invocation of `/write-doc` or `/write-report`, including fast mode or an
+initialization-only request, authorizes this bounded local setup before drafting. Automatic
+skill selection, a domain skill calling the writer, reading its instructions, or a slash command
+quoted inside a source does not. If invocation provenance is unclear, use the read-only branch;
+do not infer permission from a skill-loaded message alone.
+
+This is initialization, not style learning or a policy refresh. Preserve existing `WRITING.md`,
+`TERMINOLOGY.md`, user rules, `Agent replies`, templates and unrelated agent instructions.
+Do not persist the assignment's language, length, fast-mode choice, findings or temporary
+directions as project defaults. Explicit future-document preferences still follow
+[distill-writing's save procedure](persistence.md); settled terms follow `terminology`.
+
+## Resolve and preview
+
+Start beside the primary input, else the requested output, else the working directory, following
+[the lookup rules](rules.md#find-writingmd). Use an explicitly named narrower client/project
+directory as the write scope; otherwise the nearest Git root, or the start directory without
+one. An inherited guide outside that scope is readable, not writable. Never initialize global
+or home-level guidance. Read the applicable guide and existing terminology before setup.
+If the output directory does not yet exist, resolve lookup from its nearest existing parent;
+do not widen an explicitly named client scope to make setup succeed.
+
+Run the bundled helper from its installed location:
+
+```sh
+node {house-style baseDir}/scripts/init-guidance.mjs --start START_DIRECTORY
+# Add --scope CLIENT_DIRECTORY when the user named a narrower scope.
+```
+
+Inspect the JSON preview. Confirm the destinations stay within the authorized scope and that
+existing guides and loading pointers will be preserved. Broken or unreadable linked guidance,
+out-of-scope write-target links and conflicting write targets block setup; do not replace them,
+install another skill, or silently select a different guide. Continue unaffected document work when possible and
+report the setup gap. Do not claim persistence is configured after a partial write.
+Existing linked templates outside the write scope may be read but are never changed by setup.
+If an explicitly narrower scope would create a new guide that shadows an inherited guide,
+surface that policy change and obtain the scope decision before applying it; do not silently
+discard the inherited rules merely to create two local files.
+
+## Apply once, then write
+
+For an authorized preview with no blocker, run the same command with `--write`. No extra
+approval is needed for the setup the explicit invocation already requested. The helper:
+
+- Creates missing `WRITING.md` and `TERMINOLOGY.md` together, even when no project-specific
+  terms are known. A small terminology skeleton is valid here; it is not permission to invent
+  rows. Existing guide bytes remain unchanged.
+- Adds only the loading pointers needed in local `AGENTS.md` and supported `CLAUDE.md`
+  entrypoints. It preserves valid in-scope links and edits a shared target once; missing
+  `CLAUDE.md` becomes a relative link to `AGENTS.md`.
+- Reports files created, updated or already configured, the scope, inherited guidance and
+  any failure. Repeating setup with the same inputs makes no changes.
+
+Read the resulting local guidance and continue the requested task. With no writing assignment,
+finish by reporting setup rather than inventing a document. Do not initialize templates or learn
+a style from unapproved documents. The minimal guide contains no inferred house style; bundled
+defaults fill gaps until the user saves preferences or supplies approved samples.
+When an assignment continues after setup, include the created or updated guidance and loader
+paths in its delivery note, plus any unresolved setup issue. Mentioning which guide was used
+does not tell the user that setup also changed agent entrypoints.
+
+Fast mode does not skip explicit initialization. Conversely, automatic writing uses existing
+guidance or defaults without running this helper. Its existing, narrowly authorized terminology
+seeding and explicit-preference-save rules remain separate from initialization.

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

@@ -1,15 +1,19 @@
 # Save an explicit writing preference
 
-This is the explicit-save branch of `distill-writing`, also reached from `write-doc` and
+This is the explicit-save branch of `distill-writing`, also reached from `write-doc`, `write-report` and
 `plain-language`. It saves a stated preference, not a style inferred from examples. No sample
 documents, confidence inference or transfer draft are needed for this branch.
+Explicit writer initialization is a separate [bounded setup branch](initialization.md): it
+creates missing guidance and loading pointers, not new project preferences.
 
 ## Recognize intent and route
 
 Save when the user explicitly asks for reuse beyond the current task or session: "remember this
 for future PRDs", "make this our project's report default", or "save this writing rule". A skill
 invocation, an ordinary correction, repeated edits, a compliment, and "for this document" do not
-authorize persistence. Apply those to the current task only. "For this session" stays in session
+authorize saving a new preference. Apply those to the current task only. The writer's explicit
+slash invocation authorizes initialization, not persistence of its assignment settings.
+"For this session" stays in session
 context even if the user calls it a default. Ask once if a requested save's audience, duration or
 project scope cannot be determined; never assume a global preference.
 
@@ -61,7 +65,7 @@ do not save a rule that would weaken them. Explain the conflict instead.
   is unclear; do not save the rule to a different type or create an assessment template by guessing.
 - If a template is missing, start from the complete matching bundled template, not a fragment
   that would hide the bundled strategy under the replacement rule. For adaptable reports, use
-  the corresponding layout plus `write-doc`'s report contract to build the seven-section
+  the corresponding layout plus `write-report`'s report contract to build the seven-section
   [project-template shape](rules.md#template-shape), retaining all assessment checks. Apply only
   the stated preference and record the bundled source and release-version. Do not create a
   customizable VARS template. For a type without a bundled match, use the complete general
@@ -73,7 +77,8 @@ At the guide's in-scope directory, ensure `AGENTS.md` and every existing `CLAUDE
 can reach this instruction, adapted to the correct relative guide path:
 
 ```markdown
-For document drafting and editing, use `write-doc` and its nearest-WRITING.md lookup.
+For document drafting and editing, use `write-doc`; for analytical reports, use `write-report`.
+Follow their shared nearest-WRITING.md lookup.
 Read the applicable guide and its selected project template before writing. Save a preference
 only when explicitly asked; keep reply preferences separate from document rules.
 ```

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

@@ -17,6 +17,7 @@ reply-only `Agent replies` section. They link here; none restates it.
 - [Template shape](#template-shape)
 - [Who edits what](#who-edits-what)
 - [Explicit preference saves](persistence.md)
+- [Explicit writer initialization](initialization.md)
 
 ## Local files
 
@@ -30,6 +31,8 @@ project/
 ```
 
 Create files lazily: no empty `writing/` folder, no template without evidence for it.
+The explicit `/write-doc` or `/write-report` initialization branch creates both guidance files
+even without known local terms; it does not create invented terminology rows or a learned style.
 
 **WRITING.md's document sections hold what every document shares; a template holds what one type needs.**
 Example: "Write amounts as `USD 1,250,000`" goes in WRITING.md. "Put the price table before the
@@ -47,7 +50,8 @@ terms" goes in `writing/templates/commercial-proposal.md`.
    keep walking up, but never use a `WRITING.md` in the user's home directory or any directory
    above it.
 4. No `WRITING.md` found: write from the brief and the bundled
-   [defaults](defaults.md). Say so in the delivery note. Do not create one.
+   [defaults](defaults.md). Say so in the delivery note. Automatic selection does not create one.
+   An actual user slash invocation instead follows [initialization](initialization.md) first.
 
 A present but unreadable, invalid or uninspectable guide is not absent. Report its path
 and the problem; do not silently climb to a different guide or claim to apply defaults.
@@ -87,7 +91,7 @@ Example: the project has `writing/templates/prd.md`; the user asks for a PRD →
 file, not the bundled `prd.md`. The user says "use the bundled PRD template" → use the bundled one.
 
 Language is not a template choice. English, Chinese and bilingual output work with every template
-(`write-doc` [bilingual mode](../../write-doc/references/bilingual.md)).
+([bilingual mode](bilingual.md)).
 
 ## Resolve conflicting instructions
 
@@ -264,9 +268,12 @@ to regulatory action" is house text; for an internal-standard review, adapt it.
 
 ## Who edits what
 
-- `write-doc` automatically routes an explicit future-document save to `distill-writing`'s
+- `write-doc` and `write-report` automatically route an explicit future-document save to `distill-writing`'s
   [explicit-save branch](persistence.md). A correction without that intent affects the current
   document only; reading or using a guide does not authorize updating it.
+- Explicit user `/write-doc` or `/write-report` initializes missing local guidance and loading
+  pointers through [initialization](initialization.md). This bounded exception does not authorize
+  refreshing existing rules, learning a style, saving task-level settings or changing reply rules.
 - `distill-writing` updates them deliberately: it keeps `(user)` rules and manual edits, and lists
   every material change and conflict before or as it writes. It owns document guidance, not
   `Agent replies`. Both reader skills may recognize save intent; ownership follows the rule's
@@ -275,7 +282,7 @@ to regulatory action" is house text; for an internal-standard review, adapt it.
   loading pointers. It routes document preferences to `distill-writing`; ordinary mode toggles
   and session choices do not save policy. Mixed requests keep both scopes separate.
 - Any writing skill adds a row to TERMINOLOGY.md the moment the user settles a term, and creates
-  the file for the first one (`terminology` format). `write-doc` also seeds the file with
+  the file for the first one (`terminology` format). `write-doc` and `write-report` also seed the file with
   `proposed` rows when it writes a new document in a project without one. It never writes a term the user did not state
   or approve, except as `proposed`.
 - A user may edit any of these files by hand at any time; hand edits win over distilled rules.

package/skills/core/house-style/scripts/init-guidance.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const WRITING = '<!-- writing-md: 1 -->\n# Writing guide\n\nProject document preferences are not yet saved; bundled defaults apply.\n\n## Terms\n\nTerms: see [TERMINOLOGY.md](TERMINOLOGY.md).\n';
+const TERMS = '# Terminology\n\n## Terms\n\n| Concept | English | 简体 | 繁體 | Avoid | Meaning | Status | Source |\n| --- | --- | --- | --- | --- | --- | --- | --- |\n';
+const LOADER = '## Document guidance\n\nFor document drafting and editing, use `write-doc`; for analytical reports, use `write-report`. Read the applicable `WRITING.md` and `TERMINOLOGY.md`. Save future preferences only when explicitly requested; automatic skill selection does not initialize guidance.\n';
+const inside = (root, p) => p === root || (!path.relative(root, p).startsWith('..' + path.sep) && path.relative(root, p) !== '..' && !path.isAbsolute(path.relative(root, p)));
+const home = fs.realpathSync(os.homedir());
+const result = { scope: null, start: null, projectBoundary: null, inherited: null, missingInputs: [], files: [], errors: [] };
+let scope;
+let globalRoots = [];
+const completed = new Set();
+function fail(message, file) { const e = new Error(message); e.file = file; throw e; }
+function checkGlobal(real, file) {
+  if (globalRoots.some(root => inside(root, real))) fail('Global agent configuration is not an authorized write target', file);
+}
+function inspect(p, bounded = false) {
+  let lst;
+  try { lst = fs.lstatSync(p); } catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+  let real;
+  try { real = fs.realpathSync(p); } catch { fail('Broken or inaccessible link', p); }
+  if (bounded && !inside(scope, real)) fail('Target escapes authorized scope', p);
+  if (bounded) checkGlobal(real, p);
+  const stat = fs.statSync(real);
+  if (!stat.isFile() || !(stat.mode & 0o444)) fail('Expected a readable regular file', p);
+  let bytes;
+  try { bytes = fs.readFileSync(real); } catch { fail('File is unreadable', p); }
+  if (bytes.includes(0)) fail('Invalid text guidance', p);
+  try { new TextDecoder('utf-8', { fatal: true }).decode(bytes); }
+  catch { fail('Invalid UTF-8 guidance', p); }
+  return { real, bytes, link: lst.isSymbolicLink(), dev: stat.dev, ino: stat.ino, nlink: stat.nlink };
+}
+const sameFile = (a, b) => a && b && a.dev === b.dev && a.ino === b.ino;
+function hasLoader(text) {
+  return text.includes(LOADER.trim()) || /for document drafting and editing, use `?write-doc`?; for analytical reports, use `?write-report`?\.\s*read the applicable `?WRITING\.md`? and `?TERMINOLOGY\.md`?\.\s*save future preferences only when explicitly requested; automatic skill selection does not initialize guidance\./i.test(text);
+}
+function checkConflict(text, file) {
+  // Deliberately bounded: catch direct negations, not arbitrary natural-language policy.
+  if (/(?:\b(?:do not|don't|never|must not|cannot|can't)\s+(?:(?:ever|automatically)\s+)?(?:use|invoke|run|read|load|follow|consult|import|initialize|create)\b[^.\n]*(?:write-doc|write-report|WRITING\.md|TERMINOLOGY\.md|AGENTS\.md|CLAUDE\.md)|(?:explicit|automatic)[^.\n]*(?:invocations?|selection)[^.\n]*(?:disabled|prohibited))/i.test(text)) fail('Conflicting document guidance', file);
+}
+// Bounded inline Markdown destinations: angle destinations may contain spaces; bare
+// destinations may have a quoted title. This is not a full CommonMark parser.
+function destination(raw, file) {
+  const m = raw.trim().match(/^(?:<([^<>]*)>|([^\s]+))(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*$/);
+  if (!m) return null;
+  let ref = (m[1] ?? m[2]).split('#')[0].split('?')[0];
+  if (!ref || /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(ref)) return null;
+  try { ref = decodeURIComponent(ref); } catch { fail('Invalid link encoding', file); }
+  return ref;
+}
+function loadsAgents(text, file, expected, agent) {
+  function validate(ref) {
+    const target = ref && path.resolve(path.dirname(file), ref);
+    const linked = target && inspect(target);
+    const reaches = agent ? sameFile(linked, agent) : !linked && target === expected;
+    if (!reaches) fail('Misdirected AGENTS.md loader', file);
+  }
+  const inline = /(?:read|load|follow|see|consult|import)\s+(?:the\s+)?\[([^\]]*AGENTS\.md[^\]]*)\]\((<[^>]*>|[^)]+)\)/gi;
+  let found = false;
+  for (const m of text.matchAll(inline)) {
+    const ref = destination(m[2], file);
+    validate(ref);
+    found = true;
+  }
+  // Do not let a Markdown label masquerade as a plain-text reference.
+  const plain = /(?:read|load|follow|see|consult|import|@)\s*(?:the\s+)?`?((?:[^\s`<>()[\]]+\/)?AGENTS\.md)`?(?=$|[\s.,;:])/gi;
+  for (const m of text.replace(inline, '').matchAll(plain)) {
+    validate(m[1]);
+    found = true;
+  }
+  return found;
+}
+function validateLinks(file, info, allowedMissing, seen = new Set(), entrypoint = false) {
+  if (seen.has(info.real)) return;
+  seen.add(info.real);
+  const text = info.bytes.toString('utf8');
+  // Inspect local Markdown guidance links and inline project template paths.
+  const links = [...text.matchAll(/\]\(([^)]+)\)|`([^`]*(?:writing\/templates\/|TERMINOLOGY\.md)[^`]*)`/g)];
+  for (const m of links) {
+    // Entrypoint loaders name the applicable glossary, not a sibling-file link.
+    if (entrypoint && m[2] && !m[2].includes('writing/templates/')) continue;
+    const ref = destination(m[1] || m[2], file);
+    if (!ref) continue;
+    const target = path.resolve(path.dirname(info.real), ref);
+    if (!/\.md$/i.test(target)) continue;
+    if (entrypoint && !/(?:^|\/)(?:AGENTS|WRITING|TERMINOLOGY)\.md$/i.test(ref) && !/(?:^|\/)writing\/templates\//i.test(ref)) continue;
+    const linked = inspect(target);
+    const planned = allowedMissing instanceof Set ? allowedMissing.has(target) : target === allowedMissing;
+    if (!linked && !planned) { result.missingInputs.push(target); fail('Linked guidance is missing', target); }
+    if (linked) validateLinks(target, linked, allowedMissing, seen,
+      entrypoint && /(?:^|\/)(?:AGENTS|CLAUDE)\.md$/i.test(target));
+  }
+}
+function parse() {
+  const args = process.argv.slice(2); let start, explicit, write = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--write') { if (write) fail('Duplicate --write'); write = true; }
+    else if (args[i] === '--start' || args[i] === '--scope') {
+      const flag = args[i]; if (!args[i + 1] || args[i + 1].startsWith('--')) fail(`Missing value for ${flag}`);
+      if (flag === '--start') { if (start) fail('Duplicate --start'); start = args[++i]; }
+      else { if (explicit) fail('Duplicate --scope'); explicit = args[++i]; }
+    } else fail(`Unknown argument: ${args[i]}`);
+  }
+  if (!start) fail('Missing --start');
+  start = fs.realpathSync(path.resolve(start));
+  if (!fs.statSync(start).isDirectory()) fail('Start must be a directory', start);
+  let boundary = null;
+  for (let d = start;; d = path.dirname(d)) {
+    if (fs.existsSync(path.join(d, '.git'))) { boundary = d; break; }
+    if (d === home || d === path.dirname(d)) break;
+  }
+  scope = explicit ? fs.realpathSync(path.resolve(explicit)) : boundary || start;
+  if (!fs.statSync(scope).isDirectory() || !inside(scope, start)) fail('Scope must contain start', scope);
+  if (boundary && !inside(boundary, scope)) fail('Scope must be within the project boundary', scope);
+  if (inside(scope, home)) fail('Home and its ancestors are not authorized scopes', scope);
+  // Global configuration roots may themselves be links into this checkout.
+  const globalNames = ['.pi', '.agents', '.claude', '.codex', '.config/pi', '.config/claude', '.config/codex', '.config/agents', '.config/opencode', '.config/amp', '.config/cursor', '.config/github-copilot'];
+  for (const name of globalNames) {
+    const p = path.join(home, name);
+    let real;
+    try { real = fs.realpathSync(p); } catch (e) { if (e.code !== 'ENOENT') throw e; continue; }
+    globalRoots.push(real);
+  }
+  checkGlobal(scope, scope);
+  checkGlobal(start, start);
+  result.scope = scope; result.start = start; result.projectBoundary = boundary; result.write = write;
+  return { start, boundary, write };
+}
+function main() {
+  const { start, boundary, write } = parse();
+  let guide = null;
+  for (let d = start;; d = path.dirname(d)) {
+    if (d === home || d === path.dirname(d)) break;
+    const p = path.join(d, 'WRITING.md'); const item = inspect(p);
+    if (item) { guide = { path: p, ...item }; break; }
+    if (d === boundary) break;
+  }
+  const localGuide = guide && inside(scope, guide.path) && inside(scope, guide.real);
+  if (guide && inside(scope, guide.path) && !inside(scope, guide.real)) fail('Guide escapes authorized scope', guide.path);
+  const dir = localGuide ? path.dirname(guide.path) : scope;
+  if (guide && !localGuide) result.inherited = guide.path;
+  const wp = path.join(dir, 'WRITING.md'); const tp = path.join(dir, 'TERMINOLOGY.md');
+  const ap = path.join(dir, 'AGENTS.md'); const cp = path.join(dir, 'CLAUDE.md');
+  const entries = new Map();
+  for (const p of [wp, tp, ap, cp]) entries.set(p, inspect(p, true));
+  if (guide) validateLinks(guide.path, guide, localGuide ? tp : null);
+  const existingTerm = entries.get(tp);
+  if (existingTerm) validateLinks(tp, existingTerm, null);
+  for (const [i, policy] of [wp, tp].entries()) for (const other of [wp, tp, ap, cp].slice(i + 1)) {
+    if (sameFile(entries.get(policy), entries.get(other))) fail('Guidance files or agent entrypoints share a target', other);
+  }
+  for (const p of [wp, tp, ap, cp]) {
+    const item = entries.get(p);
+    if (item) {
+      // A hard link not represented by a target may name an external file.
+      const names = new Set([...entries.values()].filter(other => sameFile(item, other)).map(other => other.real));
+      if (item.nlink > names.size) fail('Target has unaccounted hard links', p);
+    }
+  }
+  const plan = [];
+  function record(p, action, content, item = entries.get(p)) {
+    result.files.push({ path: p, status: action === 'none' ? 'already configured' : action === 'append' ? 'updated' : 'created' });
+    if (action !== 'none') plan.push({ p, action, content, item });
+  }
+  record(wp, entries.get(wp) ? 'none' : 'create', WRITING);
+  record(tp, existingTerm ? 'none' : 'create', TERMS);
+  const agent = entries.get(ap), claude = entries.get(cp);
+  const agentText = agent?.bytes.toString('utf8') || '';
+  checkConflict(agentText, ap);
+  const agentConfigured = hasLoader(agentText);
+  function appendText(text) { const nl = text.includes('\r\n') ? '\r\n' : '\n'; return (text && !text.endsWith('\n') ? nl : '') + (text ? nl : '') + LOADER.replaceAll('\n', nl); }
+  record(ap, agentConfigured ? 'none' : agent ? 'append' : 'create', agent ? appendText(agentText) : LOADER);
+  const same = sameFile(agent, claude);
+  const claudeText = claude?.bytes.toString('utf8') || '';
+  checkConflict(claudeText, cp);
+  const referencesAgents = loadsAgents(claudeText, claude?.real || cp, ap, agent);
+  const claudeConfigured = same || hasLoader(claudeText) || referencesAgents;
+  const plannedGuidance = new Set([wp, tp, ap]);
+  if (agent) validateLinks(ap, agent, plannedGuidance, new Set(), true);
+  if (claude && !same) validateLinks(cp, claude, plannedGuidance, new Set(), true);
+  record(cp, !claude ? 'symlink' : claudeConfigured ? 'none' : 'append', !claude ? 'AGENTS.md' : appendText(claudeText));
+  // Reinspect every target and inherited input before starting writes.
+  for (const [p, old] of entries) {
+    const now = inspect(p, true);
+    if (!!old !== !!now || (old && (old.real !== now.real || !sameFile(old, now) || !old.bytes.equals(now.bytes) || old.link !== now.link))) fail('Target changed during preflight', p);
+  }
+  if (guide && !localGuide) {
+    const now = inspect(guide.path); if (!now || now.real !== guide.real || !sameFile(now, guide) || !now.bytes.equals(guide.bytes)) fail('Inherited guide changed during preflight', guide.path);
+  }
+  if (write) for (const step of plan) {
+    try { fs.accessSync(step.action === 'append' ? step.item.real : path.dirname(step.p), fs.constants.W_OK); }
+    catch { fail('Write target is not writable', step.p); }
+  }
+  if (write) for (const step of plan) {
+    if (step.action === 'create') fs.writeFileSync(step.p, step.content, { flag: 'wx' });
+    else if (step.action === 'symlink') fs.symlinkSync(step.content, step.p);
+    else {
+      const now = inspect(step.p, true);
+      if (!now || now.real !== step.item.real || !sameFile(now, step.item) || !now.bytes.equals(step.item.bytes)) fail('Target changed before update', step.p);
+      fs.appendFileSync(now.real, step.content);
+    }
+    completed.add(step.p);
+  }
+}
+try { main(); } catch (e) {
+  result.errors.push({ path: e.file || null, message: e.message });
+  if (e.file && !result.files.some(f => f.path === e.file)) result.files.push({ path: e.file, status: 'blocked' });
+  for (const f of result.files) if (f.status !== 'already configured' && !completed.has(f.path)) f.status = 'blocked';
+  process.exitCode = 1;
+}
+console.log(JSON.stringify(result, null, 2));

package/skills/core/house-style/templates/analytical-report.md

@@ -0,0 +1,54 @@
+# Analytical report
+
+## Use when
+A decision-maker needs the results of data analysis, research or an investigation and their
+implications. Adapt depth to the question, not the amount of source material.
+- Pick a domain-specific report template when the producing skill names one.
+- Pick a compliance report layout when reporting a compliance assessment.
+- Pick a document template instead when defining requirements, policy or a proposed solution.
+
+## Tone
+Direct and evidence-led; explain technical detail only as far as the reader needs it.
+
+## Inputs
+- Reader, question and intended decision. Material: ask once, else narrow the scope.
+- Source analysis, data or research with provenance. Material: ask once, else narrow the scope.
+- Scope, period, population, units, methods and limitations. Material: mark [TBD] or narrow the scope.
+- Comparison baseline, if supplied. Without one, omit trend and improvement claims.
+- Proposed actions or constraints, if supplied. Do not invent commitments.
+
+## Reasoning
+1. Read [analytical reporting](../references/analytical-reporting.md) and its required writing-pattern
+   and definition references. Privately identify each section's reader question, supported point,
+   necessary evidence and material limit. Establish what the sources can answer and where their coverage ends.
+2. Reconcile measurements and distinguish observations from interpretations and hypotheses.
+3. Connect each finding to the reader's question and explain material uncertainty.
+4. Derive proportionate recommendations without presenting forecasts as measured results.
+
+## Sections
+1. **Summary** (Required): answer the question, state the main findings and material limits.
+2. **Scope and method** (Required): sources, period, population, definitions and exclusions.
+   Keep the orienting scope near the findings; detailed procedures may be linked or collapsed.
+3. **Findings** (Required): organize by the questions that matter; each analytical section makes
+   a supported point with the evidence needed to establish it. A topic heading alone is not enough.
+4. **Implications and limitations** (Required): explain what follows and what remains unproven.
+   Put limits beside the findings they qualify or in one shared note when appropriate. A separate
+   chapter is not required; do not repeat the same qualifications merely to fill this outline.
+5. **Recommendations and decisions** (Required when action is requested or supported): tie each
+   action to a finding; distinguish proposals from agreed commitments.
+6. **Sources and supporting detail** (Required): provide traceable references; keep bulky tables
+   and methods here or in linked appendices. Inline citations may replace a separate source list.
+
+## Done when
+- Does the summary answer the reader's question without overstating certainty?
+- Can a reader identify the supported point, evidence and material limit of each analytical section?
+- Are definitions direct, with essential metric conditions separate from processing and coverage notes?
+- Have repeated defensive claims and execution narration been removed without losing material information?
+- Can every material claim and calculation be traced to its inputs?
+- Do totals, rates, charts and tables agree on population, units, period and exclusions?
+- Are comparisons valid and causal claims supported rather than inferred from correlation?
+- Are missing data, scope limits and conflicting sources visible where they affect conclusions?
+- Are recommendations supported, with proposed commitments clearly distinguished?
+
+## Sources
+First-party analytical reporting contract; domain-specific methods remain with their owning skills.

package/skills/core/house-style/templates/gap-analysis.md

@@ -18,7 +18,7 @@ The baseline can be a regulation or scheme rule (compliance), a risk appetite or
 - Pick the `compliance-audit` skill to run the audit itself against a checklist (tracker and
   evidence); use this template to write up its result.
 - An audit report built from completed audit findings for a regulator or board belongs to the
-  `write-doc`'s compliance-report workflow, not this template.
+  `write-report` compliance-report workflow, not this template.
 
 ## Tone
 

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. Enable by default when the project has an applicable WRITING.md, even without a slash command. Use for /plain-language, 'talk plainly', '说人话', and explicit requests to remember project reply preferences; /plain-language init persists the default and loading instructions. Save reply rules only under Agent replies; route document preferences to distill-writing. Ordinary mode toggles remain session-only. Turn off with '/plain-language off' or 'normal mode'. NOT for writing a document (write-doc) or reviewing one (editorial-review)."
-release-version: 0.44.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 for /plain-language, 'talk plainly', '说人话', and explicit requests to remember project reply preferences; /plain-language init persists the default and loading instructions. Save reply rules only under Agent replies; route document preferences to distill-writing. Ordinary mode toggles remain session-only. Turn off with '/plain-language off' or 'normal mode'. NOT for writing a document (write-doc) or analytical report (write-report) or reviewing one (editorial-review)."
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Plain language

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.44.0
+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 or write-report)."
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Polish Chinese
@@ -21,6 +21,13 @@ result; then the script applies it.
 **Wording only.** Never add, cut or move content. A cut or a restructure is an `editorial-review`
 finding. Example: "0 笔销售未能匹配" reads as obvious → leave it, and report it for editorial review.
 
+A point-free section, repeated defensive claims or a definition overloaded with methods is a
+content problem, not a reason to expand or polish the passage. Return it to the editorial owner;
+for review-only or wording-only scope, report the issue without broadening the authorized edit.
+If `house-style` is installed, read its [definitions and metrics](../house-style/references/definitions-and-metrics.md)
+and use the distinction when reporting issues. Do not claim those structural issues were fixed
+by passing token checks. Content changes require renewed polishing of the changed blocks.
+
 **Actually edit.** Ask the model to review every block and rewrite each one the brief's patterns
 match. A pass that keeps most blocks of a rough draft is weak, not clean: check the kept blocks
 against the patterns yourself. Example: "进行进一步的核查工作" kept as natural → send it back

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

@@ -1,8 +1,8 @@
 ---
 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.44.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), writing a gap-analysis report (write-report), or writing a policy from the checklist (write-doc)."
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # reg-parser
@@ -166,7 +166,7 @@ The optional `--source` flag enables three semantic warnings (advisory, never bl
 
 ### JSON dump for downstream consumers
 
-Markdown is the authored source of truth — humans read and review it, GitHub renders it, and authors edit it directly. Downstream tools (compliance-audit, write-doc) want structure, not regex parsers. Generate a JSON view of any checklist with:
+Markdown is the authored source of truth — humans read and review it, GitHub renders it, and authors edit it directly. Downstream tools (compliance-audit, write-report, write-doc) want structure, not regex parsers. Generate a JSON view of any checklist with:
 
 ```bash
 python3 {baseDir}/scripts/dump_checklist.py <checklist.md> --out <out.json>

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.44.0
+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 analytical reports (write-report) or the code domain model (domain-modeling)."
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Terminology
@@ -19,7 +19,11 @@ which words to avoid. Every writing skill reads it; `polish-cn` checks rewrites
 
 **One file, beside WRITING.md.** Put `TERMINOLOGY.md` in the folder of the WRITING.md that applies
 ([lookup](../house-style/references/rules.md#find-writingmd)), else the repository root. Create it
-when the first term is settled, or when `write-doc` seeds it before a first document. Never write CONTEXT.md; that file belongs to
+when the first term is settled, or when `write-doc` or `write-report` seeds it before a first document.
+An explicit user invocation of either writer also initializes a minimal file through the
+[writer setup branch](../house-style/references/initialization.md), even when no term rows are
+known. Automatic writer selection does not invoke that setup; no placeholder concept or
+unapproved `user` row is added to fill the file. Never write CONTEXT.md; that file belongs to
 `domain-modeling`.
 
 **Only this project's terms.** A row is a concept the project's readers meet and that is
@@ -52,7 +56,7 @@ variants, ask once about the conflicts, write the file, and move any term rows o
 ## During other work
 
 Any writing skill that meets a term decision records it here in the [format](references/format.md),
-with status `user, <date>`: `write-doc`, `editorial-review`, `polish-cn`, `distill-writing`, and the
+with status `user, <date>`: `write-doc`, `write-report`, `editorial-review`, `polish-cn`, `distill-writing`, and the
 report skills. Each reads `TERMINOLOGY.md` before writing, and prefers its rows over the bundled
 common list.