@akagilnc/pi-workflow-roles 0.1.4403 → 0.1.4419

package/resources/methods/code-review/SKILL.md

@@ -1,92 +0,0 @@
----
-name: code-review
-description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
----
-
-Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
-
-- **Standards** — does the code conform to this repo's documented coding standards?
-- **Spec** — does the code faithfully implement the originating issue / spec?
-
-Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
-
-This package method must remain usable without Matt setup files and must **not** modify project governance as setup. Do **not** run `/setup-matt-pocock-skills`, write `docs/agents/issue-tracker.md`, or create other project governance files to "prepare" the review.
-
-Review is independent of product repair: keep scratch probes, fixtures, and temporary investigation artifacts distinguishable from fixed-target facts, and never turn the review into product repairs, commits, or governance edits.
-
-## Process
-
-### 1. Pin the fixed point
-
-Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
-
-Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
-
-Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.
-
-### 2. Identify the spec source
-
-Look for the originating spec, in this order:
-
-1. Spec or issue material the caller already supplied (task text, admitted attachments, or explicit paths in the request).
-2. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch only when a working tracker is already available without setup; do not install or write tracker config.
-3. A path the user passed as an argument.
-4. A pre-existing spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
-5. If nothing is found, treat Spec as not established: the **Spec** axis skips substantive requirements checking and reports "no spec available". Do not invent a spec and do not mutate the repository to create one.
-
-### 3. Identify the standards sources
-
-Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
-
-On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
-
-- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
-- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
-
-Each smell reads *what it is* → *how to fix*; match it against the diff:
-
-- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
-- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
-- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
-- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
-- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
-- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
-- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
-- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
-- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
-- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
-- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
-- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
-
-### 4. Spawn both sub-agents in parallel
-
-Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
-
-**Standards sub-agent prompt** — provide:
-
-- The full diff command and commit list.
-- Typed, traceable references to every standards-source file found in step 3, plus the complete Fowler smell baseline from this Skill. The sub-agent must actually read those supplied references; a path/digest-bound bundle is equivalent to inline material.
-- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
-
-**Spec sub-agent prompt** — provide:
-
-- The diff command and commit list.
-- A typed, traceable reference to the actual spec bytes. The sub-agent must read the supplied spec material before judging it; a path/digest-bound bundle is equivalent to inline material.
-- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
-
-If the spec is missing, skip the Spec sub-agent and note this in the final report.
-
-### 5. Aggregate
-
-Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
-
-End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
-
-## Why two axes
-
-A change can pass one axis and fail the other:
-
-- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
-- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
-
-Reporting them separately stops one axis from masking the other.

package/resources/methods/code-review/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Code Review"
-  short_description: "Review a diff on standards and spec"

package/resources/methods/code-review/provenance.json

@@ -1,26 +0,0 @@
-{
-  "name": "code-review",
-  "kind": "role-method-skill",
-  "upstream": {
-    "repository": "https://github.com/mattpocock/skills",
-    "path": "skills/engineering/code-review",
-    "commit": "8b36d4fb2635b3c21998dcd8144439c9e5ba7302",
-    "tag": "v1.2.2",
-    "license": "MIT",
-    "copyright": "Copyright (c) 2026 Matt Pocock",
-    "attribution": "mattpocock/skills"
-  },
-  "packageAdaptation": "reviewer-no-setup-fixed-target-two-axis",
-  "files": {
-    "SKILL.md": {
-      "sha256": "17840093c3a69ebffa3a3bd9582f6a944fa58623df6a65481d5a1dc2a85dd913",
-      "byteLength": 7588,
-      "gitBlob": "768371d43a38fadf2657ff890cca5fc2b038b7e1"
-    },
-    "agents/openai.yaml": {
-      "sha256": "8229ca854e11dc8e6aef2131ee03f31fb1561cf905fab9ccc325180cf3331352",
-      "byteLength": 100,
-      "gitBlob": "9076774ba327f49068db9273feceda03bfe940fa"
-    }
-  }
-}

package/src/adr-path-refs.ts

