@tplog/hasapi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hasapi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# hasapi
+
+One command to set up the [Pi](https://github.com/earendil-works/pi-mono) coding agent the way I like it — a curated set of extensions plus the `hasapi-*` skills, installed globally.
+
+## Quick start
+
+```bash
+npx @tplog/hasapi
+```
+
+It will:
+
+1. Install `pi` for you if it isn't on PATH yet.
+2. Install the curated pi extensions (`pi install <source>`).
+3. Copy the bundled `hasapi-skills/` into `~/.pi/agent/skills/` and enable skill commands.
+
+Install is **idempotent** — extensions already in your pi settings are skipped, and skills are re-copied so re-running updates them safely.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `npx @tplog/hasapi` | Install everything (extensions + skills) |
+| `npx @tplog/hasapi status` | Show which extensions/skills are installed |
+| `npx @tplog/hasapi remove` | Remove the hasapi extensions and skills |
+| `npx @tplog/hasapi doctor` | Check your environment for common problems |
+
+## What gets installed
+
+**Extensions** (`pi install`):
+
+- `npm:pi-markdown-preview` — Markdown preview
+- `npm:pi-notify` — desktop notifications
+- `npm:@aliou/pi-processes` — background process management
+- `npm:@plannotator/pi-extension` — planning and annotation workflow
+- `npm:pi-mcp-adapter` — MCP server integration
+- `npm:@narumitw/pi-goal` — goal tracking
+- `npm:@juicesharp/rpiv-ask-user-question` — ask-user prompts
+- `npm:context-mode` — context-mode tooling
+- `npm:@narumitw/pi-btw` — side-chat popover
+- `npm:pi-generative-ui` — generative UI
+- `npm:glimpseui` — native UI widgets and dialogs
+- `npm:pi-provider-kimi-code` — Kimi model provider
+- `npm:pi-claude-bridge` — Claude Code provider bridge
+- `npm:@narumitw/pi-chrome-devtools` — Chrome DevTools control
+
+**Skills** — the `hasapi-skills/` bundle (diagnosis + implementation chain) copied to
+`~/.pi/agent/skills/hasapi-skills/`. The folder moves as a unit so each skill's
+`../_shared/*` references keep resolving.
+
+## Editing the catalog
+
+Extensions live in the `EXTENSIONS` array at the top of `bin/hasapi.mjs`. Add an entry
+with an `id`, `source` (`npm:` or `git:`), and `description`.

package/bin/hasapi.mjs

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import {
+	existsSync,
+	readFileSync,
+	writeFileSync,
+	copyFileSync,
+	mkdirSync,
+	cpSync,
+	rmSync,
+} from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { cwd } from "node:process";
+
+// ---------------------------------------------------------------------------
+// Catalog
+// ---------------------------------------------------------------------------
+// pi extensions installed via `pi install <source>`. Curate to taste.
+const EXTENSIONS = [
+	{ id: "markdown-preview", source: "npm:pi-markdown-preview", description: "Markdown preview" },
+	{ id: "notify", source: "npm:pi-notify", description: "Desktop notifications" },
+	{ id: "processes", source: "npm:@aliou/pi-processes", description: "Background process management" },
+	{ id: "plannotator", source: "npm:@plannotator/pi-extension", description: "Planning and annotation workflow" },
+	{ id: "mcp-adapter", source: "npm:pi-mcp-adapter", description: "MCP server integration" },
+	{ id: "goal", source: "npm:@narumitw/pi-goal", description: "Goal tracking" },
+	{ id: "ask-user-question", source: "npm:@juicesharp/rpiv-ask-user-question", description: "Ask-user prompts" },
+	{ id: "context-mode", source: "npm:context-mode", description: "Context-mode tooling" },
+	{ id: "btw", source: "npm:@narumitw/pi-btw", description: "Side-chat popover" },
+	{ id: "generative-ui", source: "npm:pi-generative-ui", description: "Generative UI" },
+	{ id: "glimpse", source: "npm:glimpseui", description: "Native UI widgets and dialogs" },
+	{ id: "provider-kimi-code", source: "npm:pi-provider-kimi-code", description: "Kimi model provider" },
+	{ id: "claude-bridge", source: "npm:pi-claude-bridge", description: "Claude Code provider bridge" },
+	{ id: "chrome-devtools", source: "npm:@narumitw/pi-chrome-devtools", description: "Chrome DevTools control" },
+];
+
+// Bundled skills dir, copied as a unit into ~/.pi/agent/skills/hasapi-skills.
+// The whole folder moves together so each skill's ../_shared/* paths still resolve.
+const SKILLS_BUNDLE_DIR = "hasapi-skills";
+
+const PI_CORE_SPEC = "@earendil-works/pi-coding-agent";
+
+// ---------------------------------------------------------------------------
+// Small ANSI helpers (no deps)
+// ---------------------------------------------------------------------------
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const bold = paint("1");
+const dim = paint("2");
+const red = paint("31");
+const green = paint("32");
+const yellow = paint("33");
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+const HERE = dirname(fileURLToPath(import.meta.url));
+const bundledSkillsPath = () => join(HERE, "..", SKILLS_BUNDLE_DIR);
+const settingsPath = () => join(homedir(), ".pi", "agent", "settings.json");
+const skillsRoot = () => join(homedir(), ".pi", "agent", "skills");
+const installedSkillsPath = () => join(skillsRoot(), SKILLS_BUNDLE_DIR);
+
+// ---------------------------------------------------------------------------
+// spawn / settings
+// ---------------------------------------------------------------------------
+function spawnCommand(command, args = [], options = {}) {
+	// On Windows npm/pi resolve to .cmd shims that need a shell.
+	const shell = platform() === "win32";
+	return spawnSync(command, args, { shell, ...options });
+}
+
+function hasCmd(name) {
+	const probe = spawnCommand(platform() === "win32" ? "where" : "which", [name], { stdio: "ignore" });
+	return probe.status === 0;
+}
+
+function runPi(args) {
+	return spawnCommand("pi", args, { stdio: "inherit" }).status ?? 1;
+}
+
+function readSettings() {
+	const path = settingsPath();
+	if (!existsSync(path)) return { path, exists: false, parsed: {}, error: null };
+	try {
+		return { path, exists: true, parsed: JSON.parse(readFileSync(path, "utf8")), error: null };
+	} catch (err) {
+		return { path, exists: true, parsed: null, error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+function writeSettings(mutate) {
+	const current = readSettings();
+	if (current.error) return { ok: false, path: current.path, error: current.error };
+	const settings = current.parsed ?? {};
+	if (!mutate(settings)) return { ok: true, path: current.path, changed: false };
+	mkdirSync(dirname(current.path), { recursive: true });
+	if (current.exists) {
+		const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+		copyFileSync(current.path, `${current.path}.hasapi.${stamp}.bak`);
+	}
+	writeFileSync(current.path, JSON.stringify(settings, null, 2) + "\n", "utf8");
+	return { ok: true, path: current.path, changed: true };
+}
+
+function installedSources() {
+	const { parsed } = readSettings();
+	const set = new Set();
+	for (const entry of parsed?.packages ?? []) {
+		if (typeof entry === "string") set.add(entry);
+		else if (entry && typeof entry.source === "string") set.add(entry.source);
+	}
+	return set;
+}
+
+// ---------------------------------------------------------------------------
+// install steps
+// ---------------------------------------------------------------------------
+function ensurePi() {
+	if (hasCmd("pi")) return true;
+	console.log(yellow("`pi` not found on PATH."));
+	console.log(`Installing Pi via \`npm install -g ${PI_CORE_SPEC}\``);
+	const code = spawnCommand("npm", ["install", "-g", PI_CORE_SPEC], { stdio: "inherit" }).status;
+	if (code !== 0) {
+		console.error(red(`Failed to install Pi. You may need sudo:\n  sudo npm install -g ${PI_CORE_SPEC}`));
+		return false;
+	}
+	if (!hasCmd("pi")) {
+		console.error(red("Installed Pi, but `pi` is still not on PATH. Open a new shell and re-run."));
+		return false;
+	}
+	return true;
+}
+
+function installExtensions() {
+	const installed = installedSources();
+	let failures = 0;
+	for (const ext of EXTENSIONS) {
+		if (installed.has(ext.source)) {
+			console.log(dim(`  • ${ext.id} — already installed`));
+			continue;
+		}
+		console.log(`→ pi install ${ext.source}`);
+		if (runPi(["install", ext.source]) !== 0) {
+			console.error(red(`  ✗ failed to install ${ext.id}`));
+			failures++;
+		}
+	}
+	return failures;
+}
+
+function installSkills() {
+	const src = bundledSkillsPath();
+	if (!existsSync(src)) {
+		console.error(red(`Bundled skills not found at ${src}`));
+		return 1;
+	}
+	const dest = installedSkillsPath();
+	mkdirSync(skillsRoot(), { recursive: true });
+	cpSync(src, dest, { recursive: true });
+	console.log(green(`  ✓ skills → ${dest}`));
+	return 0;
+}
+
+function enableSkillCommands() {
+	const result = writeSettings((s) => {
+		if (s.enableSkillCommands === true) return false;
+		s.enableSkillCommands = true;
+		return true;
+	});
+	if (!result.ok) {
+		console.error(red(`Could not update settings (${result.error}). Set "enableSkillCommands": true manually.`));
+		return 1;
+	}
+	if (result.changed) console.log(green('  ✓ enableSkillCommands: true'));
+	return 0;
+}
+
+// ---------------------------------------------------------------------------
+// commands
+// ---------------------------------------------------------------------------
+function cmdInstall() {
+	console.log(bold("hasapi") + dim(" — installing onto pi\n"));
+	if (!ensurePi()) return 127;
+
+	console.log(bold("Extensions"));
+	const extFailures = installExtensions();
+
+	console.log(bold("\nSkills"));
+	const skillFailures = installSkills();
+	const settingsFailures = enableSkillCommands();
+
+	const failures = extFailures + skillFailures + settingsFailures;
+	console.log("");
+	if (failures > 0) {
+		console.error(red(`Done with ${failures} failure(s).`));
+		return 1;
+	}
+	console.log(green("Done. Run `pi` to start."));
+	return 0;
+}
+
+function cmdStatus() {
+	const installed = installedSources();
+	console.log(bold("Extensions"));
+	for (const ext of EXTENSIONS) {
+		const ok = installed.has(ext.source);
+		console.log(`  ${ok ? green("✓") : yellow("•")} ${ext.id} ${dim(ext.source)}`);
+	}
+	console.log(bold("\nSkills"));
+	const skillsOk = existsSync(installedSkillsPath());
+	console.log(`  ${skillsOk ? green("✓") : yellow("•")} ${SKILLS_BUNDLE_DIR} ${dim(installedSkillsPath())}`);
+	const { parsed } = readSettings();
+	const cmdsOn = parsed?.enableSkillCommands === true;
+	console.log(`  ${cmdsOn ? green("✓") : yellow("•")} enableSkillCommands`);
+	return 0;
+}
+
+function cmdRemove() {
+	let failures = 0;
+	const installed = installedSources();
+	console.log(bold("Removing extensions"));
+	for (const ext of EXTENSIONS) {
+		if (!installed.has(ext.source)) {
+			console.log(dim(`  • ${ext.id} — not installed`));
+			continue;
+		}
+		console.log(`→ pi remove ${ext.source}`);
+		if (runPi(["remove", ext.source]) !== 0) {
+			console.error(red(`  ✗ failed to remove ${ext.id}`));
+			failures++;
+		}
+	}
+	console.log(bold("\nRemoving skills"));
+	const dest = installedSkillsPath();
+	if (existsSync(dest)) {
+		rmSync(dest, { recursive: true, force: true });
+		console.log(green(`  ✓ removed ${dest}`));
+	} else {
+		console.log(dim(`  • skills not present`));
+	}
+	return failures > 0 ? 1 : 0;
+}
+
+function cmdDoctor() {
+	const checks = [];
+	const [major] = process.versions.node.split(".").map(Number);
+	checks.push([major >= 20, `Node ${process.versions.node} (need >=20)`]);
+	checks.push([hasCmd("pi"), "`pi` on PATH"]);
+	const s = readSettings();
+	checks.push([!s.error, s.error ? `settings.json invalid JSON (${s.error})` : `settings.json readable`]);
+	checks.push([existsSync(bundledSkillsPath()), `bundled skills present`]);
+	let ok = true;
+	for (const [pass, label] of checks) {
+		console.log(`  ${pass ? green("✓") : red("✗")} ${label}`);
+		if (!pass) ok = false;
+	}
+	return ok ? 0 : 1;
+}
+
+function cmdHelp() {
+	console.log(`${bold("hasapi")} — install hasapi extensions + skills onto pi
+
+Usage:
+  npx @tplog/hasapi            Install everything (extensions + skills)
+  npx @tplog/hasapi status     Show what's installed
+  npx @tplog/hasapi remove     Remove hasapi extensions + skills
+  npx @tplog/hasapi doctor     Check environment
+  npx @tplog/hasapi help       Show this help`);
+	return 0;
+}
+
+// ---------------------------------------------------------------------------
+// entry
+// ---------------------------------------------------------------------------
+const command = process.argv[2] ?? "install";
+const dispatch = {
+	install: cmdInstall,
+	status: cmdStatus,
+	remove: cmdRemove,
+	doctor: cmdDoctor,
+	help: cmdHelp,
+	"--help": cmdHelp,
+	"-h": cmdHelp,
+};
+const handler = dispatch[command];
+if (!handler) {
+	console.error(red(`Unknown command: ${command}`));
+	cmdHelp();
+	process.exit(2);
+}
+process.exit(handler());

package/hasapi-skills/README.md

@@ -0,0 +1,56 @@
+# hasapi-skills（刃 · pi 定制包）
+
+> HasaPi（刃）= 刀刃。开发应如刀：**需求抓准，精准实现。**
+> 诊断层来自 brooks-lint（建立在 Frederick Brooks《人月神话》等经典之上，
+> 文本中保留这些作者引用——那是刀刃赖以锋利的钢材），
+> 实现层来自 mattpocock 的执行链。统一以 hasapi-* 命名。
+
+## 安装
+
+    unzip hasapi-skills.zip -d ~/.pi/agent/skills/
+
+得到 ~/.pi/agent/skills/hasapi-skills/...，pi 递归发现全部 15 个 skill。
+确保 ~/.pi/agent/settings.json 内 "enableSkillCommands": true。
+
+> 关键：_shared/ 必须与 hasapi-* 同级（本包已保证）。诊断类 skill 用
+> ../_shared/common.md 等相对路径读共享文件，挪动布局会断。
+
+## 15 个 skill（+ _shared 资源）
+
+诊断/质检（6，多数自动触发）—— 钢之背，负责"看得准":
+  hasapi-health  hasapi-audit  hasapi-review  hasapi-test  hasapi-debt  hasapi-sweep
+实现链（7）—— 刃之锋，负责"切得正":
+  hasapi-grilling  hasapi-to-prd  hasapi-to-issues  hasapi-implement
+  hasapi-tdd  hasapi-handoff  hasapi-setup
+日常高频（2，自动触发）:
+  hasapi-diagnosing-bugs（查具体 bug）  hasapi-resolving-merge-conflicts（解合并冲突）
+
+_shared/ 不是 skill（无 SKILL.md），是诊断层共享参考文件，勿删勿改名。
+
+## 自动 vs 手动
+
+- 自然说话即自动触发：hasapi-{health,audit,review,test,debt,sweep,grilling,tdd,
+  diagnosing-bugs,resolving-merge-conflicts}
+- 必须手动 /skill:name：hasapi-{to-prd,to-issues,implement,handoff,setup}
+  （凡是"改外部世界 / 切阶段"的，扳机留给人）
+
+## 推荐节奏（头尾诊断、中间实现）
+
+1. /skill:hasapi-health             进场体检，拿 baseline
+2. hasapi-grilling                  逼清需求（刀要抓准的地方，人重仓）
+3. /skill:hasapi-to-prd（大功能）→ /skill:hasapi-to-issues   落成 ready-for-agent
+4. /skill:hasapi-implement + hasapi-tdd   精准实现（人可 AFK）
+5. hasapi-review / hasapi-test      质检（人守闸门，逐条 accept/dismiss）
+6. hasapi-debt                      记债进 backlog（可喂回 to-issues）
+7. /skill:hasapi-handoff <重点>     趁上下文干净，存档换会话
+
+日常：bug 用 hasapi-diagnosing-bugs；合并卡住用 hasapi-resolving-merge-conflicts。
+
+## 注意
+
+- 每个项目首次使用前跑一次 /skill:hasapi-setup 配好 GitHub issue tracker，
+  否则 implement / to-issues 不知道去哪取活、往哪写。
+- hasapi-sweep 会自动改代码：只在熟悉某库、想一键清理时手动调，陌生库别用。
+- 故意未含 matt 的 review / architecture 类 skill——诊断走 hasapi-review，避免抢活。
+- tdd 文本中保留了对 /codebase-design、/domain-modeling 的引用（不在本包内），
+  模型会自行适配；如需要可另行补装。

package/hasapi-skills/_shared/common.md

@@ -0,0 +1,240 @@
+# Brooks-Lint — Shared Framework
+
+Code and test quality diagnosis using principles from twelve classic software engineering books.
+Use `source-coverage.md` to keep those sources grounded in real evidence, exceptions, and tradeoffs.
+
+## The Iron Law
+
+```
+NEVER suggest fixes before completing risk diagnosis.
+EVERY finding must follow: Symptom → Source → Consequence → Remedy.
+```
+
+Violating this law produces reviews that list rule violations without explaining why they
+matter. A finding without a consequence and a remedy is not a finding — it is noise.
+
+> **On-demand sections (skip unless the condition applies):**
+> - "Remedy Mode" — only when user passes `--fix` or asks to fix findings
+> - "Post-Report Triage" — only in interactive sessions after the report is output
+> - "History Tracking" — only after the Health Score is computed
+
+## Project Config
+
+Before executing the review, attempt to read `.brooks-lint.yaml` from the project root.
+If the file exists, parse and apply its settings before proceeding.
+If the file does not exist, continue with defaults (all risks enabled, no ignores).
+
+In a multi-mode session, re-read only if the user says the config has changed.
+
+### Supported settings
+
+**`disable`** — list of risk codes to skip entirely. Findings for disabled risks are
+silently omitted from the report and do not affect the Health Score.
+Valid codes: `R1` `R2` `R3` `R4` `R5` `R6` `T1` `T2` `T3` `T4` `T5` `T6`
+
+**`severity`** — override the severity of a specific risk for this project.
+Valid values: `critical` `warning` `suggestion`
+Example: `R1: suggestion` means every R1 finding is downgraded to Suggestion regardless
+of what the guide says.
+
+**`ignore`** — list of glob patterns. Files matching any pattern are excluded from
+analysis. Findings that arise solely from ignored files are omitted.
+Common entries: `**/*.generated.*`, `**/vendor/**`, `**/migrations/**`
+
+**`focus`** — non-empty list of risk codes to evaluate; all others are skipped.
+Omit this key (or leave it empty) to evaluate all non-disabled risks.
+Cannot be combined with a non-empty `disable` list.
+
+**Minimal example:**
+```yaml
+version: 1
+disable:
+  - T5
+severity:
+  R1: suggestion
+ignore:
+  - "**/*.generated.*"
+```
+
+If `.brooks-lint.yaml` contains a `custom_risks` map, read `custom-risks-guide.md`
+from the `_shared/` directory for loading and scanning instructions.
+
+### Config Validation
+
+Before applying, check for errors and mention each in the report:
+- Invalid risk code (not R1–R6, T1–T6, or a defined `Cx` code): skip it, note `"Config warning: X is not a valid risk code"`
+- Invalid severity value (not `critical`/`warning`/`suggestion`): skip it, note the error
+- Both `disable` and `focus` are non-empty: treat as a config error, ignore both, note it
+
+If the YAML fails to parse entirely, skip config loading and proceed with defaults.
+
+### Config Reporting
+
+If a config file was found and applied, add this line immediately after the **Scope** line
+in the report:
+`Config: .brooks-lint.yaml applied (N risks disabled, M paths ignored)`
+
+Include N and M even if zero. Omit this line if no config file was found.
+
+---
+
+## Auto Scope Detection
+
+When no files or code are specified, detect scope automatically:
+
+**PR Review:** `git diff --cached` → `git diff` → `git diff main...HEAD` → ask user.
+
+**Architecture Audit / Tech Debt:** Entire project by default. `--since=<ref>`: run `git diff <ref>...HEAD --name-only`, analyze only modules containing changed files; note "Incremental audit — modules touched since <ref>".
+
+**Test Quality:** All test files by default. If a diff exists, prioritize test files co-located with changed production files (`src/foo.ts` → `src/foo.test.ts`).
+
+**Health Dashboard:** Entire project by default. If user provides a path, scope all dimension sub-scans to that path.
+
+**Scope line:** Always state what was detected — e.g., `Scope: staged changes (3 files)` or `Scope: branch changes vs main (12 files)`.
+
+---
+
+## The Six Decay Risks
+
+Navigation index only — canonical definitions (symptoms, severity guides, sources, "What Not
+to Flag" guards) live in `decay-risks.md`. Do not duplicate or edit diagnostic questions here;
+update `decay-risks.md` directly. Book-level coverage, exceptions, and tradeoffs are in
+`source-coverage.md`.
+
+| Risk | Diagnostic Question |
+|------|---------------------|
+| Cognitive Overload | How much mental effort to understand this? |
+| Change Propagation | How many unrelated things break on one change? |
+| Knowledge Duplication | Is the same decision expressed in multiple places? |
+| Accidental Complexity | Is the code more complex than the problem? |
+| Dependency Disorder | Do dependencies flow in a consistent direction? |
+| Domain Model Distortion | Does the code faithfully represent the domain? |
+
+---
+
+## Report Template
+
+**Language rule:** Output the report in the same language the user is using. Translate the
+per-finding content and the one-sentence verdict to match the user's language. Keep the
+following in English: Iron Law field labels (Symptom / Source / Consequence / Remedy),
+book titles, principle and smell names (e.g. "Shotgun Surgery", "Divergent Change"),
+and fixed structural headers from the template below (`Findings`, `Summary`,
+`Module Dependency Graph`, `Critical`, `Warning`, `Suggestion`).
+
+````
+# Brooks-Lint Review
+
+**Mode:** [PR Review / Architecture Audit / Tech Debt Assessment / Test Quality Review]
+**Scope:** [file(s), directory, or description of what was reviewed]
+**Health Score:** XX/100
+
+[One sentence overall verdict]
+
+---
+
+## Module Dependency Graph
+
+<!-- Mode 2 (Architecture Audit) ONLY — omit this section for other modes -->
+<!-- classDef colors: see architecture-guide.md Step 1 Rule 6 -->
+
+```mermaid
+graph TD
+    ...
+```
+
+---
+
+## Findings
+
+<!-- Sort all findings by severity: Critical first, then Warning, then Suggestion -->
+<!-- If no findings in a severity tier, omit that tier's heading -->
+
+### 🔴 Critical
+
+**[Risk Name] — [Short descriptive title]**
+Symptom: [exactly what was observed in the code]
+Source: [Book title — Principle or Smell name]
+Consequence: [what breaks or gets worse if this is not fixed]
+Remedy: [concrete, specific action]
+
+### 🟡 Warning
+
+**[Risk Name] — [Short descriptive title]**
+Symptom: ...
+Source: ...
+Consequence: ...
+Remedy: ...
+
+### 🟢 Suggestion
+
+**[Risk Name] — [Short descriptive title]**
+Symptom: ...
+Source: ...
+Consequence: ...
+Remedy: ...
+
+---
+
+## Summary
+
+[2–3 sentences: what is the most important action, and what is the overall trend]
+````
+
+## Remedy Mode
+
+When the user passes `--fix` or asks to "fix the findings", read
+`remedy-guide.md` from the `_shared/` directory before writing the report.
+
+## Health Score Calculation
+
+Base score: 100
+Deductions:
+- Each 🔴 Critical finding: −15
+- Each 🟡 Warning finding: −5
+- Each 🟢 Suggestion finding: −1
+Floor: 0 (score cannot go below 0)
+
+## History Tracking
+
+After generating the Health Score, attempt to append a record to `.brooks-lint-history.json`
+in the project root.
+
+**Append logic:**
+1. Read the file (or start with empty array if it doesn't exist)
+2. Append: `{ date, mode, score, findings: { critical, warning, suggestion }, scope }`
+3. Write the file back
+
+**Trend display:** If the history file exists and contains at least one prior record for
+the same mode, add a Trend line after the Health Score in the report:
+
+  **Trend:** 85 → 82 (−3) over last 3 runs
+
+Show the most recent prior score and the delta. If delta is 0: "Stable at 82".
+If this is the first run for this mode: "First run — no trend data".
+
+## Post-Report Triage (Optional)
+
+**Guard:** Interactive sessions only — skip in CI/headless mode.
+
+After reporting Warning or Suggestion findings, offer:
+> Would you like to triage these findings? (accept / dismiss / defer / skip)
+
+For each finding one at a time (lowest severity first): show title, ask `[a]ccept / [d]ismiss / [f]defer / [s]kip`; wait for reply before moving to the next.
+
+**Dismiss:** ask one-line reason → append to `.brooks-lint.yaml` under `suppress:` → downgraded to info in future runs.
+
+**Defer:** same as dismiss, add `expires: YYYY-MM-DD` (default 90 days) → resurfaces at original severity after expiry.
+
+**Suppress matching at scan time:** for each `suppress:` entry, match `risk` code and file `pattern` against findings.
+- Both match → downgrade to info (not counted in Health Score, shown under collapsed "Suppressed" section).
+- `expires` is past → ignore entry, finding resurfaces. Note in Summary: "N suppressed findings have expired and are now active again."
+
+## Reference Files
+
+Read on demand:
+
+| File | When to Read |
+|------|-------------|
+| `source-coverage.md` | At the start of every review, before writing findings |
+| `decay-risks.md` | Before any production-code review or architecture/debt assessment |
+| `test-decay-risks.md` | Before any test review and before the PR Review "Quick Test Check" step |