@defrex/autobuild 0.8.0

package/packages/core/src/zod-issues.ts

@@ -0,0 +1,91 @@
+/**
+ * Moving zod issues across a validation boundary without losing what zod
+ * reported, and expanding what a renderer cannot present as-is.
+ *
+ * A nested `safeParse` whose issues are relayed by hand — the shape every
+ * `z.transform` that validates a sub-value ends up in — is where detail goes to
+ * die. Re-encoding each issue as `{ code: 'custom', message }` keeps the prose
+ * and silently discards everything structured: `unrecognized_keys.keys`,
+ * `invalid_type.expected`, and, decisively, `invalid_union.errors`, which is
+ * where an untagged `z.union` keeps the entire reason it rejected the value.
+ * Its own `message` is the bare "Invalid input", so re-encoding turns a precise
+ * rejection into no information at all.
+ *
+ * The split is deliberate: `forwardIssues` relays, `expandIssues` presents.
+ * Forwarding keeps validation honest without deciding prose; expanding is what
+ * makes union branch detail reach a human, and belongs at operator-facing
+ * renderer boundaries rather than inside a validator.
+ */
+import type { z } from 'zod'
+
+/**
+ * The slice of zod's `$RefinementCtx` a transform needs to report issues.
+ *
+ * Taken from zod rather than hand-written: its `addIssue` already accepts every
+ * issue code — an issue this codebase raises (`{ code: 'custom', message }`,
+ * path optional because zod anchors it) and one relayed from an inner parse
+ * alike. Restating it as a `custom`-only shape is what made re-encoding look
+ * like the only option at each of these boundaries.
+ */
+export type IssueSink = Pick<z.core.$RefinementCtx, 'addIssue'>
+
+/**
+ * Relay every issue from an inner parse to an outer context verbatim, with only
+ * its path prefixed to anchor it where the inner value sits.
+ *
+ * Verbatim is the point. Each issue keeps its own code and its code-specific
+ * payload, so a caller downstream — the config loader's `unrecognized_keys`
+ * migration hints, `expandIssues`' union expansion — still sees what zod
+ * actually decided rather than a `custom` issue carrying prose.
+ */
+export function forwardIssues(
+  issues: readonly z.core.$ZodIssue[],
+  ctx: IssueSink,
+  prefix: PropertyKey[] = [],
+): void {
+  for (const issue of issues) {
+    ctx.addIssue({ ...issue, path: [...prefix, ...issue.path] })
+  }
+}
+
+/**
+ * Replace each union issue that carries branch detail with one issue per branch
+ * leaf, so a renderer that prints `path: message` prints why every alternative
+ * was rejected instead of the bare "Invalid input".
+ *
+ * A leaf keeps its real path (the union's, then its own) and its real code, so
+ * path-and-code-driven post-processing downstream still sees a real issue. Only
+ * the message is synthesized, and only by prefixing `option N of M:`.
+ *
+ * Expansion happens ONLY when it yields at least one leaf; otherwise the issue
+ * passes through untouched. That single rule is the whole tagged-choice
+ * guarantee: a `z.discriminatedUnion` that matches no tag reports
+ * `invalid_union` with `errors: []` and a message that already names the
+ * expected tags, so it has nothing to expand and renders exactly as it did
+ * before. Nesting recurses — a union inside a union yields leaves carrying both
+ * markers.
+ *
+ * `invalid_key` and `invalid_element` nest issues the same way. Neither reaches
+ * the currently covered config, plugin-manifest, findings, or ticket-update
+ * renderers, so they are left alone rather than handled speculatively.
+ */
+export function expandIssues(issues: readonly z.core.$ZodIssue[]): z.core.$ZodIssue[] {
+  const expanded: z.core.$ZodIssue[] = []
+  for (const issue of issues) {
+    const leaves = issue.code === 'invalid_union' ? unionLeaves(issue) : []
+    if (leaves.length > 0) expanded.push(...leaves)
+    else expanded.push(issue)
+  }
+  return expanded
+}
+
+function unionLeaves(issue: z.core.$ZodIssueInvalidUnion): z.core.$ZodIssue[] {
+  const branches = issue.errors
+  return branches.flatMap((branch, index) =>
+    expandIssues(branch).map((leaf) => ({
+      ...leaf,
+      path: [...issue.path, ...leaf.path],
+      message: `option ${index + 1} of ${branches.length}: ${leaf.message}`,
+    })),
+  )
+}