@@ -1,25 +0,0 @@
-/**
- * Shared docs/adr path extraction from free text (issue body / ticket face).
- * Single authority for reviewer Spec discovery.
- *
- * Shape only: segments under docs/adr/ without `..` or empty parts. Real IO
- * confinement still lives at the read seam (ADR 0038).
- */
-
-/** docs/adr paths referenced inside free text (order of first appearance). */
-// Each segment must start with alnum so `.` / `..` traversal claims never match.
-const ADR_PATH_IN_BODY =
-  /docs\/adr\/(?:[A-Za-z0-9][A-Za-z0-9._-]*\/)*[A-Za-z0-9][A-Za-z0-9._-]*\.md/g;
-
-/** Extract unique docs/adr/*.md paths; preserve first-seen order. */
-export function extractReferencedAdrPaths(text: string): readonly string[] {
-  const seen = new Set<string>();
-  const paths: string[] = [];
-  for (const match of text.matchAll(ADR_PATH_IN_BODY)) {
-    const path = match[0]!;
-    if (seen.has(path)) continue;
-    seen.add(path);
-    paths.push(path);
-  }
-  return Object.freeze(paths);
-}

package/src/public-cli/reviewer-dispatch-rejection.ts

@@ -1,106 +0,0 @@
-/**
- * Durable Reviewer-rejection child→parent page under AK_ROLE_RUN_DIR.
- * Stays in public-cli (AK artifact owner); role-runtime imports this neighbor.
- */
-import { writeFileSync } from "node:fs";
-import { readFile, unlink } from "node:fs/promises";
-import { join } from "node:path";
-
-import type { RoleTurnKnownFailure } from "../host-contracts.ts";
-import {
-  REVIEWER_PREFLIGHT_VIOLATIONS,
-  type ReviewerPreflightViolation,
-} from "../reviewer-dispatch.ts";
-
-const REVIEWER_DISPATCH_REJECTION_FILE = "typed-known-failure.json";
-
-function isReviewerPreflightViolation(value: unknown): value is ReviewerPreflightViolation {
-  return (
-    typeof value === "string" &&
-    (REVIEWER_PREFLIGHT_VIOLATIONS as readonly string[]).includes(value)
-  );
-}
-
-function reviewerDispatchRejectionPath(runDirectory: string): string {
-  return join(runDirectory, REVIEWER_DISPATCH_REJECTION_FILE);
-}
-
-/**
- * Clear any prior attempt's Reviewer rejection page so resume/retry cannot
- * inherit a stale knownFailure.details.
- */
-export async function clearReviewerDispatchRejection(runDirectory: string): Promise<void> {
-  try {
-    await unlink(reviewerDispatchRejectionPath(runDirectory));
-  } catch (error) {
-    if (
-      error instanceof Error &&
-      "code" in error &&
-      (error as { code?: unknown }).code === "ENOENT"
-    ) {
-      return;
-    }
-    throw error;
-  }
-}
-
-/**
- * Synchronous durable write for Reviewer dispatch rejection (child process exit is sync).
- * Parent public CLI recovers via readReviewerDispatchRejection into knownFailure.
- */
-export function recordReviewerDispatchRejectionSync(
-  runDirectory: string,
-  rejection: Readonly<{
-    diagnostic: string;
-    violations: readonly ReviewerPreflightViolation[];
-  }>,
-): void {
-  writeFileSync(
-    reviewerDispatchRejectionPath(runDirectory),
-    `${JSON.stringify(rejection)}\n`,
-    "utf8",
-  );
-}
-
-/** Recover a child-written Reviewer dispatch rejection through a fixed mapping. */
-export async function readReviewerDispatchRejection(
-  runDirectory: string,
-): Promise<RoleTurnKnownFailure | undefined> {
-  let raw: string;
-  try {
-    raw = await readFile(reviewerDispatchRejectionPath(runDirectory), "utf8");
-  } catch (error) {
-    if (
-      error instanceof Error &&
-      "code" in error &&
-      (error as { code?: unknown }).code === "ENOENT"
-    ) {
-      return undefined;
-    }
-    throw error;
-  }
-  const parsed: unknown = JSON.parse(raw);
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    const error = new Error("Reviewer dispatch rejection page must be a JSON object");
-    error.name = "ReviewerDispatchRejectionContractError";
-    throw error;
-  }
-  const record = parsed as Record<string, unknown>;
-  if (
-    typeof record.diagnostic !== "string" ||
-    record.diagnostic.trim() === "" ||
-    !Array.isArray(record.violations) ||
-    record.violations.length === 0 ||
-    record.violations.some((value) => !isReviewerPreflightViolation(value))
-  ) {
-    const error = new Error("Reviewer dispatch rejection page has unusable required fields");
-    error.name = "ReviewerDispatchRejectionContractError";
-    throw error;
-  }
-  return {
-    cause: "activation",
-    diagnostic: record.diagnostic,
-    identity: { name: "ReviewerDispatchRejectionError" },
-    details: { violations: Object.freeze([...record.violations]) },
-  };
-}

