DEV Community: Russell Jones

A missing npm ci silently starved the content-mining pipeline for a week

Russell Jones — Thu, 03 Sep 2026 11:44:10 +0000

Ahnii!

Earlier posts covered building and refining the automated content pipeline: a scheduled job scans recent commits, groups them by theme, and files GitHub issues as raw material for future posts. Every mined candidate gets validated against a JSON schema before the workflow files an issue for it — that's the guardrail that keeps malformed seeds out of the queue. For about a week, that guardrail silently dropped every candidate instead of filing a single one.

What Broke

The mining script, scripts/mine-git-activity.sh, builds a seed for each commit group and validates it with schemas/validate.js, which loads the ajv JSON Schema validator:

const Ajv = require('ajv');
const addFormats = require('ajv-formats');

ajv and ajv-formats are devDependencies in package.json, so they only exist after npm ci runs. The content-mine.yml workflow checked out the blog repo and ran the mining script directly — it never installed Node dependencies first. Every call to the validator hit Cannot find module 'ajv' and exited non-zero.

The script treated that crash the same as a real validation failure: reject the candidate, move on. No error surfaced anywhere. The workflow itself finished green, because the script's own exit code was still 0 — it just never filed anything. Net result: zero issues created, for about a week, and nothing in the logs said so unless you went looking.

Fix 1: Fail Open, Warn Loud

The first patch, in the blog repo, doesn't wait for CI to be fixed — it makes the script defend itself. Before validating anything, it checks whether the validator's dependencies actually resolve:

VALIDATOR_OK=1
if ! node -e "require('ajv'); require('ajv-formats')" >/dev/null 2>&1; then
  echo "WARN: schema-validator deps (ajv) not installed — creating issues WITHOUT seed validation. Add 'npm ci' to the mining workflow to restore validation." >&2
  VALIDATOR_OK=0
fi

Downstream, the validation gate becomes an or: skip validation and file the issue anyway if the deps aren't there, instead of letting the crash masquerade as "this candidate is invalid":

if [[ "$VALIDATOR_OK" == "0" ]] || $VALIDATOR mined-seed "$SEED_FILE" > /dev/null 2>&1; then
  # ...build and create the issue...

That's a deliberate trade: an unvalidated issue is a minor cleanup problem for a human curator. A silently starved queue is a week of lost content ideas nobody knew to chase. Given the choice, fail open and be loud about it.

Fix 2: Actually Install the Dependency

The warning fixes the symptom. The root cause was still the missing install step, patched separately in the content-mine.yml workflow (in jonesrussell/jonesrussell, the repo that owns the queue):

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: 'lts/*'
    cache: 'npm'

- name: Install dependencies (ajv for seed validation)
  run: npm ci

With that in place, validation runs for real again — the fail-open guard in fix 1 becomes a safety net for the next unrelated dependency gap, not a permanent workaround for this one.

What Changed, at a Glance

	Before	After
Missing `ajv`	Validator crashes, treated as "invalid," issue silently dropped	Absence detected up front, logs a `WARN`, issue still filed
Node deps in CI	Never installed	`actions/setup-node` + `npm ci` before the script runs
Failure visibility	None — 0 issues/week, workflow exits `0`	Explicit warning line in job logs

The Lesson

A script that "succeeds" by doing nothing is worse than one that fails loudly, because nothing pages you for it. The mining workflow's exit code was never wrong; it was just measuring the wrong thing. The mining job runs daily, so this wasn't one bad run — it was seven straight silent failures before the empty queue was noticeable on its own. Exit code isn't the metric that would have caught it. Throughput is: issues filed per run, checked against zero. That's the check I was missing.

Baamaapii

Idempotent, budget-bounded AI queries on a single SQLite writer

Russell Jones — Wed, 02 Sep 2026 14:22:30 +0000

Ahnii!

northway is a Go service that turns approved sources into small, ranked, source-backed news feeds for AI agents — one process, embedded SQLite, deployed Pi-first. Every feed query that reaches an AI provider costs real money, and a network retry or a crashed request must never turn into a second charge for the same query. internal/sqlite is what makes that guarantee hold: one writer, scoped credentials, a reserve-then-settle budget, and an idempotent claim lifecycle for the provider call itself.

One writer, strictly locked

Store owns a single SQLite file and refuses to share it. Open takes an flock-style exclusive lock on the database file and requires the directory to be private:

if !info.IsDir() || info.Mode().Perm()&0077 != 0 {
    return nil, "", errors.New("database directory must be private (0700) and not a symlink")
}

Writes go through one *sql.DB with _txlock=immediate, and a buffered channel (writeGate) serializes callers before any transaction opens:

func (s *Store) write(ctx context.Context, fn func(*sqlc.Queries) error) error {
    select {
    case s.writeGate <- struct{}{}:
    case <-ctx.Done():
        return ctx.Err()
    }
    defer func() { <-s.writeGate }()
    tx, err := s.writer.BeginTx(ctx, nil)
    ...
}

Reads use a separate read-only pool (query_only(1)) with up to two connections, so lookups never queue behind the write gate. WAL mode, foreign_keys(1), and synchronous(FULL) are all asserted — not just set — by Ready(), which fails startup if the file's actual pragmas don't match what the binary expects.

Scoped keys, one cross-tenant lookup

Every credential is tenant-scoped. identity.go stores a key's SHA-256 digest, never the key itself, and validates the full record shape before writing:

if key.TenantID != tenant || !identity.ValidKeyID(key.ID) || !key.Scopes.Valid() ||
    !validTimestamp(key.CreatedAt) || key.Digest == [32]byte{} ||
    key.LastUsedAt != nil || key.RevokedAt != nil {
    return errors.New("invalid key metadata")
}

LookupAPIKey is deliberately the only function in the package that resolves a key without an existing tenant scope — its own comment spells out the boundary: it "exposes no corpus data and is consumed only by identity.Service, never a public lookup endpoint." Everything downstream of that lookup — TouchAPIKey, RevokeAPIKey, every query and mutation — takes a tenant and checks access before touching a row.

Reserve first, settle later

Budgets are tracked in micros (LimitMicros, SpentMicros, HeldMicros) and set through an operator-only call:

func (s *Store) SetBudget(ctx context.Context, principal identity.Principal, limitMicros int64) error {
    tenant, err := principal.RequireOperator()
    ...
}

The spend itself never just decrements a counter after the fact. A query first reserves a worst-case amount; only once the real cost is known does it settle the difference back. That two-step is what makes an in-flight AI call safe to retry, fail, or recover from a crash without double-billing.

The query claim lifecycle

BeginQuery is the entry point, and it's built to be replay-safe. It hashes the caller's idempotency key together with the endpoint (sha256("POST /v1/feed-queries\x00" + key)) and looks for existing work under that hash:

Cache hit (same feed/corpus/entitlement/ranker revision as an existing snapshot) → returns the cached result, no budget touched.
Existing work found, same request digest → returns the in-progress or completed claim; a second call with the same key can never start a second paid attempt.
Existing work found, different request digest → ErrConflict. Reusing an idempotency key for a different request is rejected outright.
No existing work, budget configured → reserves policy.WorstCaseMicros and returns a WorkID the caller can use to actually invoke the provider.
No existing work, no budget → still creates work, but ProviderAllowed is false — the caller is limited to deterministic (non-AI) results.

The function's own comment is blunt about the safety property: "A replay never returns WorkID, so it cannot authorize another call."

From there, three methods carry a claim through its lifecycle:

Call	Precondition	Effect
`StartProvider`	work is `pending`, spend is `reserved`, lease not expired, scope unchanged	flips spend to `started` — must commit before the provider is actually called
`CompleteQuery`	work is `pending`, lease valid, feed/entitlement revision unchanged	validates every selected article against current storage, settles spend, writes an immutable snapshot
`FailQuery`	work is `pending`	settles the hold as `uncertain` if the provider had started, marks work `failed`

StartProvider's doc comment states the ordering guarantee directly: "An error/ambiguous commit never authorizes a call... No provider code runs inside storage." The database transaction is the gate, not the HTTP call to the provider.

