@gavin-hu/my-pi-agent 0.20.0 → 0.22.0

package/skills/project-docs/references/release.md

@@ -1,84 +0,0 @@
-# Release
-
-Only when the user asked for a specific version. A release is a promise: a tag, a
-published artifact, and a section of the changelog that says what is in it. The
-project's release document owns the whole procedure; this file adds the changelog
-steps and the order they fit into, not a competing one.
-
-## Before touching the file
-
-1. Read the project's release document — `docs/release.md`, `RELEASING.md`,
-   `CONTRIBUTING.md`'s release section, `.github/workflows/publish.yml`. It decides
-   the files to bump, the tag format, and the push and publish order.
-2. Confirm the version and the reason with the user. Say the reason in SemVer's
-   terms: a fix with no surface change is a patch, an additive surface is a minor, a
-   breaking change is a major — and ask when a project in `0.x` treats minors as the
-   breaking channel, because many do. Never infer a version from the size of the
-   diff and never raise the version in the release without the user's word for it.
-
-## Move the entries
-
-A project that keeps no changelog file — only GitHub or GitLab releases, or release
-notes a tool generates — has nothing to move: say so and stop, and do not create the
-file as part of a release. The rest of this section assumes one exists.
-
-A file a tool generates is moved by that tool, not here: `changeset version`,
-`git-cliff --tag`, `release-please`, `semantic-release`, or whatever the project's
-release document names. In that case this mode's job is to check the result — the
-version, the dated heading, the category order, the link refs — and to report the step
-that is still owed, never to edit the generated file.
-
-- Read `[Unreleased]` and check it is what the release contains: everything since
-  the last tag, nothing that already shipped.
-- Move every entry under `## [X.Y.Z] - YYYY-MM-DD`, categories in the file's own
-  order and spelling, creating only the categories that hold an entry. Keep each
-  bullet's text; a release is a move, not a rewrite.
-- Leave `[Unreleased]` present and empty, unless the file's preamble says it is
-  removed between releases. An empty heading is how the next change knows where to
-  land.
-- Update the link references: `[Unreleased]` now compares from the new tag, and the
-  new version gets a reference in the file's existing style (`compare/vOLD...vNEW`
-  or `releases/tag/vNEW`).
-- Bump the version where the project keeps it — usually one manifest, sometimes a
-  lockfile, a version file, and an install pin. The build manifest and the newest
-  dated heading must agree, or a consistency guard fails.
-- The release commit holds the changelog move, the version bump, and the link refs.
-  No behavior, no new entries, no unrelated docs: a release commit that also changes
-  code cannot be diffed as a release.
-
-## Finish
-
-- Run the project's release guard (often `release.test.ts` or a `changelog` check),
-  then the project's full check. The guard is the one test that names a version, so
-  run it directly while iterating.
-- Then, in the project's order and only with explicit approval for that push: commit,
-  tag (`vX.Y.Z`, annotated where the project does that), push the tag together with
-  the branch — a branch push that lands before its tag races the checkout that
-  asserts they agree — and publish through the project's pipeline, not a local
-  publish.
-- The release body is that section verbatim, heading included. Do not add a summary,
-  a thank-you, or a rewrite of the bullets a reader already has.
-
-## Verify a release you did not cut
-
-A release is a chain of steps, and the last one can sit for hours waiting on a
-pipeline's approval, so checking a tagged version is its own job. It touches no file:
-open the tag, read each of these, and report the line.
-
-- The tag's own manifest — `git show vX.Y.Z:package.json`, or the equivalent — because
-  the publish job proves that before it publishes, not the branch's.
-- The newest dated heading, and the project's release guard where it has one.
-- The link refs: `[Unreleased]` compares from the new tag, and `X.Y.Z` points at it.
-- Whatever the release document bumps in the same commit — an install pin, a version
-  stamped in a guide, a captured image.
-- The release body against the section the project's own tooling prints, never against
-  memory.
-- The publish run itself: a workflow that checks out `vX.Y.Z` publishes the tagged tree
-  whatever ref the dispatch named, so what remains is its environment approval and the
-  registry version after it.
-
-## After
-
-If a shipped change turns out to have no bullet, do not edit the released section.
-Record the gap to the user and add a bullet to `[Unreleased]` for the next release,
-naming the fix; a released section is a record of what was published, not a draft.

package/skills/project-docs/references/roadmap.md

