@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/core/editorial-review/references/checklist.md

@@ -0,0 +1,94 @@
+# Checklist
+
+The core checks for every document. Run them alongside the reader test and the template's
+`Done when`, against the same version. Write every finding down before fixing any.
+
+## Contents
+
+- [Facts](#facts)
+- [Argument](#argument)
+- [Cut](#cut)
+- [House style](#house-style)
+- [Language](#language)
+
+## Facts
+
+- Every name, number, date, obligation and claim traces to the brief, a source or a computed result.
+- Nothing came from a template example, WRITING.md example or an earlier document.
+- Each number keeps its period, denominator and unit where it is stated. Example: "approval rate
+  62.40%" → of which attempts, in which window.
+- Each gap uses the [gap markers](../../house-style/references/rules.md#gap-markers) and is listed
+  in the delivery note. No other placeholder remains: search for `{{`, `[Name]`, `XX`, `____`,
+  `lorem`, and bare `TBD` outside a table cell under a sentence naming who will agree it.
+- Uncertainty that changes a decision is stated where the claim is made, with what it depends on.
+- A period that runs past the data's cut-off or today's date is marked as partial. Example: an
+  "October" report written on 20 October → "1–19 October".
+- Every link and image target exists. Example: `[方法说明](methodology.zh.md)` with no such file →
+  a finding.
+- A hypothesis stays a hypothesis. Example: "payment-pattern names are inferred" → never "the
+  merchant runs a top-up business".
+
+## Argument
+
+- The first paragraph gives the answer or the purpose, not the background.
+- A reader who was not in the analysis can follow the conclusion. Example: "C1 is high priority
+  because of a 2x ladder at 100% single-country concentration" → name what a 2x ladder is, or say
+  what it means for the reader.
+- Each section relies only on what the reader knows or an earlier section established.
+- Each policy, rule or definition appears once; other places refer to it.
+- Facts, assumptions, analysis and recommendations are distinguishable.
+- The template's `Done when` questions all answer yes (or n/a for a section the brief's scope
+  removed).
+
+## Cut
+
+Delete these; keep only what changes the reader's understanding or action.
+
+- **The obvious.** A zero, an empty set or a default that the reader would assume. Example:
+  "0 sales failed to match an authorization" → delete; keep "267 October sales matched
+  authorizations from earlier months".
+- **Method narration.** How a number was computed, when the method is standard or shown in a table.
+  Keep a method note only where a reader would otherwise misread the number.
+- **One word doing every job.** A generic label repeated across headings, tables and prose.
+  Example: "证据" for data, fields, tables and records → say which: "历史明细表", "汇率来源及折算记录",
+  "缺少首次报送日期".
+- **Repeats.** The same caveat in every section, a closing summary or verdict that restates the
+  opening, a table that repeats the prose.
+- **Exhaustive detail in the body.** Diagnostic tables, full reconciliations and every tested
+  variant belong in an appendix, a collapsed view or the evidence file. Keep in the body what the
+  conclusion rests on.
+- **Internal names.** Script, field or pipeline terms the reader never sees. Example: "合格授权",
+  "关联支持记录", `source_hash` → the business meaning from the sources; meaning unknown and the
+  reader needs the number → a gap; otherwise cut it.
+
+## House style
+
+- Terms match TERMINOLOGY.md, else the bundled
+  [common terms](../../house-style/references/terminology-zh.md); no Avoid term appears in the sense
+  its row avoids.
+- Every **Required** rule in WRITING.md and the template holds, unless the brief overrode it.
+- `locked` text is verbatim.
+
+## Language
+
+Remove these patterns; replace them with the specific claim or nothing:
+
+- **Inflated significance**: "plays a pivotal role", "a testament to", "marks a significant
+  milestone".
+- **Vague attribution**: "experts agree", "industry reports suggest" with no named source.
+- **Filler openers and closers**: "It is important to note that", "In conclusion", a final
+  paragraph that repeats the summary.
+- **Rhythm devices**: lists of exactly three adjectives, "not only … but also", "it's not X, it's Y".
+- **Negative-first sentences** that make the reader invert them. Example: "未能匹配的销售为 0 笔"
+  → delete (obvious), or state the positive fact.
+- **Stock words and jargon**: the banned lists in the house-style guides
+  ([English](../../house-style/references/style-en.md#words),
+  [中文](../../house-style/references/style-zh.md)).
+- **Formatting tics**: bold on every other phrase, inline-header bullet lists for prose reasoning,
+  em dashes in place of every comma.
+- **Chinese**: decorative 首先……其次……最后, a 总结 paragraph that restates the opening,
+  translation artifacts. Sentence-level Chinese wording is `polish-cn`'s job; record a wording
+  finding here only when it changes meaning or blocks understanding.
+
+Do not swap in a generic personality either. The voice is the one in WRITING.md, else the language
+guide.

package/skills/core/editorial-review/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/core/house-style/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

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

@@ -0,0 +1,33 @@
+---
+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.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# House style
+
+Reference files the writing skills share. Read the one the calling skill names; do not run this
+skill on its own. Writing a document → `write-doc`. Learning a style from approved documents →
+`distill-writing`.
+
+| Need | Read |
+| --- | --- |
+| Where WRITING.md is, which template, which rule wins, gap markers, template shape, who edits what | [rules](references/rules.md) |
+| No WRITING.md, or a rule it does not cover | [defaults](references/defaults.md) |
+| Sentences in English / in Chinese | [style-en](references/style-en.md) / [style-zh](references/style-zh.md) |
+| Common Chinese terms (简体 and Hong Kong 繁體), translation-ese fixes, words to avoid | [terminology-zh](references/terminology-zh.md) |
+| Bundled templates and where they came from | [templates/](templates/), [sources](references/sources.md) |
+
+Bundled templates: [brd](templates/brd.md) · [prd](templates/prd.md) ·
+[gap-analysis](templates/gap-analysis.md) · [technical-spec](templates/technical-spec.md) ·
+[integration-guide](templates/integration-guide.md) ·
+[commercial-proposal](templates/commercial-proposal.md) ·
+[compliance-policy](templates/compliance-policy.md) ·
+[risk-operations-procedure](templates/risk-operations-procedure.md) ·
+[general](templates/general.md).
+
+**Never edit these files for one project.** A project's rules go in its WRITING.md and
+`writing/templates/` ([who edits what](references/rules.md#who-edits-what)). Example: a client
+wants "merchant", not "seller" → their TERMINOLOGY.md, not `style-en.md`.

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

@@ -0,0 +1,66 @@
+# Bundled defaults
+
+Apply these when WRITING.md is missing or silent on a point. Every item is a **Default**: the
+assignment, WRITING.md and the chosen template all override it
+([precedence](rules.md#resolve-conflicting-instructions)).
+
+This file holds what applies in any language. Sentence-level rules live in the language guides:
+read [English style](style-en.md) for English and [中文风格](style-zh.md) for Chinese; read both in
+bilingual mode.
+
+## Contents
+
+- [Scope](#scope)
+- [Numbers, dates and names](#numbers-dates-and-names)
+- [Structure](#structure)
+- [Presentation](#presentation)
+
+## Scope
+
+**Write what the brief asks for, at the length it asks for.** A template lists what a full document
+of its type covers; a narrower brief gets a narrower document. Example: "a short policy, one page"
+stays within one page, with no content the sources never mention.
+
+**Mark only the gaps the reader needs** ([gap markers](rules.md#gap-markers)). In a table, write
+`TBD` (Chinese: `待确认`, Traditional `待確認`) in each unknown cell and put one sentence above
+the table: "Owners and dates are to be agreed by `<who>`." Never write `[TBD: owner, owner: X]`.
+
+## Numbers, dates and names
+
+- Use numerals for 10 and above, and for all measurements, money and percentages.
+- Money: currency code and amount, `USD 1,250,000`; state the period for rates (`per month`).
+- Dates: `17 October 2026` in English prose, `2026-10-17` in tables, `2026 年 10 月 17 日` in
+  Chinese. Never "next week" without a date.
+- Keep every figure exactly as the source gives it. Round only in a summary, and keep the precise
+  figure in the body.
+
+## Structure
+
+- Open the document and each section with its point.
+- Order sections so each relies only on what the reader knows or an earlier section established.
+- Keep each policy, rule or definition in one place; refer to it elsewhere. A worked example may
+  repeat a number the policy states.
+- Put background after the point, and only as much as the reader needs.
+- End with what happens next: decision, actions with owners and dates, or open questions.
+
+## Presentation
+
+- **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".
+- **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.
+- **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
+  supports: `(Ops report, Q2 2026)`, or a numbered reference list for long documents.
+- **Diagrams**: Mermaid for flows, sequences and state, when the reader would otherwise hold more
+  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.

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

@@ -0,0 +1,267 @@
+# House-style rules
+
+The one definition of the local writing files, the lookup and precedence rules, the gap markers,
+and the shape every document template follows. `write-doc` and the other writing skills read these
+files; `distill-writing` creates and updates them. They link here; none restates it.
+
+## Contents
+
+- [Local files](#local-files)
+- [Find WRITING.md](#find-writingmd)
+- [Choose the template](#choose-the-template)
+- [Resolve conflicting instructions](#resolve-conflicting-instructions)
+- [Rule strength and evidence](#rule-strength-and-evidence)
+- [Gap markers](#gap-markers)
+- [WRITING.md shape](#writingmd-shape)
+- [Template shape](#template-shape)
+- [Who edits what](#who-edits-what)
+
+## Local files
+
+```text
+project/
+  WRITING.md                  shared voice, presentation, template index
+  TERMINOLOGY.md              preferred term per concept and language, terms to avoid (`terminology`)
+  writing/
+    templates/<type>.md       project templates (same shape as bundled ones)
+    examples/<type>-<n>.md    optional approved or sanitized excerpts
+```
+
+Create files lazily: no empty `writing/` folder, no template without evidence for it.
+
+**WRITING.md holds what every document shares; a template holds what one document type needs.**
+Example: "Write amounts as `USD 1,250,000`" goes in WRITING.md. "Put the price table before the
+terms" goes in `writing/templates/commercial-proposal.md`.
+
+## Find WRITING.md
+
+1. Start in the directory of the document being written or edited. With no output path yet, start
+   in the current working directory. A report written from an input file (a contract, a findings
+   file) starts in the input file's directory instead: the client's house style sits with the
+   client's files. Pasted input: start in the output directory, else the working directory.
+2. Walk up one directory at a time. The first `WRITING.md` found applies. Do not merge it with a
+   `WRITING.md` further up.
+3. Stop at the project root: the nearest ancestor containing `.git`. With no `.git` above the start,
+   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.
+
+`TERMINOLOGY.md` sits beside the `WRITING.md` that applies, else at the project root; find it
+the same way. An older WRITING.md that still holds a Terms table: use its rows too, TERMINOLOGY.md
+winning, and suggest `terminology` to move them.
+
+Resolve every relative link from the file that contains it. Project templates live in
+`writing/templates/` beside the `WRITING.md` that applies, unless its template index links
+elsewhere.
+
+Example: writing `clients/acme/proposal.md` in a repo with `clients/acme/WRITING.md` and a root
+`WRITING.md` applies `clients/acme/WRITING.md` only, and its templates come from
+`clients/acme/writing/templates/`.
+
+## Choose the template
+
+Take the first that applies:
+
+1. **Explicit choice**: the user, or the skill that produced the document, names a template or a
+   path. Use it even if another matches better. Example: `payment-analysis` names its
+   `references/report-template.md` → review its reports against that file.
+2. **Project template**: a file in the project's `writing/templates/` whose `Use when` matches the
+   assignment.
+3. **Bundled template**: one of the bundled [templates](../templates/).
+4. **General**: [general.md](../templates/general.md), adapted into an outline for this assignment.
+
+A project template with the same file name as a bundled one replaces it completely. Never merge the
+two.
+
+Example: the project has `writing/templates/prd.md`; the user asks for a PRD → use the project
+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)).
+
+## Resolve conflicting instructions
+
+**Facts control factual claims, always.** No style rule, template or brief makes an unsupported
+claim acceptable.
+
+For everything else, the higher item wins:
+
+1. The assignment: what the user asked for in this request.
+2. Local **Required** rules: the chosen project template, then WRITING.md.
+3. Local **Default** rules: the chosen project template, then WRITING.md.
+4. Bundled rules: the chosen bundled template, then the language guide
+   ([English](style-en.md), [中文](style-zh.md)), then [defaults](defaults.md).
+5. Writer judgment.
+
+At the same strength the template wins over WRITING.md.
+
+**Words follow TERMINOLOGY.md.** For which term to use, the order is: the assignment, then
+TERMINOLOGY.md, then the template and WRITING.md, then the common
+[terminology](terminology-zh.md). Example: a template example says "seller" and TERMINOLOGY.md
+says "merchant" → write "merchant".
+
+Example: WRITING.md says "Default: no tables in executive summaries"; the brief says "put the
+three options in a table at the top" → use the table. WRITING.md says "Default: open with the
+overall rating"; the board-briefing template says "Default: open with the decision asked" → open
+with the decision. WRITING.md says "Required: amounts in USD with ISO code"; the source quotes
+"$1.2m" → write `USD 1,200,000` and keep the source figure exact.
+
+## Rule strength and evidence
+
+Every rule in WRITING.md or a project template carries a strength:
+
+- **Required**: apply unless this request explicitly overrides it; name the override in the
+  delivery note.
+- **Default**: apply unless the assignment says otherwise.
+- **Optional**: a known good pattern; use when it helps the reader.
+
+An inferred rule carries its evidence and confidence in one short trailer. A rule the user stated
+carries `(user)` instead.
+
+```markdown
+- Default: open each section with its conclusion in one sentence.
+  _(ref: q3-risk-review.md §2, "Overall exposure is moderate"; acme-assessment.md §1; high)_
+- Required: call the client "the Client", never by name, in templates and examples. _(user)_
+```
+
+Confidence: **high** = three or more agreeing references, or an explicit guide; **medium** = one or
+two references; **low** = one reference with counter-evidence, or an inference from layout alone.
+No numeric scores.
+
+Evidence quotes show the pattern, not the old assignment: replace names and figures with `…`.
+Example: `"Overall, the Client's … is rated Amber"`, not the client's name or its alert count.
+A rule's own example uses neutral values, never a reference's: "counts in digits (`12 次`)", not
+the `11 次` the reference reported.
+
+A project template line identical to the bundled template its `Sources` names is bundled text:
+it needs no trailer and is not a hand edit.
+
+## Gap markers
+
+Mark a fact the reader needs and no source gives as `[TBD: <what>, owner: <who>]` (Chinese:
+`【待确认：<内容>，负责人：<谁>】`, Traditional Chinese: `【待確認：<內容>，負責人：<誰>】`). In a
+table, write `TBD` (`待确认`, `待確認`) in each unknown cell and put one sentence above the table
+naming who will agree them. The owner is the role a source names for that item, else the role
+responsible for the document, else `owner: unknown` (`负责人：未知`, `負責人：未知`). A table of
+unknown owners gets one sentence above it naming who should assign them, only when a source names
+that person or role.
+
+## WRITING.md shape
+
+Use this skeleton. Omit any section with no evidence; do not invent content to fill it.
+
+```markdown
+<!-- writing-md: 1 -->
+# Writing guide: <project or organization>
+
+## Readers and documents
+Who reads our documents, what they decide or do with them, and the recurring document types.
+
+## Voice
+Constant across documents. A short "We are / We are not" table, each row with evidence. The brand
+name and the closing call to action, when documents end with one.
+
+## Language
+Languages used, bilingual presentation (paired paragraphs or separate versions), source language.
+
+## Terms
+One line: `Terms: see [TERMINOLOGY.md](TERMINOLOGY.md).` The terms themselves live in
+TERMINOLOGY.md, in the `terminology` skill's format; never a table here.
+
+## Sentences and paragraphs
+Length, person, tense, numbers, dates, currency, abbreviations.
+
+## Structure and reasoning
+How a conclusion, its evidence, trade-offs and the recommendation connect.
+
+## Presentation
+Headings, paragraph density, lists, tables, emphasis, links and citations, diagrams.
+
+## Templates
+| Template | Use when | Notes |
+| --- | --- | --- |
+| risk-assessment (`writing/templates/risk-assessment.md`) | ... | ... |
+
+## Examples
+Two or three short annotated excerpts (approved or sanitized), or links to writing/examples/.
+
+## Sources and open choices
+References read (file, date, standing: approved guide / approved document / draft), conflicts not
+yet decided with the recommended answer, and intentional exceptions.
+```
+
+Tone that varies by document type (formality, technical depth) goes in the template's `Tone` line,
+not in Voice.
+
+## Template shape
+
+A template is a strategy for one document type. Every template, bundled or project, has these
+sections in this order:
+
+1. **Use when**: the reader, the decision or action the document serves, and when to pick this
+   template over a neighbor.
+2. **Tone**: one line: formality, technical depth, and any type-specific voice shift.
+3. **Inputs**: the evidence the writer can use. Mark an input the reader cannot do without
+   `Material:` with its action: `ask once`, `mark [TBD]` ([gap markers](#gap-markers)), or `narrow the scope`, or two of them in
+   order (`ask once, else narrow the scope`). An unmarked input follows its own line's instruction
+   when it has one; otherwise leave it out.
+4. **Reasoning**: how to turn the inputs into the argument, analysis or specification.
+5. **Sections**: the outline. For each section: what it must achieve, its strength, and how to
+   adapt it. Strength is `Required`, `Optional`, or `Required when <condition>`. Keep the order
+   unless the reader's decision needs another.
+6. **Done when**: the type-specific checks that make the result useful. Each is a yes/no question.
+   A question about a section the brief's scope removed answers n/a.
+7. **Sources**: where the bundled default was adapted from, or, for a project template, the
+   references it was distilled from.
+
+Use this skeleton for every template, bundled or distilled:
+
+```markdown
+# <Type>: <short qualifier>
+
+## Use when
+<Reader, the decision or action, when to pick it.> Then one bullet per neighbor:
+- Pick **<other-template>** instead when …
+
+## Tone
+<One line.>
+
+## Inputs
+- <Input>. Material: <ask once | mark [TBD] | narrow the scope>.
+
+## Reasoning
+1. <Step from inputs toward the conclusion.>
+
+## Sections
+Omit Optional sections that add nothing. Do not pad with empty headings.
+
+1. **<Section>** (Required | Optional): <what it must achieve; how to adapt it>.
+
+## Done when
+- <Yes/no question>?
+
+## Sources
+<Bundled: what informed it. Project: the references it was distilled from, and the bundled
+template it started from with the write-doc release-version, e.g. "bundled gap-analysis, 0.36.0".>
+```
+
+**Locked text** is wording an outside authority mandates (a regulator, a scheme, a signed
+contract). It sits in a fenced block marked `locked`, with its source on the line above, and is
+copied unchanged and never translated into the document's voice. House boilerplate is not locked:
+it is a Default, adapted when the facts differ. Example: a rating scale saying "exposes the Client
+to regulatory action" is house text; for an internal-standard review, adapt it.
+
+## Who edits what
+
+- `write-doc` never edits WRITING.md or a project template unless the user asks in that request.
+  A correction applies to the current document only.
+- `distill-writing` updates them deliberately: it keeps `(user)` rules and manual edits, and lists
+  every material change and conflict before or as it writes.
+- 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
+  `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.
+- Skill updates replace the bundled templates and defaults only. Project files are never touched by
+  an update.

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

@@ -0,0 +1,27 @@
+# Sources and attribution
+
+The bundled templates, defaults and English style guide are original text written for this skill;
+the sources below informed their structure and ideas. The Chinese style guide is adapted from an
+MIT-licensed source, as marked. Checked 2026-10-17.
+
+| Area | Source | License | How it is used |
+| --- | --- | --- | --- |
+| Editorial baseline | [Google developer documentation style guide](https://developers.google.com/style/highlights) | CC BY 4.0 (text) | Ideas for [style-en](style-en.md) (lead with the point, active voice, everyday words) and [defaults](defaults.md) (informative headings, link text). |
+| Technology voice | [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) | All rights reserved | Linked for reference only. |
+| English technical style | [Cursor `technical-writing` skill](https://github.com/cursor/plugins/blob/main/pstack/skills/technical-writing/SKILL.md) | No license stated | Ideas only for [style-en](style-en.md): layered rules, rhythm, the system as the word list. No text copied. |
+| Chinese technical style | [Fenng/tech-doc-style-chinese](https://github.com/Fenng/tech-doc-style-chinese) | MIT | Adapted into [style-zh](style-zh.md); the copyright and permission notice is reproduced at its end. |
+| PRD | [Atlassian product requirements template](https://www.atlassian.com/software/confluence/templates/product-requirements) | All rights reserved | Linked; [prd](../templates/prd.md) is adapted from the retired `prd` skill in this repository. |
+| BRD | Retired `brd` skill in this repository | MIT (1aboveio/ai) | Folded into [brd](../templates/brd.md). |
+| Technical spec | [GitLab design document template](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/_template/), [arc42](https://arc42.org/overview/) | All rights reserved; CC BY-SA 4.0 | Ideas only for [technical-spec](../templates/technical-spec.md). No arc42 text is adapted, so share-alike does not apply. |
+| Decision records | [MADR](https://adr.github.io/madr/) | MIT or CC0-1.0 | Ideas for recording options and decisions in technical-spec. |
+| Integration guide | [Diátaxis](https://diataxis.fr/start-here/) | CC BY-SA 4.0 | The tutorial / how-to / reference / explanation distinction shapes [integration-guide](../templates/integration-guide.md). No Diátaxis text is adapted. |
+| Project updates | [Atlassian project status template](https://www.atlassian.com/software/confluence/templates/project-status) | All rights reserved | Linked; covered by [general](../templates/general.md). |
+| Local context files | [Impeccable](https://impeccable.style/docs/context/) | Apache-2.0 (code repository) | The idea of keeping editable project context apart from the skill. No text used. |
+
+Gap analysis, compliance policy, risk operations procedure and commercial proposal are authored
+for this skill. Improve them for a project by distilling approved examples with `distill-writing`.
+
+When adding to a bundled file: write original text. Do not paste wording from an all-rights-reserved
+source. Adapting text from a CC BY-SA source puts the adapted file under CC BY-SA 4.0; adapting
+CC BY text requires the credit line "Portions adapted from <title>, <link>, CC BY 4.0, changes
+made".