CompleteQuery re-checks the feed's revision and each selected article's content hash before it will settle spend or write a snapshot — an unrelated ingest arriving mid-request can't get charged for or attached to a query that started against older data.

Recovering from crashes without guessing

Every claim carries a LeaseUntil. If a process dies mid-call, the spend is left in reserved or started, not silently lost or silently spent. RecoverQueries sweeps expired leases and fails them the same way FailQuery would — its comment notes it processes bounded batches and "preserves uncertain holds," since an operator later needs to reconcile those, not assume they were free.

That reconciliation is ReconcileQuery, and it requires actual evidence, not elapsed time, before it will move a hold out of uncertain:

if w.SpendState == "settled" {
    if w.ActualMicros.Int64 == actualMicros {
        return nil
    }
    return query.ErrConflict
}
if w.SpendState != "uncertain" {
    return query.ErrConflict
}

Repeating the same settlement is a safe no-op; a contradictory number is rejected outright rather than silently overwritten.

Timestamps get the same suspicion

Money isn't the only thing storage refuses to trust blindly. timestamps_test.go asserts that out-of-range values — before the epoch, past 9999-12-31, or offsets that push a boundary value across it — are rejected on write and never partially applied:

"positive wrap":    time.Date(600000, 1, 1, 0, 0, 0, 0, time.UTC),
"offset past end":  time.Date(9999, 12, 31, 23, 0, 0, 0, time.FixedZone("west", -3600)),

A rejected write leaves the row, its version history, and its full-text index completely unchanged — the test checks the version count and search index directly, not just the returned error.

Why this shape

None of this is exotic SQLite usage — WAL mode, a single writer, a lease column. What makes it hold together is that every step that touches money or identity states its own precondition in code, not just in a comment: wrong state, expired lease, mismatched revision, or a reused key against a different request all fail the transaction outright. For a Raspberry Pi-deployed, single-process service fronting paid AI calls, that's the difference between "retry-safe" as a claim and as a property you can point to in the diff.

Baamaapii

Hardening a manual Claude Code review workflow in GitHub Actions

Russell Jones — Wed, 02 Sep 2026 14:22:25 +0000

Ahnii!

goformx uses a mixed-provider workflow: Codex writes some pull requests, Claude writes others, and each gets reviewed by the other provider on request. The Claude side runs on the official Claude Code Action, triggered by a maintainer commenting @claude review on a PR. That sounds simple to wire up. It wasn't safe to wire up as-is, because the action's default "tag mode" is built for implementation, not read-only review — three gaps in the default, five fixes to close them.

Why the Default Example Wasn't Enough

The action ships an official progress-tracked review example that auto-triggers on every PR event and posts a tracked comment. It's a good starting point, but three things about tag mode don't fit a review-only job:

Tag mode is implementation-capable by default. It's designed for "@claude fix this," not "@claude look but don't touch."
GitHub Actions expression matching is case-insensitive. An if: condition comparing a comment body to @claude review will also match @Claude Review, @CLAUDE REVIEW, and anything else GitHub considers equal — not the exact trigger you intended.
Tool permissions in the SDK accumulate, they don't replace. Passing a restricted tool list doesn't override the mode's defaults; both apply, so an allow-list alone can't get you to read-only.

The workflow adapts the official example at a pinned action revision, keeps the manual-only trigger and subscription auth, and layers on the following fixes.

Fix 1: Enforce the Exact Trigger

The outer if: on the job is a first, cheap filter, but because Actions expressions are case-insensitive it can't be the whole check. A trusted actions/github-script preflight step re-validates everything in JavaScript before any model call happens:

const comment = context.payload.comment;
if (!context.payload.issue?.pull_request || comment?.body !== '@claude review' ||
    comment.user?.login !== 'jonesrussell' || comment.user?.type !== 'User' ||
    context.actor !== 'jonesrussell') {
  core.setFailed('An exact human maintainer review request is required.');
  return;
}

This rejects extra text, trailing newlines, wrong casing, bot comments, and anyone who isn't the maintainer — all before the job spends a single turn talking to Claude. It also checks that the PR is still open, and records head_sha/base_sha for later verification.

Fix 2: Bound the Diff, Fail Closed

Tag mode's native changed-file context is a file list, not a diff — Claude would have to reconstruct the actual changes from scratch. Instead, a setup step downloads the real diff to runner-temp storage with a hard size cap:

const {data: diff} = await github.rest.pulls.get({
  ...context.repo, pull_number: context.issue.number, mediaType: {format: 'diff'}
});
if (typeof diff !== 'string' || !diff.trim() || Buffer.byteLength(diff, 'utf8') > 1048576) {
  throw new Error('Review diff is missing, invalid or exceeds the 1 MiB review bound.');
}
require('node:fs').writeFileSync(diffPath, diff, {mode: 0o600, flag: 'wx'});

Missing, empty, or oversized diffs fail the job before Claude ever runs. The cap is 1 MiB; there's no silent fallback to a partial or truncated review.

Fix 3: Deny Tools Instead of Just Allowing Them

The SDK's argument parser accumulates allowedTools rather than replacing the mode defaults, so the workflow can't rely on an allow-list alone. It sets the permission mode explicitly, restricts built-in tools to Read, Glob, Grep, and layers an explicit deny list on top:

claude_args: >-
  --max-turns 16
  --permission-mode default
  --setting-sources user
  --strict-mcp-config
  --tools "Read,Glob,Grep"
  --disallowedTools "Bash,Edit,Write,NotebookEdit,Agent,Task,mcp__github_ci__*,mcp__github_file_ops__*"

Some of those denials cover capabilities that aren't even enabled at the pinned action revision. That's deliberate — defense against future defaults changing underneath the pin.

Fix 4: Keep Git Metadata Off Limits

Tag mode checks out the PR head and stores its short-lived job token in .git/config. A review agent with unrestricted Read could read that token straight out of the checkout. The workflow denies it explicitly in the action's settings:

{"disableAllHooks":true,"permissions":{"deny":["Read(./.git)","Read(./.git/**)"]}}

Denying reads to .git also blocks Grep/Glob from searching that directory, and hooks are disabled entirely so only user settings and the action's own MCP configuration load.

Fix 5: Catch Stale or Unverified Reviews

A successful job run isn't proof the review still applies. If the PR gets pushed to while Claude is reviewing it, the findings could describe a revision that no longer exists. A final step re-checks the PR's current head_sha/base_sha against what the preflight recorded, and confirms the local checkout matches too:

const checkedHead = require('node:child_process').execFileSync(
  'git', ['rev-parse', 'HEAD'], {encoding: 'utf8'}
).trim();
if (pr.state === 'open' && pr.head.sha === process.env.REVIEW_HEAD &&
    pr.base.sha === process.env.REVIEW_BASE && checkedHead === process.env.REVIEW_HEAD) return;

If any of those checks fail, the workflow posts a comment marking the review STALE or UNVERIFIED with a link to the run, and fails the job. That comment matters as much as the review itself — without it, a stale finding just sits there looking authoritative.

What Changed, at a Glance

Risk	Default tag mode	Hardened workflow
Trigger matching	Case-insensitive `if:` only	JS preflight enforces exact comment, author, PR state
Diff visibility	File list only	Downloaded diff, 1 MiB bound, fails closed
Tool access	Implementation-capable	`Read,Glob,Grep` only, explicit deny list
Git metadata	Job token readable in `.git/config`	`Read` denied for `.git` and its contents
Stale results	Not checked	Head/base/checkout re-verified, STALE comment on mismatch

Testing Without Spending a Turn

The workflow's own tests don't call the model at all. A separate CI job runs mocked-response tests against the preflight and revision-check logic, plus actionlint against both workflow files:

node --test .github/scripts/manual-review.test.cjs
go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12 -shellcheck= -pyflakes= \
  .github/workflows/manual-claude-review.yml .github/workflows/manual-review-tests.yml

That proves the guardrails and workflow syntax are correct. It doesn't prove the provider's runtime tool enforcement — a live @claude review request against an authorized PR is still the only way to confirm end to end that the final comment gets posted and failures are reported correctly.