package/src/reviewer-dispatch.ts

@@ -1,39 +0,0 @@
-/**
- * #836 删 8: no code-compiled axis dispatch.
- * Parent seat invokes packaged code-review skill; this module does not construct or run children.
- */
-export {
-  branchNamesAtPinnedHead,
-  createReviewerPinnedGitReader,
-  immutableReviewerPin,
-  type ReviewerPinnedGitReader,
-  type ReviewerPinnedTarget,
-  type ReviewerRange,
-} from "./reviewer-pinned-git.ts";
-export { extractReferencedAdrPaths } from "./adr-path-refs.ts";
-export { sha256Hex } from "./sha256.ts";
-export {
-  isReviewerPromptText as isReviewerPromptIdentity,
-  sameReviewerPromptText as sameReviewerPromptIdentity,
-  type ReviewerPromptText as ReviewerPromptIdentity,
-} from "./reviewer-prompt-identity.ts";
-
-export type ReviewerIssueFetchResult = Readonly<{
-  number: number;
-  title?: string;
-  body?: string;
-}>;
-
-export type ReviewerIssueFetcher = (input: {
-  repo: string;
-  ticketNumber: number;
-  signal?: AbortSignal;
-}) => Promise<ReviewerIssueFetchResult | undefined>;
-
-export const REVIEWER_PREFLIGHT_VIOLATIONS = [
-  "base-invalid",
-  "range-invalid",
-  "prompt-identity-invalid",
-  "target-drift",
-] as const;
-export type ReviewerPreflightViolation = (typeof REVIEWER_PREFLIGHT_VIOLATIONS)[number];

package/src/reviewer-git-snapshot.ts

@@ -1,45 +0,0 @@
-export const REVIEW_REF_PREFIXES = ["refs/heads", "refs/tags", "refs/remotes"] as const;
-
-/** Closed identity for a ref: annotated tags retain both tag object and peeled commit. */
-export type ReviewerRefEntry = Readonly<{
-  objectId: string;
-  peeledCommitId: string | null;
-}>;
-export type ReviewerRefMap = Readonly<Record<string, ReviewerRefEntry>>;
-
-export function parseReviewerRefSnapshot(raw: string): Record<string, ReviewerRefEntry> {
-  const refs: Record<string, ReviewerRefEntry> = {};
-  for (const line of raw.split("\n")) {
-    if (!line) continue;
-    const fields = line.split("\0");
-    if (fields.length !== 5 || !fields[0] || !fields[1] || !fields[3]) {
-      throw new Error(`Malformed Git ref snapshot line: ${line}`);
-    }
-    const peeledCommitId = fields[3] === "commit"
-      ? fields[1]
-      : fields[4] === "commit" && fields[2] ? fields[2] : null;
-    refs[fields[0]] = Object.freeze({
-      objectId: fields[1],
-      peeledCommitId,
-    });
-  }
-  return refs;
-}
-
-export function reviewerRefSnapshotArgs(): string[] {
-  return ["for-each-ref", "--format=%(refname)%00%(objectname)%00%(*objectname)%00%(objecttype)%00%(*objecttype)", ...REVIEW_REF_PREFIXES];
-}
-
-export function immutableReviewerRefs(refs: ReviewerRefMap): ReviewerRefMap {
-  return Object.freeze(Object.fromEntries(Object.entries(refs)
-    .sort(([a], [b]) => a.localeCompare(b))
-    .map(([name, entry]) => [name, Object.freeze({ objectId: entry.objectId, peeledCommitId: entry.peeledCommitId })])));
-}
-
-export function sameReviewerPinnedTarget(
-  actual: Readonly<{ repositoryRoot: string; objectFormat: "sha1" | "sha256"; targetHead: string; refs?: ReviewerRefMap }>,
-  expected: Readonly<{ repositoryRoot: string; objectFormat: "sha1" | "sha256"; targetHead: string; refs?: ReviewerRefMap }>,
-): boolean {
-  return actual.repositoryRoot === expected.repositoryRoot && actual.objectFormat === expected.objectFormat &&
-    actual.targetHead === expected.targetHead;
-}