@@ -1,93 +0,0 @@
-# Roadmap
-
-The roadmap is the one document that describes the tree rather than the last release,
-so it goes stale two ways: it keeps what already shipped, and it promises what the
-tree already does differently. This mode re-derives it and deletes what is done. It
-never decides what matters.
-
-Read [`discovery.md`](./discovery.md) first for the file, the item form, the buckets
-and their caps, the ledger, and the stated rule for a shipped item. A file with no ids
-and no buckets is not a defect to fix: it gets the deletion pass below, and no invented
-id scheme.
-
-## Re-derive before editing
-
-```bash
-git log --oneline <last-tag>..HEAD
-```
-
-Use `HEAD`, or the branch the project documents as its default — a project's branch is
-not always `main`. Read the changelog's newest dated heading beside it: the window is
-everything that landed, and the release is what a reader has. A project with no tags has
-no window at all: re-derive from the newest dated heading and the tree instead, and say
-that is what you did. An item is not "shipped" because a branch merged — the tree
-decides whether the promise is met, the maintainer decides whether it shipped.
-
-Then, for every item in the file, open the code it names. Three outcomes:
-
-- **The tree does it.** Delete the item, and record the reason where it was — one line
-  is enough, and it is what stops the same item being re-added next review. A file with
-  its own history or "previous `Now`" section gets the note there instead.
-- **The tree does part of it.** Rewrite the item down to the part still missing. A
-  condensed item is a finding; a deleted one that was not done is a lost promise.
-- **The tree contradicts it** — the approach changed, or the problem was solved another
-  way. Delete it with that reason. Parking it as "still available" describes a tree
-  that no longer exists.
-
-Never tick an item and leave it. A checklist with finished rows is a changelog written
-in the wrong file, and it is what the project's own rule usually forbids.
-
-## Renumber and fix every citation
-
-After a deletion, ids break in four places, and all four move in the same edit:
-
-- The item headings, so a prefix's numbers stay contiguous.
-- Every reference elsewhere in the file — a ledger row, a "if only two things ship"
-  list, a `P1–P3` range whose endpoints both still resolve.
-- Every mention in the guides, the front door, and the instruction file, which is what
-  a stale id breaks first because nothing validates it.
-- The relative links and `path:line` citations the items carry.
-
-Change an id only when a deletion forces it. Renumbering for tidiness loses the
-citations the file's readers already have.
-
-## Keep the buckets honest
-
-- A bucket over the cap the file states is a priority list that stopped being one:
-  demote an item rather than widening the cap.
-- A horizon whose exit condition has been met gets rewritten, not left as decoration.
-- A ledger row whose items have all closed is closed; an open item with no ledger row
-  gets one, or it is not part of a promise.
-
-## Numbers belong to the tree
-
-Any count the file states about the code — modules, extensions, tools, screens — is
-read from the tree, not adjusted by hand. A project that derives it in a guard has the
-count already: run the guard, and change the tree or the guard, never the number. A
-project that does not is a finding for the audit, and the fix is a guard.
-
-## Non-goals are decisions
-
-The non-goal list carries a reason per entry. When the changelog, a discussion, or the
-audit contradicts one, that is a decision for the maintainer: list it, with the
-evidence, and ask. Reversing a documented non-goal is not a roadmap edit, and an item
-that needs one reversed says so in the item.
-
-## Report
-
-Every edit named by the item it touched: deleted, rewritten, renumbered, or cited.
-Then the items that need a decision, one line each. A roadmap whose window changed and
-whose items are all still true is a valid result — say so instead of finding work to
-look thorough.
-
-## In this repository
-
-- `ROADMAP.md` states its own rules under *How items are ordered*: an item is deleted
-  when it ships, never ticked, and `Now` and `Next` hold at most ten.
-- `test/roadmap.test.ts` pins the mechanical half — id uniqueness and contiguity, the
-  links, the citations, and the caps — and cannot tell that an item has shipped, which
-  is why the file states that rule in prose.
-- `AGENTS.md` requires the deletion or renumbering in the same commit as the change.
-
-The paths are named, not linked: a skill is installed into projects that do not
-contain them, so a link would point nowhere from the place it is read.

package/skills/project-docs/scripts/state.ts