Budget Stays Bounded Too

The job itself is capped three ways: 16 turns, an 8-minute limit on the review step, and a 20-minute ceiling on the whole job. Auth comes from a CLAUDE_CODE_OAUTH_TOKEN repository secret tied to a Claude Max subscription. There's no API-key fallback, so a misconfigured secret fails the preflight instead of silently billing somewhere else.

None of this is exotic. It's the same instinct as any other CI hardening: don't trust a string comparison you haven't tested for case sensitivity, don't hand out more filesystem access than the job needs, and don't let a slow job's output outlive the code it described.

Baamaapii

Publishing a versioned API contract you can actually trust

Russell Jones — Mon, 31 Aug 2026 02:38:22 +0000

Ahnii!

If you ship a public API, you eventually hit the same question from every client: "what exactly am I integrating against, and will it change under me?" goformx, a Go forms service, answers with a generated OpenAPI contract that gets frozen, checksummed, and published as its own release artifact, separate from the application's version tags. Here's how that pipeline works: the CI drift check, the release packaging script, and the rules the published docs give clients for staying compatible.

The problem: generated code that quietly goes stale

goformx generates its TypeScript client types from an OpenAPI 3.1 spec using openapi-typescript. Generated files are easy to forget to regenerate after an API change, and once that happens, the published client silently disagrees with the server. The fix is a CI gate that fails the build if generated artifacts don't match a clean regeneration — goforms/contracts/check-generated.mjs:

import { execFileSync } from "node:child_process";
import { fileURLToPath } from "node:url";

const cwd = fileURLToPath(new URL("../", import.meta.url));
execFileSync("git", ["diff", "--exit-code", "--", "contracts/generated"], { cwd, stdio: "inherit" });
const untracked = execFileSync("git", ["ls-files", "--others", "--exclude-standard", "--", "contracts/generated"], { cwd }).toString().trim();
if (untracked) throw new Error(`Generated artifacts must be committed:\n${untracked}`);

It regenerates the contract, then checks two things: no diff against what's committed, and no new untracked files under contracts/generated. Either failure means someone changed the API without regenerating and committing the client types.

Packaging a frozen release

Passing CI isn't the same as being safe to integrate against — main still moves. goformx solves that with package-release.mjs, which turns a specific commit into an immutable, checksummed bundle:

Refuses a dirty tree. It runs git status --porcelain first and throws if there are uncommitted changes — only a clean, verified commit gets packaged.
Hashes committed bytes, not a checkout. It reads file contents with git show HEAD:<path> instead of the filesystem, so a contributor's line-ending settings can't change the published SHA-256.
Requires an explicit semantic version. It reads info.version out of the generated openapi.json and rejects anything that isn't MAJOR.MINOR.PATCH.
Builds a manifest of content-addressed URLs. Each artifact (OpenAPI spec, form-definition schema, auth assertion schema, generated client types, example archive) gets a raw.githubusercontent.com/<repo>/<exact-commit-sha>/... URL plus its own SHA-256, so a client can verify what it downloaded actually matches that commit.
Never touches the network. The script only writes files to a local, git-ignored .contract-release/ directory — publishing the GitHub release is a separate, deliberate step.

That last point matters: packaging and publishing are decoupled on purpose, so building the artifact can't accidentally ship it.

What clients are told to do with it