package/skills/code-review/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: code-review
+description: Review a build's implementation commits against its spec and plan. Invoked by the build-runner as the code-review phase; takes only the build slug.
+---
+
+# /ab-code-review <build>
+
+You are a fresh skeptic reviewing the diff. You have no memory of prior
+rounds by design. Your verdict travels the typed channel; prose you print
+goes nowhere.
+
+## Session shape
+
+1. Run `ab context`. You get `.ab/spec.md`, `.ab/plan.md`, the commit range
+   (`base`/`head` in `.ab/context.json`), `.ab/implement-notes.md`, and
+   `.ab/history/` with prior rounds' findings. When present,
+   `.ab/dismissed-findings.json` lists finding ids a human explicitly dismissed.
+2. Read the actual diff (`git diff <base>..<head>`), then the surrounding
+   code. Review what changed *and* what the change touches.
+3. Judge on exactly these axes, in this order:
+   - **Correctness** — bugs, broken edge cases, races, wrong behavior under
+     real inputs. This is most of your job. When the diff touches a
+     third-party API boundary, check the provider's own schema or reference
+     documentation for the actual request shapes, argument types, enum syntax,
+     and identifier constraints. Raise any mismatch or unverified assumption
+     as a concrete finding; memory, nearby adapter code, and green tests over a
+     fake or mock are not contract evidence because they can repeat the
+     author's assumption.
+   - **Spec conformance** — every acceptance criterion met; nothing beyond
+     the spec's scope smuggled in.
+   - **Tests** — do the new tests exercise the seams this change created or
+     moved? Would they fail if the change were wrong?
+   - **Fit** — matches the codebase's idioms; no needless indirection.
+4. Write `.ab/code-review.md`, then exactly one verdict:
+
+   ```
+   ab verdict approve --notes .ab/code-review.md
+   ab verdict revise --findings .ab/findings.json --notes .ab/code-review.md
+   ab verdict escalate --reason "…" --notes .ab/code-review.md
+   ```
+
+## Writing findings
+
+Same schema as every review (the CLI validates and stamps ids): `severity`
+(`blocking` | `important` | `minor`), optional `file`/`lines`, `summary`,
+optional `detail`, and `persists` — ids of prior-round findings this one
+continues.
+
+`persists` means the defect a prior finding named is still present in the
+work under review — not that a new problem falls in the same category as
+one already fixed. Test it that way: if the exact defect the prior finding
+named is gone, the chain ends there, however closely your new finding
+resembles it. A new instance of a defect class whose reported instance was
+fixed is fresh work and starts its own chain — raise it with no `persists`
+link. Mark honestly in both directions: neither re-litigate a resolved
+finding nor let a dodged one look fresh, because the kernel mechanically
+escalates a chain that persists too long, and a stalemate is the only
+thing that counter can usefully measure.
+
+A human-dismissed id is settled: do not re-raise that finding. If a genuinely
+different problem touches the same code, raise it with a new id and do not link
+`persists` into the dismissed chain; dismissal settles one disagreement, not
+the file.
+
+Each finding must name a concrete failure, not a preference. "This could be
+cleaner" is not a finding; "a sixth login attempt bypasses the limiter
+because the window key uses the unnormalized email" is.
+
+Severity measures proportion, not certainty. Rate a finding by what the
+defect costs against the spec's acceptance criteria and the realistic
+operating conditions of the work under review — never by how sure you are
+that it is a defect. Certainty is the bar for raising a finding at all; it
+says nothing about which level the finding belongs at.
+
+- `blocking` — name the acceptance criterion the defect defeats. Approving
+  would deliver work the spec does not accept.
+- `important` — name the acceptance criterion or stated invariant the defect
+  puts at material risk under realistic conditions, short of defeating it
+  outright.
+- `minor` — real and in scope, but nothing above turns on it.
+
+`blocking` and `important` both cost the producer a revision round, so if you
+cannot name that criterion or invariant, the finding does not belong at
+either level. A true defect that puts no acceptance criterion at risk, breaks
+no stated invariant, and is unreachable under realistic input is `ab observe`,
+not a finding — the same disposition an out-of-scope discovery gets.
+
+Do not raise a bar the spec set: where the spec bounds a failure model or an
+operating condition, conformance is measured against that bound, and a
+stricter model you would have chosen is not a defect. Hostile or pathological
+input that the surface's contract does not promise to handle is `minor` or an
+observation, unless a security boundary, an acceptance criterion, or a stated
+invariant makes it material.
+
+Approve when the implementation satisfies the spec and is sound — not when
+it is the diff you would have written. Known immaterial defects are not a
+reason to withhold approval — record them with `ab observe` and approve.
+Escalate only genuine judgment calls a human must make (the spec itself is
+wrong, a security tradeoff outside your authority). Out-of-scope discoveries
+are `ab observe`, never findings.

package/skills/finalize/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: finalize
+description: Prepare a green build's pull request description. Invoked by the build-runner as the finalize phase; takes only the build slug.
+---
+
+# /ab-finalize <build>
+
+The build is green: plan approved, code approved, every verify step passed.
+You write the PR description; the kernel opens the PR when you finish (you
+never touch the forge).
+
+## Session shape
+
+1. Run `ab context`. You get `.ab/spec.md`, `.ab/plan.md`, every verify report,
+   the repo's PR template config if one exists, and — when a human answered an
+   escalation this phase raised on an earlier attempt — `.ab/guidance.json`,
+   their answer to it.
+2. Write `.ab/pr-description.md`:
+   - **Title line first** — imperative, ≤ 70 chars, from the spec's what.
+   - **What & why** — from the spec, compressed for a human reviewer who
+     hasn't read it.
+   - **How** — the approach actually taken (from the plan and the implement
+     notes), including deviations from the plan.
+   - **Verification** — which verify steps ran and what they proved; note
+     anything a human should re-check by hand.
+   - Follow the PR template if the context includes one.
+   Do not paste the audit trail — the kernel's summary comment appends verdict
+   history and links into the store.
+3. Finish:
+
+   ```
+   ab artifact put pr-description .ab/pr-description.md
+   ab done
+   ```
+
+   `ab done` validates the deposit; the kernel opens the PR from it. One
+   terminal command; if validation fails, fix what it names and rerun.
+
+`.ab/guidance.json`, when present, is a human operator's answer to the
+escalation that blocked this build: the escalation id and the answer text. It
+is authoritative feedback for this attempt and the PR description must act on
+it, while the spec remains the contract this phase is measured against — if the
+two cannot both be satisfied, escalate instead of guessing. Finalize has no
+review round of its own, so guidance is the only feedback it ever receives.