@@ -1,316 +0,0 @@
-/**
- * Changelog state, for the `project-docs` skill.
- *
- * The skill's judgement is the model's; the counting is not. This prints what a
- * changelog can be asked mechanically — the file, the last tag, the commits since it,
- * the `[Unreleased]` categories, the empty and duplicate headings, the scope prefixes
- * in use, and the link references — so an audit starts from facts instead of a
- * hand-run `git log` whose flags and column are remembered differently each time.
- *
- * It ships inside the skill and resolves against the skill's own directory, so it
- * imports nothing from the package's `lib/`: an installed copy has `skills/` and
- * nothing else.
- *
- * Usage: `bun <skill>/scripts/state.ts [dir]`
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
-
-/** One `###` category under `[Unreleased]`, as the file spells it. */
-export interface Category {
-	/** The heading text, exactly as written: `Fixed`, not `Fix`. */
-	name: string;
-	/** 1-based line of the heading. */
-	line: number;
-	/** Top-level bullets between this heading and the next one. */
-	bullets: number;
-}
-
-/** What the file's text alone says; `gitFacts` adds the part that needs a repository. */
-export interface State {
-	/** Whether the first paragraphs name Keep a Changelog and Semantic Versioning. */
-	keepAChangelog: boolean;
-	/** The `[Unreleased]` section, when the file keeps one. */
-	unreleased?: { line: number; categories: Category[]; bullets: number };
-	/** Every dated `## [X.Y.Z]` heading, newest first, which is the order released sections appear in. */
-	dated: { version: string; line: number }[];
-	/** A heading text used twice inside one section, with every line it occurs on. */
-	duplicates: { name: string; lines: number[] }[];
-	/** Scope prefixes and how often each appears, most used first. */
-	scopes: { name: string; count: number }[];
-	/** The link references the file defines, lowercased, and the dated sections that lack one. */
-	refs: { unreleased: boolean; dated: number; missing: string[] };
-}
-
-/** What the repository adds: the tag the window starts at, and what is in the window. */
-export interface GitFacts {
-	/** The newest tag, when the repository has one. */
-	tag?: string;
-	/** Subject lines of the non-merge commits since the tag, newest first. */
-	commits: string[];
-	/** Why a fact is absent, in words the report can print: no repository, no tags. */
-	note?: string;
-}
-
-/** Keep a Changelog's `## [Unreleased]`, and the un-bracketed spelling some files use. */
-const UNRELEASED = /^\[?unreleased\]?$/i;
-/** A dated section heading: `[0.17.0] - 2025-06-01`, `0.17.0`, or a project's own suffix. */
-const DATED = /^\[?(\d+\.\d+\.\d+[^\s\]]*)\]?/;
-const HEADING = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
-const FENCE = /^\s*(?:```|~~~)/;
-const BULLET = /^[-*+]\s+/;
-/** A bullet's scope: backticked, bold, or a bare `area:` prefix. Not a path, and not prose. */
-const SCOPE = /^[-*+]\s+(?:`([^`]+)`|\*\*([^*]+)\*\*|([A-Za-z][A-Za-z0-9./-]{0,24}))\s*:/;
-const LINK_REF = /^\[([^\]]+)\]:\s*\S+/;
-
-/** Report caps, so a long history stays one screen. */
-export const MAX_COMMITS = 40;
-export const MAX_SCOPES = 6;
-
-interface Heading {
-	level: number;
-	text: string;
-	line: number;
-}
-
-/** The changelog a project root holds, in the order projects name one. */
-export const CHANGELOG_NAMES = [
-	"CHANGELOG.md",
-	"CHANGELOG",
-	"CHANGES.md",
-	"HISTORY.md",
-	"NEWS.md",
-	join("docs", "CHANGELOG.md"),
-	join("docs", "changelog.md"),
-];
-
-/** The first changelog file in `dir`, as an absolute path, or undefined when it has none. */
-export function findChangelog(dir: string): string | undefined {
-	const root = resolve(dir);
-	for (const name of CHANGELOG_NAMES) {
-		const candidate = join(root, name);
-		if (existsSync(candidate)) return candidate;
-	}
-	return undefined;
-}
-
-/** Every heading outside a fence, so a `## example` in a code block is not a section. */
-function headingsOf(markdown: string): Heading[] {
-	const headings: Heading[] = [];
-	let fenced = false;
-	markdown.split("\n").forEach((text, index) => {
-		if (FENCE.test(text)) {
-			fenced = !fenced;
-			return;
-		}
-		if (fenced) return;
-		const match = HEADING.exec(text);
-		if (match !== null) headings.push({ level: match[1].length, text: match[2].trim(), line: index + 1 });
-	});
-	return headings;
-}
-
-/** The scope a bullet leads with, if it leads with one. */
-function scopeOf(line: string): string | undefined {
-	const match = SCOPE.exec(line);
-	if (match === null) return undefined;
-	return (match[1] ?? match[2] ?? match[3]).trim();
-}
-
-/** Bullet count and scopes over the given 1-based inclusive line window, outside fences. */
-function scanBullets(lines: readonly string[], start: number, end: number): { bullets: number; scopes: string[] } {
-	let bullets = 0;
-	const scopes: string[] = [];
-	let fenced = false;
-	for (let line = start; line <= end && line <= lines.length; line++) {
-		const text = lines[line - 1];
-		if (FENCE.test(text)) {
-			fenced = !fenced;
-			continue;
-		}
-		if (fenced || !BULLET.test(text)) continue;
-		bullets++;
-		const scope = scopeOf(text);
-		if (scope !== undefined) scopes.push(scope);
-	}
-	return { bullets, scopes };
-}
-
-/** Read the file's text into the facts the report prints. Pure, so a fixture can drive it. */
-export function readState(markdown: string): State {
-	const lines = markdown.split("\n");
-	const headings = headingsOf(markdown);
-	const preamble = lines.slice(0, 20).join("\n");
-
-	const unreleasedAt = headings.findIndex((heading) => heading.level === 2 && UNRELEASED.test(heading.text));
-	const dated = headings
-		.filter((heading) => heading.level === 2)
-		.flatMap((heading) => {
-			const version = DATED.exec(heading.text)?.[1];
-			return version === undefined ? [] : [{ version, line: heading.line }];
-		});
-
-	const scopes = new Map<string, number>();
-	for (const scope of scanBullets(lines, 1, lines.length).scopes) {
-		scopes.set(scope, (scopes.get(scope) ?? 0) + 1);
-	}
-
-	const duplicates = duplicateHeadings(headings);
-
-	const refs = new Map<string, number>();
-	for (const line of lines) {
-		const name = LINK_REF.exec(line)?.[1];
-		if (name !== undefined) refs.set(name.toLowerCase(), (refs.get(name.toLowerCase()) ?? 0) + 1);
-	}
-
-	let unreleased: State["unreleased"];
-	if (unreleasedAt !== -1) {
-		const heading = headings[unreleasedAt];
-		const nextSection = headings.slice(unreleasedAt + 1).find((entry) => entry.level <= 2);
-		const windowEnd = nextSection === undefined ? lines.length : nextSection.line - 1;
-		const inner = headings.filter((entry) => entry.line > heading.line && entry.line <= windowEnd);
-		const categories: Category[] = [];
-		inner
-			.filter((entry) => entry.level === 3)
-			.forEach((entry, index) => {
-				const next = inner.filter((item) => item.level === 3)[index + 1];
-				const categoryEnd = next === undefined ? windowEnd : next.line - 1;
-				categories.push({
-					name: entry.text,
-					line: entry.line,
-					bullets: scanBullets(lines, entry.line + 1, categoryEnd).bullets,
-				});
-			});
-		unreleased = {
-			line: heading.line,
-			categories,
-			bullets: categories.reduce((total, category) => total + category.bullets, 0),
-		};
-	}
-
-	return {
-		keepAChangelog: /keep a changelog/i.test(preamble) && /semantic versioning/i.test(preamble),
-		unreleased,
-		dated,
-		duplicates,
-		scopes: [...scopes.entries()]
-			.map(([name, count]) => ({ name, count }))
-			.sort((a, b) => b.count - a.count || a.name.localeCompare(b.name)),
-		refs: {
-			unreleased: refs.has("unreleased"),
-			dated: dated.length,
-			missing: dated.filter((entry) => !refs.has(entry.version.toLowerCase())).map((entry) => entry.version),
-		},
-	};
-}
-
-/** A trim with an ellipsis, so one long line cannot wrap the report. */
-function clip(text: string, width: number): string {
-	return text.length > width ? `${text.slice(0, width - 1)}…` : text;
-}
-
-/**
- * A heading repeated inside one section, which is what a reader sees as one category
- * split in two. The same `### Fixed` under each release is the format working, not a
- * duplicate, so headings are grouped by the `##` section that contains them.
- */
-function duplicateHeadings(headings: readonly Heading[]): { name: string; lines: number[] }[] {
-	const groups = new Map<string, { name: string; lines: number[] }>();
-	let section = "top";
-	for (const heading of headings) {
-		if (heading.level <= 2) section = heading.level === 2 ? heading.text.toLowerCase() : "top";
-		const key = `${section}\u0000${heading.text.toLowerCase()}`;
-		const group = groups.get(key) ?? { name: heading.text, lines: [] };
-		group.lines.push(heading.line);
-		groups.set(key, group);
-	}
-	return [...groups.values()].filter((group) => group.lines.length > 1);
-}
-
-/**
- * The report. Every line is a fact with its source, in the order an audit uses them:
- * the file, the window, the unreleased section, then what is wrong with the file, then
- * what the window contains.
- */
-export function formatState(file: string, state: State, git: GitFacts): string {
-	const out: string[] = [];
-	const preamble = state.keepAChangelog ? "Keep a Changelog preamble" : "no Keep a Changelog preamble";
-	out.push(`changelog   ${file} · ${preamble}`);
-
-	const count = `${git.commits.length} commit${git.commits.length === 1 ? "" : "s"} since, merges skipped`;
-	out.push(`last tag    ${git.tag === undefined ? (git.note ?? "no tags") : `${git.tag} · ${count}`}`);
-
-	out.push(
-		state.unreleased === undefined
-			? "unreleased  missing: the file has no `[Unreleased]` section"
-			: `unreleased  line ${state.unreleased.line} · ${state.unreleased.bullets} bullets`,
-	);
-	if (state.unreleased !== undefined) {
-		const named = state.unreleased.categories.map((category) => `${category.name} ${category.bullets}`);
-		out.push(`categories  ${named.length === 0 ? "none" : named.join(" · ")}   (file order)`);
-		const empty = state.unreleased.categories.filter((category) => category.bullets === 0).map((item) => item.name);
-		out.push(`empty       ${empty.length === 0 ? "none" : empty.join(" · ")}`);
-	}
-	out.push(
-		state.duplicates.length === 0
-			? "duplicate   none"
-			: `duplicate   ${state.duplicates
-					.slice(0, 4)
-					.map((entry) => `${entry.name} at lines ${entry.lines.join(", ")}`)
-					.join(" · ")}`,
-	);
-	const scopes = state.scopes.slice(0, MAX_SCOPES).map((entry) => `${entry.name} ${entry.count}`);
-	const rest = state.scopes.length - MAX_SCOPES;
-	out.push(
-		`scopes      ${scopes.length === 0 ? "none" : `${scopes.join(" · ")}${rest > 0 ? ` · … ${rest} more` : ""}`}`,
-	);
-	out.push(
-		`refs        [Unreleased] ${state.refs.unreleased ? "yes" : "no"} · dated refs ${state.refs.dated - state.refs.missing.length}/${state.refs.dated}${
-			state.refs.missing.length === 0 ? "" : `, missing ${state.refs.missing.slice(0, 5).join(", ")}`
-		}`,
-	);
-
-	if (git.commits.length > 0) {
-		out.push(`commits since ${git.tag ?? "the beginning"}`);
-		for (const commit of git.commits.slice(0, MAX_COMMITS)) out.push(`  ${clip(commit, 110)}`);
-		const more = git.commits.length - MAX_COMMITS;
-		if (more > 0) out.push(`  … ${more} more`);
-	}
-	return `${out.join("\n")}\n`;
-}
-
-/** Run one git command, returning its trimmed stdout or a reason it produced none. */
-function git(args: readonly string[], cwd: string): { text?: string; error?: string } {
-	const result = Bun.spawnSync({ cmd: ["git", ...args], cwd, stdout: "pipe", stderr: "pipe" });
-	if (result.exitCode !== 0) return { error: result.stderr.toString().trim() || `git ${args[0]} failed` };
-	return { text: result.stdout.toString().trim() };
-}
-
-/**
- * The tag to audit from, and the non-merge commits after it. A repository with no
- * tags has no window, and a directory outside git has neither; both are reported as a
- * note rather than an error, because the file half of the report is still useful.
- */
-export function gitFacts(cwd: string): GitFacts {
-	const inside = git(["rev-parse", "--is-inside-work-tree"], cwd);
-	if (inside.text !== "true") return { commits: [], note: "not a git repository" };
-
-	const described = git(["describe", "--tags", "--abbrev=0"], cwd);
-	const tag = described.text === "" ? undefined : described.text;
-	const range = tag === undefined ? ["HEAD"] : [`${tag}..HEAD`];
-	const log = git(["log", "--no-merges", "--format=%h %s", ...range], cwd);
-	const commits = (log.text ?? "").split("\n").filter((line) => line.trim() !== "");
-	return { tag, commits, note: tag === undefined ? "no tags" : undefined };
-}
-
-if (import.meta.main) {
-	const dir = resolve(process.argv[2] ?? ".");
-	const changelog = findChangelog(dir);
-	if (changelog === undefined) {
-		console.error(`no changelog in ${dir}: looked for ${CHANGELOG_NAMES.join(", ")}`);
-		process.exit(1);
-	}
-	const state = readState(readFileSync(changelog, "utf-8"));
-	process.stdout.write(formatState(relative(dir, changelog), state, gitFacts(dir)));
-}