The published guide, docs/api-clients.md, gives external integrators (including the project's own agent tooling) a discovery list rather than a single "latest" link:

Current release tag, manifest, OpenAPI download, client example archive, and SHA256SUMS
Links to the previous frozen versions (so a client mid-migration isn't stranded)
A pointer to the current development contract on main, explicitly labeled as not immutable

The guidance is blunt about the distinction that matters most: a published contract describes the interface, not the deployment state of any given server. Clients are told to confirm the target deployment actually supports the pinned version before integrating — a frozen spec is not proof anything is live.

The credential model, at a glance

The same doc lays out three credential types and where each is allowed to live:

Credential	Where it belongs	Authority
`gfpk_` public form key	Browser embeds and public submission clients	Published schema/submission access only; never management access
`gfst_` service token	External agents and custom-dashboard servers, in secret custody	One organization, explicit scopes, expiry and revocation
First-party assertion (`gofx-fpa+jwt`)	Server-to-server request only	Verified user and resolved organization; signed, audience-bound, single-use, at most 60 seconds

Every management operation also declares its own x-goformx-required-scopes in the spec — eight scopes total (forms:read/write/publish, submissions:read, tokens:read/write, webhooks:read/write). Write access doesn't implicitly grant publish access. Reading submissions doesn't implicitly grant webhook configuration.

Semantics that outlive any one endpoint

A few rules from the contract are the kind of thing that usually gets documented only after someone gets bitten by their absence:

Additive fields need an explicit contract bump. Contract 1.1.0 added a stored allowedOrigins array to form responses. The docs are explicit that an empty array means no cross-origin grant — never treat it as a wildcard — and that older servers omitting the field entirely is not the same as an empty configuration.
Numeric precision is a first-class guarantee. Contract 1.1.1 states that schemas and submission values retain numeric precision, with published token/exponent/decimal-place budgets, because JSONB storage can normalize spelling but must not normalize value.
Concurrency is ETag-based. Metadata PATCH requires the ETag from a current GET in If-Match; a 428 means fetch a fresh validator, a 412 means reconcile before retrying.
Idempotency keys are retry-scoped, not create-scoped. Public submissions require one; management creation has no general idempotency contract, so an uncertain create/publish response has to be reconciled rather than blindly retried.

The release checklist

Maintainers publish a new frozen contract with a fixed sequence:

Bump info.version for a new contract — never republish an existing version. Regenerate, verify, and commit source and generated files.
Run the packaging script from goforms/, which writes the manifest, OpenAPI copy, checksums, and client archive to the ignored release directory without any network call.
Create a contract-vVERSION tag at that exact commit and attach the four files to its GitHub release (not an application v* tag — contract releases are versioned independently).
Download the published artifacts anonymously, verify the SHA-256 digests and commit-pinned URLs, and run the example client against them.
Update the discovery doc for the new version, keeping the prior versions' links live.

Separating the contract's version from the application's version, and verifying the published artifact anonymously after the fact, closes the gap between "we merged it" and "an outside client can safely depend on it."

Baamaapii

Running the blog's content autopilot on a Claude subscription, not API credit

Russell Jones — Fri, 21 Aug 2026 23:52:30 +0000

Ahnii!

https://jonesrussell.github.io/blog/content-autopilot/ covers how this blog's Content Autopilot workflow mines, curates, and publishes without a human reading the draft first. Three things broke or needed hardening after that pipeline went live: how it pays for Claude, why the auth silently died, and the two gates bolted on afterward to catch a bad draft before it ships.

Switching off pay-per-token API credit

The produce step originally authenticated with ANTHROPIC_API_KEY, a pay-as-you-go API account billed per token. That account ran dry, and the daily cron started failing on the very first Claude call. Swapping to CLAUDE_CODE_OAUTH_TOKEN fixed it in one line: this env var runs the headless CLI against a Claude subscription instead.

env:
  # Subscription auth (no per-token API billing). See CLAUDE_CODE_OAUTH_TOKEN secret.
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
  GH_TOKEN: ${{ secrets.CROSS_REPO_TOKEN }}

claude setup-token mints this token locally. It's a short-lived credential meant for one CLI session, not a service account, and that mismatch is exactly what caused the next failure.

A revoked token, four silent failures

Subscription tokens rotate. This one got revoked, and the workflow had no step watching for a failure() outcome. Four daily runs failed in a row before anyone noticed, because a cron job with no output channel just... stops. Nobody was checking the Actions tab every morning.

The fix wasn't a longer-lived token. It was making failure loud:

- name: Alert on failure
  if: failure()
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    REPO: ${{ github.repository }}
    RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
  run: |
    gh label create autopilot-failure --repo "$REPO" --color d73a4a \
      --description "Content Autopilot run failed" 2>/dev/null || true
    body=$(printf 'Content Autopilot run failed: %s\n\nMost common cause: CLAUDE_CODE_OAUTH_TOKEN expired or was revoked (subscription tokens rotate). Re-sync the secret from a fresh token, or run `claude setup-token` for a long-lived one.\n\n@jonesrussell' "$RUN_URL")
    existing=$(gh issue list --repo "$REPO" --label autopilot-failure --state open --json number --jq '.[0].number // empty')
    if [ -n "$existing" ]; then
      gh issue comment "$existing" --repo "$REPO" --body "$body"
    else
      gh issue create --repo "$REPO" --title "Content Autopilot is failing" \
        --label autopilot-failure --body "$body"
    fi

This runs on any step failure in the job, not just the auth step. It opens one issue, reuses it on repeat failures instead of spamming a new one per day, and GitHub's default notification settings turn that issue into an email. The permissions block needed issues: write added alongside the existing contents: write and id-token: write for this to work.

Self-Refine: one critique pass before publish

Auth failures are loud and easy to fix. A boring, over-hedged, cliche-riddled post is a quieter failure, and nothing upstream of publish was checking for it. The next addition borrows the Self-Refine technique from the AI-writing research: have the model critique its own output once, then revise, before anything ships.

Critique and then revise the blog post at <path> and its social copy.
Rubric: (1) voice matches docs/blog-style.md and the essay reference;
(2) every claim is backed by a concrete fact, number, or reference;
(3) sentence lengths vary (no runs of same-length sentences);
(4) zero phrases from the site's banned AI-cliche list;
(5) intro scope line is not the phrase 'This post covers'.

The step is continue-on-error: true. If the critique call itself fails or times out, the workflow falls back to publishing the un-refined first draft rather than blocking the whole run over a quality pass.

The slop gate: a linter, not a model

A revise pass helps, but it's still the same model marking its own homework. The step after it is deliberately dumb: scripts/slop-check.mjs runs no API call at all. It strips frontmatter, code fences, and markdown syntax, splits what's left into sentences, and scores three signals.

const mean = totalWords / lens.length;
const variance = lens.reduce((a, n) => a + (n - mean) ** 2, 0) / lens.length;
const stdev = Math.sqrt(variance);
const burstiness = stdev / mean; // human ~0.6-1.2, AI slop < 0.4

Human writing varies sentence length a lot; AI writing tends to cluster around one length. The script also counts em dashes per thousand words (over 20 reads as machine-written) and matches a growing list of stock corporate-blog phrases pulled straight from the site's own style guide. It fails the draft on a hard burstiness floor of 0.32. Three or more banned-phrase hits alone are enough too, and so is any two of the three signals firing together. A failed check holds the draft: nothing gets committed, and the source issue stays open for the next day's run to try again.

Build order matters here. The slop gate runs before the Hugo build gate, so a flagged draft never even reaches hugo --gc --minify, let alone git push.

What actually changed

Two posts have shipped through this pipeline since it went live, tracked by issue number in data/autopilot-ledger.json. None of the hardening above came from planning ahead. Each piece exists because a specific run failed in a specific way: out-of-balance API credit, then a revoked token nobody caught, then no evidence-based reason to trust an unreviewed draft's prose. Unsupervised doesn't mean untested. It means every failure mode has to turn into a gate before the same thing is allowed to happen twice.

Baamaapii

Splitting Anokii into composable core, identity, and operator packages

Russell Jones — Fri, 21 Aug 2026 04:15:22 +0000

Ahnii!

Anokii is a distribution built on the Waaseyaa framework. It used to carry its own copy of identity handling duplicated across the root project instead of living in one place. This post covers how that got split into three composable Composer packages, core, identity, and operator, and the governed CI workflow that publishes them without a full release process.

The Problem: Duplicate Identity, No Boundary

Before the split, the root Anokii distribution kept its own Identity implementation instead of depending on a single canonical one. Any change to authentication or permissions had to be made carefully in more than one place, and there was no enforced boundary stopping other code from reaching into identity internals.

The fix was to extract two things:

waaseyaa/anokii-core, shared primitives only, nothing domain-specific.
waaseyaa/anokii-identity, one canonical identity domain: entity, service, permissions, policy, provider, migrations, and an opt-in read-only host surface.

A third package, waaseyaa/anokii-operator, followed the same pattern. The root distribution now consumes all three instead of maintaining its own duplicate implementations.

Composer Path Repositories Keep Local Dev Fast

Anokii's root composer.json points at each package directory as a local path repository, symlinked, so changes inside packages/core or packages/identity are picked up immediately without a publish step:

{
    "repositories": [
        {
            "type": "path",
            "url": "packages/core",
            "options": {
                "symlink": true,
                "versions": {
                    "waaseyaa/anokii-core": "dev-main"
                }
            }
        },
        {
            "type": "path",
            "url": "packages/identity",
            "options": {
                "symlink": true,
                "versions": {
                    "waaseyaa/anokii-identity": "dev-main"
                }
            }
        }
    ],
    "require": {
        "waaseyaa/anokii-core": "dev-main",
        "waaseyaa/anokii-identity": "dev-main"
    }
}

The symlink option means editing a file under packages/identity/src is the same as editing it in the standalone anokii-identity package, no composer update round trip. The monorepo stays the single source of truth: everything is authored in waaseyaa/anokii, not in the split repos directly.

The Split-Main Workflow

Getting code out of the monorepo and into standalone anokii-core and anokii-identity repositories is a workflow_dispatch job, not a script anyone runs by hand. It takes three inputs: the exact 40-character main SHA to split, a comma-separated list of package names, and a reason (an issue URL or similar).

Before anything is split, the workflow enforces a few gates:

# Only admin/maintain/write collaborators can dispatch the split
permission="$(gh api "repos/${REPOSITORY}/collaborators/${ACTOR}/permission" --jq '.permission')"
case "${permission}" in
  admin|maintain|write) ;;
  *) echo "::error::${ACTOR} cannot dispatch split-main."; exit 1 ;;
esac

It also refuses a stale or unmerged SHA, requiring the requested commit to match origin/main exactly, and it blocks until the Quality workflow (PHPUnit, PHPStan, php-cs-fixer, Composer audit) has reported success for that same SHA. Only then does it split:

split_sha="$(splitsh-lite --prefix="${LOCAL_PREFIX}")"
git push split --force-with-lease="refs/heads/main:${existing}" "${split_sha}:refs/heads/main"

splitsh-lite extracts the git history for one subdirectory (packages/core, packages/identity) into its own tree, preserving history instead of squashing it. The workflow pushes that exact commit to the split repo's main branch, then verifies with git ls-remote that what landed matches what was pushed, and uploads a provenance JSON artifact recording the source SHA, prefix, split SHA, actor, and reason.

Development Main Only, No Releases Yet

The workflow can update main on anokii-core and anokii-identity, but it cannot create tags, GitHub releases, or Packagist releases. That's deliberate: the split-main job proves the extraction is clean and history-preserving without committing to a versioning scheme before one exists. Tagged releases stay a separate, manual, exact-main procedure. Anyone consuming the split repos today does so at dev-main, the same version constraint the root project itself uses.

What the Split Buys You

Splitting this way doesn't just move files around, it enforces a boundary. Every returned identity entity now passes through one canonical access handler instead of whatever each duplicate implementation happened to do. The root distribution's test suite, PHPStan at max level, and a Composer audit all have to pass on the exact commit before that commit is eligible to split, so the packages that ship are never ahead of what was verified.

If you're running a monorepo that needs to publish more than one standalone package, the pattern is worth stealing even without Anokii's specific tooling: keep authoring in one place with Composer path repositories for fast local iteration, gate any split on your CI status for that exact commit, and use splitsh-lite to push history-preserving mirrors instead of hand-copying files into separate repos.

Baamaapii

Two months of senior engineering in 36 AI-assisted hours

Russell Jones — Fri, 21 Aug 2026 04:15:19 +0000

Ahnii!

Over roughly 36 hours, a large, interconnected set of Waaseyaa Framework and Sheg work went from nothing to a clean landing sequence. The interesting part is how the time split, and what it would have cost the conventional way.

Two phases, not one

The window had two distinct halves:

~10 hours of generation. An autonomous ChatGPT session pursued a goal and opened a stack of pull requests across both the Framework and Sheg. That stack was the backlog. It did not exist beforehand.
~26 hours of integration. The rest went to merging, rebasing, and repairing that stack into a moving main, plus the defects that only surface when you land code instead of just writing it.

So this is not a story about inheriting a mess and cleaning it up. The same window created the work and landed it.

What landed

14 pull requests merged — twelve in the Framework, two in Sheg.

The Framework twelve covered:

SQLite schema authority and migration safety
Admin Surface serialization and filtered destinations
Safe embed lifecycle and workflow transitions
Save-advisory contracts and acknowledgements
Entity revision recovery and authorization
Canonical sitemap URLs
Upgrade deadlock and timeout protection

The two Sheg PRs hardened secure local-acceptance diagnostics and fixed a Python test-wrapper that was reporting the wrong outcome.

The defects the merge count hides

Merges are the visible number. The real work was the defects that survived their own original implementations and only surfaced on the second pass:

Duplicate embed protocol messages
Missing workflow refresh signals
A historical-revision authorization gap and a restore-field authorization bypass
Advisory exceptions leaking across abstraction layers
Swallowed acceptance-test failures, a green check on a red result
A Composer subprocess deadlocking on a pipe
Unsafe candidate-build caching

Each was wired shut with regression, integration, and transport coverage so it stays shut. Underneath it all sits a 358-site SQLite coupling inventory across 108 files, the real map of what PostgreSQL and MySQL support will cost.

What did not happen

No tag. No package release. No deployment. No production mutation.

The release line held on purpose. The coordinated Framework and Sheg candidates wait until the CI lane and the advisory integration are finished. Anokii got compatibility and installation-contract testing but no direct change: protected, not touched.

The conventional estimate

Hand this to one experienced senior developer, generation and integration both:

Best estimate: about 8 full-time weeks
Range: 6 to 10 weeks
Effort: roughly 240 to 400 hours, midpoint around 320

Two seniors might compress the calendar to three to five weeks, but the total labor barely moves.

So the comparison is not 36 hours against building from scratch. It is one coordinated AI-assisted window against roughly two months of conventional senior engineering: generation, review, remediation, rebasing, testing, integration, and merge governance.

Baamaapii

The pipeline that writes this blog

Russell Jones — Sun, 16 Aug 2026 21:44:02 +0000

Ahnii!

This post is a little unusual: it was drafted by the same pipeline it describes. This blog runs a GitHub Actions workflow, Content Autopilot, that mines project activity, curates it with Claude Code running headless in CI, writes a Hugo post, and publishes it to main without a human in the loop. This post covers how the throttle, the curation gate, and the publish flow fit together.

The throttle: Buffer queue depth

Zero-touch pipelines need a rate limiter or they'll flood every channel the moment there's something to say. Instead of a fixed schedule, this one throttles on distribution capacity: Buffer's free tier caps a channel at 10 scheduled posts, so scripts/buffer-queue-depth.mjs checks each channel's queue depth before anything else runs.

const CAP = Number(process.argv[2] || 9);
// ...
const near = hasNext || count >= CAP;
if (near) atCap = true;

If any channel is at or near the cap, the script exits non-zero and the workflow stops before spending a single Claude token. Quiet weeks produce less; weeks where Buffer drains fast produce more. The queue itself decides the pace.

The gate: an LLM judging its own inputs

Once there's room to publish, the workflow pulls open stage:mined issues from a separate tracking repo — one issue per interesting thing that happened across other projects. Not every mined item is worth a post. A lot of them are per-directory scaffolding noise.

Rather than hand-curate, the workflow hands the candidate list to Claude with an explicit bar to clear:

STEP 1 - CURATE (be ruthless). Pick AT MOST ONE candidate that would make
a genuinely useful, self-contained post a reader would value. Reject thin
per-directory dev-scaffolding items (e.g. "packages/field work"). If
NOTHING clears that bar, write {"status":"NONE","reason":"..."} to
autopilot-result.json and STOP.

If nothing qualifies, the run ends with no post and no distribution. The gate is "good enough to publish," not "something to publish" — a distinction that matters once nobody is reading the draft before it goes live.

Verify before you invent

The riskiest part of an unsupervised pipeline is a model confidently inventing a function signature or a config flag that doesn't exist. The prompt closes that door explicitly:

STEP 2 - VERIFY. If the post would contain code, config, or interface
signatures, verify each against the real source repo using:
gh api repos/<owner>/<repo>/contents/<path> (GH_TOKEN is set). If you
cannot verify a snippet, DO NOT invent it. Either write the post without
it, or if the post depends on it write
{"status":"HOLD","issue":N,"reason":"unverifiable code"} to
autopilot-result.json and STOP.

Claude reads the actual source file through the GitHub API before quoting it. If it can't verify something the post depends on, it holds rather than guesses. This is the same rule the project's CLAUDE.md already enforces for human-written posts — the autopilot just has to follow it without anyone checking its homework afterward.

Build gate, then publish

Once Claude writes the post and a companion docs/social/<slug>.md file, the workflow runs hugo --gc --minify. If the build fails, the post never gets committed — a broken page bundle or bad frontmatter simply stops the run. Only after a clean build does the workflow commit, git pull --rebase, and push to main, which triggers the existing deploy workflow.

- name: Build gate
  if: steps.result.outputs.status == 'PUBLISH'
  run: hugo --gc --minify

- name: Publish
  if: steps.result.outputs.status == 'PUBLISH' && github.event.inputs.dry_run != 'true'
  run: |
    git add "${{ steps.result.outputs.post_path }}" "${{ steps.result.outputs.social_path }}" data/autopilot-ledger.json
    git commit -m "content: autopilot publish ${{ steps.result.outputs.slug }} (queue #${{ steps.result.outputs.issue }})"
    git pull --rebase origin main
    git push origin main

A JSON ledger (data/autopilot-ledger.json) records which mined issue numbers have already been processed, so a rerun never republishes the same source.

Distribute, then close the loop

The last step reads the same docs/social/<slug>.md file and queues one post per platform through Buffer's GraphQL API:

// Parse "## Platform" sections out of the markdown.
const parsed = {};
for (const part of md.split(/^##[ \t]+/m).slice(1)) {
  const nl = part.indexOf("\n");
  const name = (nl === -1 ? part : part.slice(0, nl)).trim().toLowerCase();
  parsed[name] = (nl === -1 ? "" : part.slice(nl + 1)).trim();
}

Each platform's body is queued with createPost, and Bluesky posts over 300 characters are rejected before they ever reach the API. The originating tracking issue is then closed, so the same idea can't get mined and drafted twice.

What keeps it honest

Nothing here is exotic on its own — a cron trigger, an LLM call, a build step, a git push. What makes it safe to run unsupervised is that every stage can say no: the throttle can refuse to run, the curator can refuse to pick anything, the verifier can refuse to invent code, and the build gate can refuse a broken post. Zero-touch doesn't mean zero judgment; it means the judgment has to be encoded into the pipeline instead of applied by a person reading a draft.

Baamaapii

A beginner's guide to Git worktrees: What they are, why they matter, and how to use them without breaking anything

Russell Jones — Thu, 16 Jul 2026 20:47:15 +0000

Ahnii!

If you have ever needed to work on two branches at the same time, Git worktrees can save you a lot of friction. This post covers what worktrees are, why they exist, and how you can use them safely as a beginner.

Prerequisites

You have Git installed
You can run commands in your terminal
You already have a local repository

What Is a Git Worktree?

A Git worktree is an extra working folder connected to the same repository history.

You can think of it as another checkout of your project, without making another full clone.

Your main folder still exists. A worktree gives you a second folder where a different branch can be checked out at the same time.

Why Worktrees Exist

Git worktrees solve a practical problem. You may be in the middle of feature work, then need to fix a bug on another branch right away.

Without worktrees, you usually do one of these:

Stash or commit unfinished work, then switch branches
Open a second full clone of the same repository

Both options work, but both add overhead. Worktrees give you a cleaner path.

Normal Clone vs Branch Checkout vs Worktree

Here is the simple difference:

Normal clone

A clone is a separate copy of a repository with its own .git directory.

git clone https://github.com/example/project.git

You use this when you need the repository on your machine for the first time. It is fully independent from other clones.

Branch checkout

A branch checkout changes which branch is active in your current folder.

git checkout feature/foo

This is fast, but only one branch can be active in that folder at a time.

Worktree

A worktree creates another folder tied to the same repository, usually on a different branch.

git worktree add ../feature-foo feature/foo

Now you have two folders open at once: your main folder and ../feature-foo. Each can point at a different branch.

Core Benefits of Worktrees

1) Multiple branches checked out at once

You can keep your main branch open in one folder and your feature branch in another.

No constant branch switching.

2) Isolated environments for experiments

You can test risky changes in one worktree without touching the working state in another folder.

3) No need for multiple full clones

Worktrees share repository data, so you avoid duplicate clones for everyday branch work.

A Safe Beginner Workflow

This is a clean workflow you can use right away.

1) Create a worktree

git worktree add ../feature-foo feature/foo

This command creates a new folder named ../feature-foo and checks out feature/foo there.

If feature/foo does not exist yet, create it first with git branch feature/foo.

2) Switch into it

cd ../feature-foo

Now every Git command runs inside that worktree folder.

Before you edit files, confirm where you are with pwd and git branch --show-current.

3) Commit from it

git add .
git commit -m "Add first pass of feature foo"

These commits belong to the branch checked out in that worktree.

You do not need to return to your original folder to commit.

4) Remove it safely

First leave the worktree folder, then remove it with Git.

cd ../your-main-repo
git worktree remove ../feature-foo

This tells Git to unregister the worktree and remove the directory safely.

Always prefer this over deleting the folder manually.

How to See Your Current Worktrees

git worktree list

This shows every registered worktree path and branch.

Use this often, especially when you are learning.

Common Beginner Mistakes

Deleting the directory without removing the worktree

If you run rm -rf on a worktree folder first, Git can keep stale metadata.

Remove worktrees with git worktree remove <path> whenever possible.

Forgetting which worktree you are in

It is easy to commit to the wrong branch when two folders look similar.

Check pwd and git branch --show-current before making changes.

Trying to check out the same branch twice

Git does not allow the same branch to be active in two worktrees at once.

Create a new branch if you need a second experimental space.

A Simple Mental Model for `.git/worktrees`

Your main repository still has the real Git database.

Inside it, .git/worktrees stores small records that point to each extra working folder.

Think of it like a clipboard that says:

Which extra folders exist
Which branch each one uses
Whether Git still expects them to be present

That is why manual deletion can confuse Git. The clipboard still has an entry, even if the folder is gone.

How to Clean Up Orphaned Worktrees

Sometimes a worktree folder gets deleted outside Git.

You can clean this up safely in a few steps.

Step 1: List what Git thinks exists

git worktree list

Look for paths that no longer exist on disk.

Those are likely orphans.

Step 2: Prune stale metadata

git worktree prune

This removes stale worktree entries that no longer point to valid folders.

It is a safe maintenance command for this situation.

Step 3: Verify cleanup

git worktree list

Run the list command again to confirm orphan entries are gone.

If everything looks clean, you are done.

Verify It Works

Run this quick check whenever you start using worktrees:

git worktree list
git branch --show-current
pwd

These three commands tell you what worktrees exist, which branch is active, and which folder you are in.

That simple habit prevents most beginner mistakes.

Baamaapii

The hackathon Anthropic didn't expect

Russell Jones — Thu, 16 Jul 2026 20:47:11 +0000

Ahnii!

Casey Newton interviewed Boris Cherny, the creator of Claude Code, for Platformer last week. Most of the coverage pulled the headline-friendly quote that coding is "solved" and moved on. I want to point at a smaller moment in the same interview that I think matters more. This post is about that moment, and three things I've watched up close that line up with it.

The hackathon Anthropic didn't expect

Newton asks Cherny about the AI divide. The worry, in shorthand, is that the people who already have power will use these tools to get more of it. The early data on who benefits from new technology usually goes that way. So who's actually getting the most out of Claude Code?

Cherny's answer surprised Newton, and it surprised me when I read it. He talks about a recent Anthropic hackathon for the Opus 4.7 release, and says the people who won were largely not professional engineers. "There was an electrician, a doctor, a carpenter who used it to build an app." Same pattern at the 4.6 hackathon. He calls it a continuous surprise. The people who get the most value out of Claude Code, he says, are not the people he'd expect.

That's a small line in a long interview. It's the line I haven't stopped thinking about.

Two questions, not one

The AI-jobs discourse is mostly fighting over one question: will engineers be replaced. Cherny's answer to that question, if you read the whole interview, is actually mild. He thinks the title "software engineer" probably changes ("builder" is the word he uses), the role expands, and the number of people writing code with the help of agents goes up roughly a hundred-fold. That's not an extinction story. It's a transformation story, with a hiring pull, not a layoff cliff.

But that's not the only question we should be asking. The other question is the one Newton was getting at: when the syntax gate falls, who walks through?

The hackathon detail is an early answer. Not "the engineers got faster." An electrician, a doctor, and a carpenter built apps that won. The default story we tell about new technology — the people in the room get more powerful first — doesn't fit. The people in the room didn't even win.

Three things I've watched up close

Here's what I'm seeing in three different places.

I just finished my Grade 12 coursework as an adult learner through Sagamok Anishnawbek's Lifelong Learning Centre. AI was in the loop for a lot of it. I'm not the demographic anyone meant when they said "AI for developers." I'm a forty-something who came back to finish his OSSD, and the tools worked for me anyway. I finished the work that for years had been hard to finish. That's one shape.

I started a petition asking the Rainbow District School Board to publish a real public AI policy before next semester. Students across the board are using these tools every day. The adults setting the rules haven't caught up. Partway through my own coursework, I was pulled aside and questioned about my AI use because there was no policy to point at. The petition is about that, but it's also about the kids: they're walking through a door before anyone has written a rule about it. That's another shape.

I'm building Anokii, the embedded chat on the OIATC site, on top of my own framework. Anokii isn't being built for engineers. It's being built so a member of a community can find a community-specific resource and get an answer that cites where it came from. Per-community variants. A relevance gate so it stays quiet when it shouldn't speak. A topic-confidence gate on the citations. When the tool is reachable, and built with the people who'll use it in mind, the people who reach for it are not the obvious ones. That's a third shape.

The pattern

Three different angles. An adult learner finishing high school. A petition asking for a fair rule. A chat that surfaces community resources without pretending to be smarter than it is.

None of these are "engineers replaced." All of them are "someone got access to a tool that wasn't available before, and the question is whether the systems around them caught up."

Cherny's hackathon detail isn't an outlier. It's the leading edge of what happens everywhere when the syntax-and-credentials gate falls. People who were never in the room start showing up. The electrician builds the app. The adult learner finishes the coursework. The community member finds the resource they needed and gets a real citation instead of an authoritative-sounding guess.

The energy we spend arguing about whether engineers will exist in five years is energy we are not spending on what the hackathon detail is actually telling us.

Where the energy belongs

Three places I'd want it to go.

Schools need policy now, not after the next semester. The Rainbow District petition is one example. Every board with students using these tools is facing the same problem. The students are already there. The policy can't be retroactive forever.

Communities deserve tools built for them, not demos pointed at them. Anokii is the version of that I'm running, and the way to tell whether a community tool is real is whether it cites its sources, whether it knows when to stay quiet, and whether it gets better when the community pushes back on it. Demos do not pass any of those tests.

For engineers and builders and whatever else we get called next: stop pretending the threat is your job disappearing. The threat, if there is one, is that the tools become most useful to the people who already had power. Cherny's data so far says that is not what's happening. Don't make it happen. (If you want the engineer-facing half of this argument, I wrote the playbook for taking a vibe-coded prototype to something a stranger can run earlier this week. This post is the other half.)

Closing

The people getting the most out of these tools right now are not the people the discourse expects. The electrician winning the hackathon, the adult learner finishing the diploma, the community member finding the resource. None of them are the story we're telling. All of them are the story we should be telling.

That should change how we talk about this.

Baamaapii

From vibe-coded to shippable: a playbook

Russell Jones — Thu, 16 Jul 2026 20:46:37 +0000

Ahnii!

There's a lot of energy right now spent bashing vibe coding. I think most of it is aimed at the wrong target. The MVP you stand up with AI doesn't have to generalize. That's not what it was for. The interesting craft is what you do next to take that prototype from "it works on my laptop" to something a stranger can run, debug, and trust. That's a craft worth respecting. This post is the playbook I'm currently running on a real public repo, with six specific moves and an artifact for each.

The wrong fight

The bashing usually goes like this: "Look at this AI-generated MVP, look at how brittle it is, look at how much it cost in tokens to get it half-right." Sure. Now compare it to the alternative: an empty directory and a developer who hasn't started. The point of the prototype isn't to be production code. The point of the prototype is to find out whether the idea works at all. To answer a question. To make something move on a screen that wasn't moving yesterday.

Once it moves, you have new information. You know which parts are load-bearing. You know which gotchas bit you. You know which assumptions held up. You're now in a much better position to do the second pass, and the second pass is where the craft lives. The craft is the set of moves you make to take a working prototype to a state where someone else can run it, debug it, and trust it.

Those moves are not mysterious. They have names. They are the rest of this post.

The repo on the bench

The worked example is the OIATC application, a public PHP repo I build alongside my own modern PHP framework, Waaseyaa:

https://github.com/waaseyaa/oiatc-waaseyaa

It powers oiatc.ca. The marquee feature inside it is Anokii, an embedded AI chat that grounds its answers in the site's own community-resource pages and cites them. Anokii started as a vibe-coded chat experiment. It's now a RAG pipeline with a relevance gate, per-community variants, anonymous query-gap logging, and a topic-confidence gate on citations. Every step below points at a specific artifact in that repo.

Step 1. Milestone the roadmap

The first thing that turned the Anokii work from "a directory of chat hacks" into "a project" was naming the phases. Phase 1 got a chat working at all. Phase 2 introduced RAG grounding, split into stages: Stage 1 was the doc_chunk entity and the app:ingest-docs CLI that fills it; Stage 2 was the keyword-RAG retrieval over those chunks.

Branches in the repo carry the phase names. feat/doc-chunk-ingestion landed Stage 1. feat/keyword-rag-chat landed the MVP retrieval. feat/sagamok-resources and feat/data-sovereignty-and-masthead carried sibling work. Each branch closes with a merge commit that documents what shipped, and only after that does the next phase begin.

Three phases, a handful of branches, every one of them with a concrete definition of done. That's enough structure to know what to work on next, and just as importantly, what not to work on right now.

You don't need a wiki or a project board. You need branch names that announce intent and merge commits that close the loop.

Step 2. Write the runbook, including the gotchas

The repo's CLAUDE.md is the runbook. It opens with a Strategy folder pointer: a separate workspace outside the repo tracks every live page on oiatc.ca against its canonical Twig source, last-updated date, and analytics. The CLAUDE.md says, plainly, that if the two disagree, the repo wins.

Below that pointer it documents the architecture (Access/, Controller/, Domain/, Entity/, Provider/, Support/), the ServiceProvider DI methods with full signatures (singleton, bind, resolve, tag, entityType), the queue Job pattern with tries, timeout, retryAfter, and the frontend template families (site shell vs. longform documents vs. news). An Operations section, added in commit 896ec8f, covers deploy, Raspberry Pi access, and secrets.

The runbook is the operating manual you wish someone had handed you. The OIATC one is dense because it earned every line. The mistakes that produced those lines aren't generic; they're specific to this app, this framework version, this deployment target. That's exactly what makes them worth writing down.

Step 3. Pin the world

Vibe-coded prototypes love composer install and git clone main. That works on Tuesday. It breaks on Friday when upstream cuts a release. The OIATC repo pins the world three different ways.

First, composer.lock is committed and treated as the source of truth. Lock-file drift gets its own entry in the upstream-notes (entry 003 walks through a drift caused by a post-hash php: >=8.5 constraint and the fix). Second, the deploy contract is a docker compose run that calls bin/waaseyaa db:init before bringing the app up:

docker compose run --rm oiatc-app bin/waaseyaa db:init
docker compose up -d

db:init is idempotent. Fresh volume gets migrations. Current schema is a no-op. Safe to invoke on every deploy. That's what makes a deploy step a contract instead of a tradition.

Third, the app lives on a specific waaseyaa/framework alpha version (currently alpha.188). Upgrades happen as deliberate events with their own branch and their own entry in the upstream-notes, not as quiet drift. When upstream cuts a release that breaks something, you have a working baseline to compare against.

Step 4. Name the graveyard

The repo has a literal graveyard directory: docs/archive/2026-04-20-cut-pages/. It holds Twig templates and design notes for pages that were on oiatc.ca and got cut. Not deleted from git history. Not pretended to never have existed. Filed under a date and a reason so the next person can read what we tried and why we stopped.

This pattern shows up in the codebase too. The keyword-RAG retrieval merge commit literally calls itself "Path B." There was a Path A. Path A's notes are still around. Anyone looking at the current Path B implementation can see the alternative that was considered and the trade-offs that drove the decision.

Naming the graveyard is one of the cheapest, most under-used moves in software. Most repos don't do it because it feels embarrassing. The OIATC repo does it because each cut page and each abandoned path represents a hypothesis tested. The next person who has a similar hypothesis deserves to see the result.

Step 5. Recon before you build

The single most useful artifact in the repo is docs/waaseyaa-upstream-notes.md. It's a running log of framework quirks, bugs, breakages, and missing pieces hit while building on an alpha release of waaseyaa/framework. Each entry uses a fixed format:

## NNN — short title

- **Date / version:** YYYY-MM-DD · waaseyaa/framework alpha.NNN
- **Doing:** what we were doing when we hit it
- **Symptom:** the observable problem
- **Workaround:** what we did to get unblocked
- **Likely upstream fix:** the proper change in waaseyaa/framework

There are 16+ entries. Stale VERSION files. Ambiguous class resolution between the metapackage and split mirrors. Lock-file drift after a platform requirement bump. Hard ext-sodium dependency via the OIDC stack. Each one is recon for the framework itself.

The point of the upstream-notes is not to complain. The point is to keep app-level hacks out of the consumer code. Every entry is a decision: do we patch around it here, do we file the upstream fix now, do we wait until the next alpha. Without the log, those decisions get re-litigated every time someone hits the same wall.

This is also the move I think AI tooling makes most useful. When you hit a quirk, write the entry first. The structured shape forces you to articulate what you actually saw, what you're guessing, and what would fix it upstream. That writing is exactly the input the model needs to either help you work around it cleanly or propose an upstream change.

Step 6. Layer specs on what's next

The hardest current work on Anokii doesn't get vibe-coded. The topic-confidence gate that decides whether a citation is worth showing (65de562), the relevance gate that ensures only genuinely relevant passages are cited (8359e37), the climate-companion variant for the Massey Solar resource cluster (c8956f6), the shared relational-graph instance per community (928191d) — all of those run through docs/superpowers/specs and docs/superpowers/plans. Each change has a spec articulating the intent, a plan decomposing the work, and reviewable PRs landing the implementation.

Why specs and not just commits: a relevance gate that filters citations is the kind of thing where a hallucinated implementation looks fine until a user gets a confidently-wrong answer. The spec gives you a contract for what the gate is supposed to do. The plan gives reviewers something to evaluate against. The implementation has a referenceable target.

This is the handoff move. Vibe coding got the chat answering. The runbook captured the patterns. The pinned world made the deploys reproducible. The graveyard remembered the dead ends. The upstream-notes captured what the framework still owes us. And now spec-driven work takes over for the parts that are too big or too risky to vibe through. Each layer earned the right to the next layer.

What this looks like together

The OIATC repo is not a clean codebase. It's a layered one. Some Anokii code still reads like the experiment it started as, because it still works and the cost of replacing it is higher than the cost of keeping it. The newer pieces — the keyword-RAG retrieval, the relevance gate, the topic-confidence gate — were built with specs and reviewed PRs because each of them is a place where a quiet bug becomes a confidently-wrong answer to a real person looking for real community resources.

Vibe coding was the first move. The six moves above are the second, third, fourth, fifth, sixth, and seventh. None of them are mysterious. None of them are expensive. They are the boring craft that turns a working prototype into something a stranger can run, debug, and trust.

If you've been bashing vibe coding, you're aiming at the start of a process and ignoring the rest of it. If you've been vibe-coding without any of the rest, you're going to keep losing days to the same gotchas, and the next person who touches your prototype is going to lose them too.

There's no shame in vibe coding. There's a lot of value in what comes next.

Baamaapii

AI keeps speccing my projects on pre-AI timelines

Russell Jones — Thu, 16 Jul 2026 20:46:33 +0000

Ahnii!

You sit down to spec a new feature with Claude Code or whichever assistant. You describe the surface, the constraints, the slices you want it broken into. The plan comes back: "5 work packages, 6 to 8 weeks." You shipped a 5-WP mission in a day yesterday. This post is about that gap and why it eats more time than it should.

The pattern

Spec mode is where it shows up worst. You ask for a plan. The plan arrives with timelines attached. Those timelines are calibrated to a world that ended around 2023. A "2-week task" inside a modern plan is often something you can ship the same afternoon if the scope is honest.

When you push back, the assistant does not back down quickly. It cites "industry norms," talks about "code review cycles," reminds you about testing time and edge cases. All of which are real concerns. None of which describe what actually happens when you and an AI co-author the work at full session-pace.

You end up in a loop. You spec. It estimates long. You explain that the work is being done with AI. It hedges. You re-spec. You ship in a fraction of the estimate. Next time you do this same dance again, because the assistant has no persistent sense that you ship faster than the baseline it was trained on.

Why this happens

Almost every public dataset that taught these models how long things take pre-dates widespread AI-assisted development. Stack Overflow threads from 2019 about how long a Laravel package takes to build. Engineering manager blog posts from 2021 about ticket-pointing conventions. Git histories from teams that did not have Claude on the keyboard. The model sees those signals and projects.

The reasoning models are smart enough to know AI assistance changes velocity. They will say so if you ask them directly. The problem is they do not apply that knowledge to estimation by default. You have to invoke it explicitly, every time, and even then they hedge in case you turn out to be slower than you said.

It is the same failure mode as asking an assistant in early 2024 whether you should use React 18 features. It knows React 19 exists. It does not always update its working assumptions to match.

What this costs

Two things.

First, time. Every spec session has a recalibration tax. You say two weeks; it says six. You push; it says four. You re-explain; it says three. You ship in two days. Multiply across a year of speccing and you are spending real hours arguing with an estimator that is wrong in one direction.

Second, drift. When you accept a long estimate to move on, the WP breakdown that gets generated is shaped by that estimate. Work packages get padded with imagined complexity to justify the duration. Tasks get split that did not need splitting. You end up implementing a plan designed for a slower world and discovering halfway through that half the WPs collapse into one.

The downstream version of this is worse: an assistant reviewing your PR will sometimes flag "is the scope of this change too large for a single WP?" when the change is fine and the WP boundary was the artifact of a stale estimate.

What to do about it

The fixes are all small and all annoying because you have to repeat them.

State the velocity assumption in your spec prompt explicitly. "This is being done with AI assistance. Estimate WPs in hours, not days, and assume each WP fits inside a single focused session." This is not subtle and it works. You can put it in your project's spec template so you do not have to remember.

Reject the estimate during planning, not after. If the plan comes back with multi-week WPs, push back before generating the WP breakdown. The breakdown is downstream of the duration assumption; if you let it materialize, you inherit its shape.

Cite recent evidence. "I shipped a 5-WP mission yesterday in a day. Use that as the baseline, not pre-2024 industry norms." The model responds to concrete recent counter-evidence more than to abstract argument.

Strip duration estimates from the plan entirely when you can. Half the time you do not need them and they only exist because the spec template asked for them. A plan that says "5 WPs, dependency-ordered" is more honest than a plan that says "5 WPs, 6-8 weeks." You are not running a Gantt chart. You are sequencing work.

The deeper problem

This will probably get worse before it gets better. Training data for "how long does this take" lags real-world velocity by a couple of years. Right now the gap is roughly 2023 vs 2026, which is about a 3-5x estimation error in many domains. As AI-assisted development accelerates, that gap widens, and the public-corpus signal stays stuck in the past.

The assistants that handle this well will be ones that calibrate against the user's recent shipping pace, not against the corpus average. That requires per-user telemetry the current tools do not have, or explicit user-state that they do not yet persist between sessions. Until then, the workaround is the four-step dance above.

The honest version of the complaint is not "AI is bad at estimates." It is "AI is estimating on a baseline that the existence of AI itself made obsolete." Worth naming so you can stop arguing with it and just override the defaults.

Baamaapii

DEV Community: Russell Jones

A missing npm ci silently starved the content-mining pipeline for a week

What Broke

Fix 1: Fail Open, Warn Loud

Fix 2: Actually Install the Dependency

What Changed, at a Glance

The Lesson

Idempotent, budget-bounded AI queries on a single SQLite writer

One writer, strictly locked

Scoped keys, one cross-tenant lookup

Reserve first, settle later

The query claim lifecycle

Recovering from crashes without guessing

Timestamps get the same suspicion

Why this shape

Hardening a manual Claude Code review workflow in GitHub Actions

Why the Default Example Wasn't Enough

Fix 1: Enforce the Exact Trigger

Fix 2: Bound the Diff, Fail Closed

Fix 3: Deny Tools Instead of Just Allowing Them

Fix 4: Keep Git Metadata Off Limits

Fix 5: Catch Stale or Unverified Reviews

What Changed, at a Glance

Testing Without Spending a Turn

Budget Stays Bounded Too

Publishing a versioned API contract you can actually trust

The problem: generated code that quietly goes stale

Packaging a frozen release

What clients are told to do with it

The credential model, at a glance

Semantics that outlive any one endpoint

The release checklist

Running the blog's content autopilot on a Claude subscription, not API credit

Switching off pay-per-token API credit

A revoked token, four silent failures

Self-Refine: one critique pass before publish

The slop gate: a linter, not a model

What actually changed

Splitting Anokii into composable core, identity, and operator packages

The Problem: Duplicate Identity, No Boundary

Composer Path Repositories Keep Local Dev Fast

The Split-Main Workflow

Development Main Only, No Releases Yet

What the Split Buys You

Two months of senior engineering in 36 AI-assisted hours

Two phases, not one

What landed

The defects the merge count hides

What did not happen

The conventional estimate

The pipeline that writes this blog

The throttle: Buffer queue depth

The gate: an LLM judging its own inputs

Verify before you invent

Build gate, then publish

Distribute, then close the loop

What keeps it honest

A beginner's guide to Git worktrees: What they are, why they matter, and how to use them without breaking anything

Prerequisites

What Is a Git Worktree?

Why Worktrees Exist

Normal Clone vs Branch Checkout vs Worktree

Normal clone

Branch checkout

Worktree

Core Benefits of Worktrees

1) Multiple branches checked out at once

2) Isolated environments for experiments

3) No need for multiple full clones

A Safe Beginner Workflow

1) Create a worktree

2) Switch into it

3) Commit from it

4) Remove it safely

How to See Your Current Worktrees

Common Beginner Mistakes

Deleting the directory without removing the worktree

Forgetting which worktree you are in

Trying to check out the same branch twice

A Simple Mental Model for .git/worktrees

A Simple Mental Model for `.git/worktrees`