DEV Community: Avery Li

A Pairing Manifest That Stops Generated Edits Outside One Module

Avery Li — Sat, 10 Oct 2026 18:52:53 +0000

A Pairing Manifest That Stops Generated Edits Outside One Module

A generated patch should stay on the laptop until a pairing names one rewrite set and one owner. The decision kept in this worked example is a manifest that rejects every changed path outside that set. A free model may draft only after the manifest exists, and a free server may receive only a later dry run. The local checker runs first, so an over-wide edit never becomes a remote experiment on a shared host.

What the session was protecting

Shared modules fail in quiet ways when a generated draft helps by touching neighboring files that nobody planned to change. A retry helper, a package initializer, and a sample config can look related while carrying different rollback costs. This worked example starts from a narrow bug in the helper and a tempting offer to clean the whole package. The senior refused that expansion before any remote host entered the plan or received a copy of the tree.

Questions the senior placed on the note

The senior did not ask for a longer prompt or a broader cleanup pass across the package. The note recorded which paths were in scope, who would roll them back, and which evidence would show the patch had not grown. Those three items stayed beside the terminal for the whole session and were not replaced by a chat log. The note became the rewrite set, rather than a second design document that nobody would reread.

Which paths may change in this pairing, and which paths stay frozen for later work?
Who owns the rollback if a later dry run on a free server fails after the check?
Which repeated diff shows that a redraft did not add paths after the first local check?

The pair answered with a file list, a named owner, and a second diff, then stopped adding process to the note. A vague answer, such as a claim that the model would know, sent the session back to the dead ends below. The note was accepted only when each answer pointed at a file, a person, or a command.

Dead ends the pair discarded

The first dead end was a draft that rewrote the helper, the package init, and a sample config together. The prompt had asked for a consistent change, and the model treated consistency as permission to wander. The second dead end proposed a live test on a free server before the diff was bounded. The third treated a green unit test as permission to include a migration in the same patch.

Each discarded option hid a different owner behind a convenient story about saving time in the session. The cleanup mixed a bug fix with style edits that another person might already be reviewing. The early server run would have spent a shared host on an unbounded working tree with no named owner. The migration idea would have coupled a data change to a retry tweak, so the pair dropped all three before the manifest.

Steps that remained after the dead ends

The workflow below is a proposal for the same kind of pairing, labeled so nobody mistakes it for a measured case study. Each step has a visible artifact, and a missing artifact stops the session rather than inviting a workaround. The free model and the free server appear late on purpose, after the file boundary is already written down. A missing owner name stops the session even when the path list already looks narrow enough.

Write rewrite-set.txt with one allowed path per line and a comment that names the rollback owner.
Run the checker against the working tree before any model is asked to redraft the helper or its tests.
If the checker prints an extra path, restore that path and shrink the prompt instead of widening the manifest.
Request a draft only inside the allowed paths, then run the checker again on the resulting diff.
Point a dry run at a free server only after the second checker exits with status zero.
Record one rollback command the owner can run, and stop the session if that command is unclear.

The checker the pairing kept

The script below is an unexecuted example for review, not a claim that a repository already enforces this gate. It reads the manifest, lists changed paths, and fails when any path is absent from the allowed set. It does not judge whether an allowed file is semantically correct, safe to ship, or free of secrets. It only preserves the boundary the pairing already chose in writing and can reverse by hand.

#!/usr/bin/env python3
"""Unexecuted example: reject Git paths outside a kept rewrite set."""

import subprocess
import sys
from pathlib import Path

MANIFEST = Path("rewrite-set.txt")


def load_allowed(path: Path) -> set[str]:
    allowed = set()
    for line in path.read_text(encoding="utf-8").splitlines():
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue
        allowed.add(stripped)
    return allowed


def collect_paths(command: list[str]) -> list[str]:
    result = subprocess.run(
        command,
        check=True,
        capture_output=True,
        text=True,
    )
    return [line.strip() for line in result.stdout.splitlines() if line.strip()]


def changed_paths() -> list[str]:
    groups = [
        ["git", "diff", "--name-only", "--", "."],
        ["git", "diff", "--cached", "--name-only", "--", "."],
        ["git", "ls-files", "--others", "--exclude-standard"],
    ]
    found = []
    seen = set()
    for command in groups:
        for path in collect_paths(command):
            if path not in seen:
                seen.add(path)
                found.append(path)
    return found


def main() -> int:
    if not MANIFEST.is_file():
        print("missing rewrite-set.txt", file=sys.stderr)
        return 2
    allowed = load_allowed(MANIFEST)
    extra = [path for path in changed_paths() if path not in allowed]
    if extra:
        print("paths outside the kept rewrite set:")
        for path in extra:
            print(f"  {path}")
        return 1
    print("rewrite set holds")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

The checker unions unstaged names, staged names, and untracked names that Git does not already ignore. A path that matches the manifest is still unread by this script, so a bad change inside an allowed file can pass. Renames can hide the old path, and ignored files never appear, so those cases need a human look at the tree. The script is a boundary reminder for a pairing, not a policy engine for a regulated release train.

A sample manifest stays short so the owner line remains visible to a human reviewer during the session. The checker ignores comments, which means a person can record the rollback without changing the allow logic. Adding a path is a new pairing decision, not a convenience edit made during a redraft of the helper. A wide manifest recreates the dead end the senior already rejected when the package cleanup appeared.

# owner: platform pairing, rollback: git checkout -- src/retry.py
src/retry.py
tests/test_retry.py

The local commands are ordinary and do not call a model or a remote host at any point. A failing run should print the extra paths and return a nonzero status before anyone opens a draft tool. A passing run only means the names match the note that the senior kept beside the terminal. Reviewers still read the diff inside those names before any dry run is scheduled on a shared host.

python3 check_rewrite_set.py
git diff -- src/retry.py tests/test_retry.py

How to rehearse the three exit codes

A rehearsal stays local and uses a temporary repository so the example cannot touch a shared host. The steps below are unexecuted instructions for a reviewer who wants to see the three exit codes. They do not prove that a passing tree is behaviorally correct or ready for any shared host. They only show that the path boundary fails closed when the manifest is missing or exceeded.

Create a temporary Git repository, commit the two allowed files, and add the sample manifest beside them.
Run the checker on a clean tree and expect status zero, since an empty change list cannot violate the set.
Add an untracked note outside the set, run the checker, and expect status one with that path printed.
Remove the manifest, run the checker, and expect status two before any drafting tool is opened.

How the pair compared the options

The comparison table is a review aid for the session, not a benchmark of tools or hosts. No timing figure, token total, or hardware result belongs in the rows of this session comparison. The only passing row is the one whose failure mode the pair can explain in a single sentence. Other rows stay as rejected alternatives so a later reader does not revive them by habit.

Option	Boundary it kept	Why it lost or stayed
Whole-package cleanup	No single owner	Style edits mixed with the bug fix
Free-server test first	A realistic host only	The diff was still unbounded
Green unit test as a wide pass	Local behavior of one helper	A migration has a different rollback
Manifest plus a second diff check	The agreed file list	Failure prints the extra path

Where a free model and a free server fit

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode enters the method only after the rewrite set exists, as a drafting aid inside the operator-described free model access. The same operator note describes a free server option, which fits the dry-run step after the checker exits cleanly. This draft does not name models, quotas, hardware, or a duration, because those terms were not verified here and can change.

Readers should confirm the current product terms before they treat either free option as available for their own work. A free server remains a shared convenience, not a production stand-in and not a substitute for the named owner. A dry run can still reveal a bad retry loop, a missing fixture, or a log line that should never have left the laptop. If that run fails, the owner uses the recorded rollback and does not widen the manifest to satisfy the host.

A later draft starts again from the same allowed paths and the same owner note beside the terminal. Nothing in the free option changes the rule that an extra path is a failed pairing rather than a prompt problem. The drafting tool should receive the manifest text in the task notes so the requested edit stays narrow. If the tool cannot accept that constraint, the pairing stops on the laptop and does not open the server.

Who should skip this boundary

This boundary should not be used for a production incident, a secret rotation, or a change that already sits with a formal control board. It also fits poorly when the real risk lives inside one allowed file, because a correct path list can still hide a bad permission check. Teams that cannot name a rollback owner should not send the patch to any shared host, free or otherwise. A zero exit from the checker is a boundary result, not an approval to deploy the change.

The worked example is a method, not a report of avoided outages or saved hours for any team. No customer outcome is claimed, and the script is not presented as an executed suite from this account. Adapt the manifest to the real repository layout before a zero exit is treated as permission to continue. Readers who draft with MonkeyCode can keep this manifest as the gate, and use the free server only after the checker exits cleanly.

Keep the Stub Gate Before Generated Workers Send Live Traffic

Avery Li — Fri, 09 Oct 2026 15:30:54 +0000

Keep the Stub Gate Before Generated Workers Send Live Traffic

A pairing should keep one fixture gate before any generated job is allowed to call a live model endpoint. The gate runs against frozen inputs and a local stub, then fails closed when network access appears by accident. Shared free model access and a free server option stay outside that gate until a human reviews the same diff. This worked example records the questions, two dead ends, and the single decision the pair kept.

Claims used, and claims left out

Disclosure: This article was prepared as part of MonkeyCode's product outreach. The operator supplied two availability claims for this draft: free model access and a free server option. This exercise does not treat model names, numeric quotas, hardware, duration, or permanence as known facts. Readers should confirm those details with current product documentation before relying on them in a workflow.

The constraint that opened the session

The junior brought a generated worker that summarized error reports and posted results to a remote host. The senior refused to review hosting details until the test story was safe to run on a laptop with the network off. The pair treated the model call as an untrusted dependency, not as a source of expected prose. The session therefore started from written constraints rather than from a generated test that already looked green.

Questions recorded before any code landed

The senior asked four questions and wrote each answer into the pairing note before any code landed. The first question asked whether the same test could pass while outbound network access stayed disabled. The second question asked which fields were allowed to leave the process inside logs or traces.

The third question asked what should fail closed when the endpoint variable was empty or unset. The fourth question asked where, if anywhere, a free server belonged inside this particular code change. The pair answered that a free server did not belong in the test change at all. That answer stayed in the note so a later deploy discussion could not smuggle the host back into CI.

Dead end one: a live call dressed as a test

The first draft asked a code assistant to add a realistic integration test against the live endpoint. That test asserted on sentences in the model reply and printed the full payload when the assertion failed. The senior stopped the draft because prose is not a stable contract and a red failure would leak the report text into CI logs. The pair also refused to spend shared model access on every pull request just to watch wording drift.

Dead end two: a golden file of full replies

The second draft stored a complete model reply and compared each new output byte for byte. That approach died in review because a free model can change wording without changing the fields the worker actually needs. The senior would not invent a score, a latency budget, or a quota number to make the golden file look scientific. The pair deleted the fixture of full prose and kept only the input reports plus a structural expectation.

The decision the pairing kept

The pair kept a fixture gate with three rules and rejected every looser option in the same note. The default transport is a local stub that returns fixed JSON and never opens a socket. Structural checks cover required keys, a maximum length, and the absence of a secret marker string. A live call requires an explicit flag that CI does not set, and the free server is not a test target at all.

How the rejected options compare

A short table made the rejection visible to the next reviewer without replaying the whole conversation. Each row records the network need, the CI stability, and whether the pair kept the option. The table is a review aid for this exercise, not a benchmark against any named vendor. Readers can extend a row only when a new option still passes with the network disabled.

Option	Network in CI	Stable contract	Kept
Live prose assertion	Required	No	No
Golden file of full replies	Required	No	No
Stub plus structural checks	None	Yes	Yes
Free server as the test host	Required	No	No

Where the two availability claims fit

Free model access can help a developer draft the worker after the gate already passes on the stub. A natural next check is one manual run of the same structural function against a reviewed client. CI should then return to the stub so shared access is not spent on wording drift. That single manual pass only shows whether required keys survive one real reply during review.

Step 1: Freeze the input fixture

The gate starts from a small JSON file that the pair can read in one sitting. Each case carries an input report, a forbidden marker, and the keys the worker must return. The file does not store a preferred paragraph, because the session already rejected prose contracts outright. A reviewer can add a case without touching the transport code or the live flag policy.

{
  "cases": [
    {
      "id": "timeout-report",
      "report": "checkout timed out after the retry budget",
      "forbidden_marker": "sk-live-example",
      "required_keys": ["summary", "action"]
    }
  ]
}

Step 2: Select a stub and fail closed

Save both Python blocks as fixture_gate.py, and treat them as a local exercise rather than a measured vendor run. It selects the stub unless the caller passes a live flag and a non-empty endpoint string. Empty configuration raises before any socket is opened, which keeps accidental live calls from starting at all. The stub returns only the keys the fixture requires, which keeps the test honest about structure.

import json
from pathlib import Path

class GateError(RuntimeError):
    pass

def load_cases(path):
    data = json.loads(Path(path).read_text(encoding="utf-8"))
    if "cases" not in data or not data["cases"]:
        raise GateError("fixture missing cases")
    return data["cases"]

def stub_complete(report):
    return {"summary": report[:80], "action": "review"}

def select_transport(live, endpoint):
    if not live:
        return stub_complete
    if not endpoint:
        raise GateError("live flag set but endpoint is empty")
    raise GateError("live transport is operator-owned and not bundled here")

Step 3: Check keys, length, and the marker

The checker does not score writing quality and does not call a model to judge a model. It confirms required keys, rejects unexpected types, and scans only the payload for the forbidden marker. A maximum length stops a generated worker from dumping an entire report into the summary field. Failures name the case id so a pairing note can point at one failing row later.

def check_case(case, transport):
    payload = transport(case["report"])
    if not isinstance(payload, dict):
        raise GateError(f"{case['id']}: payload is not an object")
    missing = [key for key in case["required_keys"] if key not in payload]
    if missing:
        raise GateError(f"{case['id']}: missing {missing}")
    summary = str(payload.get("summary", ""))
    if len(summary) > 120:
        raise GateError(f"{case['id']}: summary exceeds 120 characters")
    marker = case.get("forbidden_marker", "")
    if marker and marker in json.dumps(payload):
        raise GateError(f"{case['id']}: forbidden marker present")
    return payload

def run_gate(path, live=False, endpoint=""):
    transport = select_transport(live, endpoint)
    return [check_case(case, transport) for case in load_cases(path)]

Step 4: Prove the default path never goes live

A reviewer can execute the default path in a clean shell without exporting an endpoint variable. The command below writes a one-line result and does not contact a model or a server. CI should call the same function with the live argument left false on every pull request. The live branch in this draft raises on purpose, so a generated edit cannot silently grow a real client.

mkdir -p fixtures
python - <<'PY'
from fixture_gate import run_gate
rows = run_gate("fixtures/reports.json", live=False, endpoint="")
print(f"kept {len(rows)} structural result(s); live transport not used")
PY

Step 5: Add a negative test for the marker

A second test feeds a transport that echoes the forbidden marker and expects the gate to raise. That failure is the point of the check, because a green run on the stub alone would miss a leaky client. The test file stays local and does not import a vendor SDK or read a secret from the environment. A reviewer runs it with the standard library unittest runner before accepting the generated worker diff.

import unittest
from fixture_gate import GateError, check_case

CASE = {
    "id": "marker-case",
    "report": "checkout timed out after the retry budget",
    "forbidden_marker": "sk-live-example",
    "required_keys": ["summary", "action"],
}

def leaky_transport(report):
    return {"summary": "sk-live-example", "action": "review"}

class GateTests(unittest.TestCase):
    def test_leaky_transport_fails(self):
        with self.assertRaises(GateError):
            check_case(CASE, leaky_transport)

if __name__ == "__main__":
    unittest.main()

python -m unittest test_fixture_gate.py

Step 6: Record the decision before any remote target

The pairing note is part of the artifact, not a chat scroll that disappears after the session. It names the questions, the two rejected drafts, and the rule that CI never sets the live flag. Only after that note exists should an operator consider pointing a separate, reviewed client at free model access. A free server, when one is actually assigned, belongs in a later deploy change with its own review.

decision: fixture-gate-v1
default_transport: local_stub
ci_live_flag: absent
free_server_in_this_change: no
rejected: live prose assertion; full-reply golden file

Limitations that the note should keep visible

The gate does not prove that a summary is correct, useful, or safe for customers to read. It does not measure latency, token spend, uptime, or how long any free option will last. It will miss a secret that uses a different shape than the marker stored in the fixture. It also will not stop a later deploy step from binding a public port or writing real user data.

Who should not use this gate

Teams that need a formal evaluation suite for model quality should build that suite on purpose, with owned data and a stated rubric. This gate is the wrong tool for medical, financial, or other high-stakes text, because a key check is not a domain review. Operators without a written rule for live flags should not add a remote host just to see a green run. Generated clients that must call arbitrary URLs also fall outside this kept decision and need a different review.

After the local gate already passes

Readers who already hold an approved account can reuse this gate and attach their own endpoint outside CI. No claim is made here that one host is faster, cheaper, or more reliable than another host. A free server option, if the operator assigns one, still waits for a separate deploy review. The gate itself does not require any vendor SDK, token, or hostname to pass on a laptop.

Closing the pairing note

The pair left with one kept decision: structural checks on a stub, live traffic opt-in only, and no free server inside the test change. A later session can review deploy config, but it should not reopen the rejected golden file. Developers can copy the module, point it at their own fixture, and keep the live flag out of CI.

Date the Quota Card Before Generated CI Targets a Free Server

Avery Li — Thu, 08 Oct 2026 10:49:25 +0000

A generated CI job should not target a free model server until a fresh quota card sits beside the change. That card records the allowance a person just confirmed, the server boundary, and the time of the check. A senior pairing kept this single gate after two cheaper ideas failed during the same review. The workflow below is a labeled exercise, not a record of private production metrics or customer results.

The question the pairing had to settle

The working question stayed narrow for a small team that already reviews generated changes before they leave. The pair asked whether a generated workflow could use free model access without a dated local card. The senior also required the current project page, the job boundary, and the failure behavior when either fact was missing. MonkeyCode enters the exercise only as the source of those two operator-supplied availability claims, and the rest of the method stands alone.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Questions the senior actually asked

The session log kept four requests, and each request had to be answered with a file or a refusal. The first request demanded the documentation timestamp rather than a recollection of an earlier campaign page. The second request demanded a server name that was not production and was not a shared customer environment. The third request demanded the exit code when the card was missing, stale, or pointed at a forbidden boundary.

The fourth request demanded that campaign numbers stay out of the job file even when a person believed those numbers were still current. Each answer had to fit on the card or in the gate output, because a verbal reassurance was not accepted as evidence. The pairing stopped when those four answers existed as files, and it did not continue into model selection.

Dead ends that looked faster

The first dead end treated an outreach sentence as a permanent quota contract for the build. A quoted token pool, including any large round number in a campaign note, was refused as a build input. Allowances change, and a hardcoded count would become stale without a visible failure at generation time. The second dead end sent the generated job to a shared free server and hid the boundary until afterward.

The decision that stayed

The pairing kept one decision and dropped every faster alternative that skipped the local freshness check. No generated job file may be written unless a local quota card is present, fresh, and explicit about the server boundary. A person fills that card after reading the current project documentation, not the model that drafts the workflow. Free model access and a free server option may be used only inside that recorded boundary, and live docs should be rechecked first.

This exercise does not name models, publish quotas, describe hardware, or promise how long either free option will remain available. Readers should treat every allowance figure in campaign copy as untrusted until a person copies a current observation into the card. The card may say that free model access and a free server option were visible, but it may not invent a token total. A future change in those offers should fail the next review instead of silently riding an old sentence.

Numbered workflow

Open the current project documentation and record only the claims a person can verify on that page today.
Write those observations into a local quota card with a UTC timestamp, a maximum age, and a non-production server label.
Run the gate so a missing, stale, or production-bound card exits non-zero before any workflow file is created.
Allow a generator to draft a job only after the gate prints a success token, and keep the card in the same review.
Re-run the same gate in CI so a card older than the agreed window fails closed instead of spending an unverified allowance.

What the card is allowed to store

The card is a review artifact rather than a billing API, and it is also not a secret store. It may store the check time, the maximum age, the server boundary, and two booleans for the offers a person just saw. It may store a short note that says where the person looked, without pasting a promotional paragraph into the repository. It must not store tokens, passwords, customer identifiers, or a guessed remaining balance from any earlier page.

The gate script

The Python below is a proposed local gate for the exercise, and it has not been presented as a measured production control. The script does not call a network, does not invent a quota, and does not deploy or configure a server. It only accepts or rejects the card a person already wrote after checking the current documentation. Placeholder values in the sample card are not product facts and must be replaced before any real use.

#!/usr/bin/env python3
"""Proposed gate: refuse a generated job until a fresh quota card exists."""
import json
import sys
from datetime import datetime, timedelta, timezone
from pathlib import Path

REQUIRED = (
    "checked_at",
    "max_age_hours",
    "server_boundary",
    "free_model_access",
    "free_server_option",
)
FORBIDDEN = {"production", "prod", "shared-prod"}

def load_card(path: Path) -> dict:
    data = json.loads(path.read_text(encoding="utf-8"))
    missing = [key for key in REQUIRED if key not in data]
    if missing:
        raise SystemExit("CARD_MISSING_FIELDS")
    return data

def assert_fresh(card: dict, now: datetime) -> None:
    checked = datetime.fromisoformat(card["checked_at"])
    if checked.tzinfo is None:
        raise SystemExit("CARD_TIME_NAIVE")
    age = now - checked
    limit = timedelta(hours=float(card["max_age_hours"]))
    if age > limit or age < timedelta(0):
        raise SystemExit("CARD_STALE")

def assert_boundary(card: dict) -> None:
    boundary = str(card["server_boundary"]).strip().lower()
    if not boundary or boundary in FORBIDDEN:
        raise SystemExit("CARD_BOUNDARY_REFUSED")
    offers_ok = (
        card["free_model_access"] is True
        and card["free_server_option"] is True
    )
    if not offers_ok:
        raise SystemExit("CARD_OFFER_UNCONFIRMED")

def main() -> int:
    card = load_card(Path(sys.argv[1]))
    assert_fresh(card, datetime.now(timezone.utc))
    assert_boundary(card)
    print("CARD_OK")
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

A sample card follows. Replace every field after a live check, and do not copy a campaign token count into the notes.

{
  "checked_at": "2026-10-08T09:00:00+00:00",
  "max_age_hours": 24,
  "server_boundary": "scratch-free-server",
  "free_model_access": true,
  "free_server_option": true,
  "notes": "Confirmed from current docs on the check date."
}

python3 quota_gate.py quota_card.json

Decision table the senior kept

Situation	Gate result	Next action
Card file missing	Fail closed	Read current docs, then write a card
Required field absent	Fail closed	Fill only observed fields
Timestamp older than max age	Fail closed	Repeat the live check
Boundary is production	Fail closed	Use a named scratch server
Offer flags are not true	Fail closed	Do not assume free access remains
Card fresh and boundary explicit	CARD_OK	Review the job with the card

Reviewing the job after the gate

A passing card does not approve the generated workflow by itself, because the boundary can still be wrong. The reviewer still checks that the job name matches the server boundary and that no secret is interpolated into the steps. A proposed job fragment, which was not executed in this exercise, should stay this small on purpose. Anything broader than a scratch command belongs in a separate review rather than in the first free-server trial.

# Proposed fragment only. Do not run until the quota card prints CARD_OK.
name: scratch-free-server-check
runs-on: scratch-free-server
steps:
  - name: show-boundary
    run: printf '%s\n' "$SERVER_BOUNDARY"

The fragment intentionally has no model call, no deploy step, and no credential file in the first trial. Adding those later requires a new card and a new decision, not an edit hidden inside the same diff. The senior treated that separation as part of the kept decision rather than as optional polish for later. A generator that wants a richer job can propose it, but the gate still runs before that proposal is accepted.

Test plan for the exercise

Reviewers should run five local fixtures before they trust the gate during an ordinary repository review. A missing file should fail, and a card without a timestamp should fail with a field error. A timestamp older than the stated maximum age should fail, and a production boundary should fail as well. A fresh scratch-server card should print the success token and should not claim anything about model quality or capacity.

A short proposed test can encode those expectations without touching a network or a remote host. The test below is unexecuted example code for the exercise, and a team should run it locally before relying on the messages. Failure strings stay stable so a later workflow can match them without parsing free-form prose from the gate. Passing this file does not prove that a remote free server is healthy or that an allowance remains.

"""Proposed local checks. Unexecuted here; run only after a local review."""
from datetime import datetime, timedelta, timezone
from quota_gate import assert_fresh, assert_boundary

def expect_exit(fn, code):
    try:
        fn()
    except SystemExit as exc:
        if str(exc) != code:
            raise SystemExit("CHECK_MISMATCH")
    else:
        raise SystemExit("CHECK_MISSING")

def main():
    now = datetime.now(timezone.utc)
    stale = {
        "checked_at": (now - timedelta(hours=30)).isoformat(),
        "max_age_hours": 24,
    }
    expect_exit(lambda: assert_fresh(stale, now), "CARD_STALE")
    refused = {
        "server_boundary": "production",
        "free_model_access": True,
        "free_server_option": True,
    }
    expect_exit(lambda: assert_boundary(refused), "CARD_BOUNDARY_REFUSED")
    print("LOCAL_CHECKS_OK")

if __name__ == "__main__":
    main()

Limitations and who should skip it

This gate does not prove that a free allowance remains available after the card was written. It does not select a model, estimate cost, authorize sensitive data, or replace human review of the generated workflow. A team that cannot spare a person to refresh the card should not adopt the approach for unattended generation. A team that needs a contractual quota, a named support window, or a production server should not treat a free option as that contract.

The pairing also refused to store campaign copy, including any round token figure, inside the generated job definition. Secrets, private repositories, and customer payloads stay out of the scratch job even when the card is fresh. The script can be wrong if the operator types a false confirmation, so the card belongs in the same review as the job. None of these checks measure latency, accuracy, or how many requests a free server will accept.

Where the review stops

The useful outcome is a small refusal that keeps generated CI on the laptop until the quota card is fresh. Teams that already separate a proposal from execution can place the script beside that existing review. Others can confirm the live docs still match the card before they accept a scratch job in the change. That confirmation is the only invitation this exercise offers, and it stays optional until the card is honest.

Record the Read Set Before a Free Model Drafts the Next Test

Avery Li — Thu, 08 Oct 2026 08:24:51 +0000

A pairing should record the allowed read set before a free model drafts tests or a free server executes them. The kept decision in this worked example stays narrow, concrete, and easy for a later reviewer to audit. Generated checks may read only a synthetic fixture tree, and the remote job specification may carry no credentials. These notes describe a proposed session rather than a measured incident, and every command below remains an unexecuted example.

Why the boundary comes first

Developers who generate tests from a private repository often attach broad context and then hope the model will ignore secrets. A senior pairing treats that hope as a failed control, because the upload itself is the event that cannot be undone. The useful artifact is a read-set manifest that names every file allowed into the prompt and every path refused by the server. MonkeyCode's free model access and free server option become relevant only after that manifest exists and a human signs it.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The availability claims in the previous paragraph are operator-supplied, and this draft deliberately stops at those two claims. No model name, quota, hardware shape, duration, or permanence appears here, because those details were not verified from a primary source. Readers should confirm the current terms themselves before they attach any repository or start any remote execution. The gate remains useful if the product name is removed, because the control is ordinary Python plus a written decision record.

Recent public writing about generated interfaces and assisted coding shows the same pressure, which is speed competing with review. This article does not treat those titles, reaction counts, or anecdotes as evidence about any model. The durable problem is older than the current week: a draft can look helpful while the context beside it is still private. A pairing session is one way to force that problem into a file a reviewer can diff.

Questions the senior asked

The senior did not begin with prompt wording, and instead pinned five questions to the pairing board before any draft started. Each question had to end in a kept answer, a rejected alternative, or an explicit dead end with a reason. The board prevented the session from drifting into model comparison, benchmark talk, or unverified claims about remote capacity. The list below is the working record for this proposed session, not a transcript from a named team.

Which paths may enter the model context, and which paths stay forbidden even when a test seems to need them?
May the free server mount anything outside the synthetic fixture directory during this session?
Which environment names are allowed in the job spec, and which names are always rejected?
What happens when the generator asks for a production-shaped dump in order to reproduce a bug?
Who signs the decision record, and which change requires the pairing to reopen before the next draft?

The senior required each answer to name an owner, a file path, and a condition that would invalidate the answer later. Vague notes such as a general warning about secrets were rejected, because a warning cannot be tested or diffed in review. The manifest file is the test, since a reviewer can see the allowed list without reconstructing the conversation. That standard also stops a later edit from smuggling a dump into the prompt under a friendlier filename.

Dead ends the pairing refused

The first dead end was a proposal to sanitize a database dump and then upload the sanitized copy with the prompt. Sanitization scripts miss new column names, copied tokens in comments, and fixtures that developers later paste back by hand. The senior rejected that path because a partial redaction still teaches the team to move private data toward the model. The kept alternative was a hand-built synthetic tree that contains shapes and statuses, but never customer values.

The second dead end was a request to let the free server run the existing integration suite against a shared staging account. That request looked efficient, yet it would place credentials, network reach, and generated code in the same job. The pairing refused it, because a generated test that only reads can still print headers, follow redirects, or write files. Remote execution stayed limited to a unit run over the synthetic tree, with network egress left unspecified on purpose.

The third dead end was an attempt to compare unnamed free models by latency before the read set was stable. Timing numbers would have been meaningless, and this draft has no verified benchmark method or hardware description to publish. The senior parked comparison work until the same manifest, the same fixtures, and the same commands could be repeated. That pause kept the session on a decision a reviewer can check, rather than on a leaderboard nobody can reproduce.

The decision that stayed

The pairing kept one decision and wrote it in a single sentence at the top of the record file. Generated tests may be drafted from the manifest, and they may run only where the fixture root is the sole mounted data path. Any request for a dump, a token, a cloud key, or a production hostname reopens the pairing instead of extending the prompt. The record names the signer role, the session date, and the commit that the manifest claims to describe.

Run the gate in seven steps

The workflow below is a tutorial sequence for a local gate, and it assumes a Unix shell plus Python 3.10 or newer. Operators should run it on a disposable copy of the repository, then inspect the manifest before any model call. The steps do not deploy infrastructure, open a network listener, or contact a remote API by themselves. A later human may paste the reviewed manifest into a coding session only after the blocked list is empty or explicitly accepted.

Create an isolated work directory and a synthetic fixture root that holds invented records only.
List candidate prompt files in a plain text inventory, with one relative path on each line.
Run the gate script so it rejects secret-like names, forbidden directories, dumps, and oversized files.
Read the decision record and confirm the kept sentence is still the header a reviewer will see.
Emit a job spec that mounts only the fixture root and sets no secret environment variables at all.
Run the unit command locally against those fixtures, and archive the manifest beside the test output.
If a generator asks for more files, add them to the inventory and repeat the gate before the next draft.

A clean local run is not permission to skip the human read of both JSON files the script writes. The script can only see the inventory it was given, so files pasted into a chat by hand bypass it completely. The pairing therefore treats the chat box as untrusted until the same paths appear in the allowed list. That rule is the practical difference between a written control and a good intention that nobody can audit later.

Read the proposed script

The following Python example is a proposal for the local gate, and it has not been executed in this drafting session. It reads an inventory file, applies a small denylist, and writes a JSON decision record that a reviewer can diff. It also writes a job spec whose data mount is fixed to the fixture root and whose environment block stays empty. Teams should treat the patterns as a starting filter, not as a complete secret scanner or a compliance certification.

#!/usr/bin/env python3
"""Unexecuted example: build a read-set manifest and a secret-free job spec."""

import json
import sys
from pathlib import Path

FORBIDDEN_PARTS = {
    ".env",
    ".pem",
    ".key",
    "id_rsa",
    "secrets",
    "credentials",
    ".git",
}
MAX_BYTES = 200_000
FIXTURE_ROOT = "fixtures/synthetic"
KEPT = "fixtures-only-no-credentials"


def reject(path: Path) -> str | None:
    lowered = path.as_posix().lower()
    if any(part in lowered for part in FORBIDDEN_PARTS):
        return "forbidden-name"
    if path.suffix.lower() in {".pem", ".key", ".p12", ".sqlite"}:
        return "forbidden-suffix"
    outside = "fixtures/synthetic" not in lowered
    if outside and path.suffix.lower() in {".sql", ".dump", ".bak"}:
        return "data-dump-outside-fixtures"
    if not path.exists():
        return "missing"
    if path.stat().st_size > MAX_BYTES:
        return "too-large"
    return None


def main() -> int:
    inventory = Path(sys.argv[1] if len(sys.argv) > 1 else "readset.txt")
    allowed, blocked = [], []
    for line in inventory.read_text(encoding="utf-8").splitlines():
        rel = line.strip()
        if not rel or rel.startswith("#"):
            continue
        reason = reject(Path(rel))
        if reason:
            blocked.append({"path": rel, "reason": reason})
        else:
            allowed.append(rel)
    record = {
        "decision": KEPT,
        "fixture_root": FIXTURE_ROOT,
        "allowed": allowed,
        "blocked": blocked,
        "signer_role": "pairing-senior",
        "status": "proposed-unverified",
    }
    Path("decision-record.json").write_text(
        json.dumps(record, indent=2), encoding="utf-8"
    )
    spec = {
        "mounts": [{"source": FIXTURE_ROOT, "target": "/work/fixtures"}],
        "env": {},
        "command": ["python", "-m", "unittest", "discover", "-s", "tests"],
        "network": "unspecified-do-not-assume-egress",
    }
    Path("job-spec.json").write_text(
        json.dumps(spec, indent=2), encoding="utf-8"
    )
    print(f"allowed={len(allowed)} blocked={len(blocked)}")
    return 1 if blocked else 0


if __name__ == "__main__":
    raise SystemExit(main())

The shell fragment below is also an unexecuted example, and it only creates local files for the gate to read. It does not call a model, publish a draft, or open a socket toward a free server of any kind. Operators who adapt the paths should keep the fixture directory free of copied production rows and live tokens. A missing file is a blocked file on purpose, so the inventory cannot name a path the reviewer cannot open.

mkdir -p fixtures/synthetic tests
printf '%s\n' '{"id":"sample-1","status":"queued"}' > fixtures/synthetic/orders.json
printf '%s\n' 'tests/test_status.py' 'fixtures/synthetic/orders.json' > readset.txt
python3 gate_readset.py readset.txt

A failing exit status means the inventory still contains a blocked path, so the pairing does not proceed to a model call. A clean exit only means the small filter accepted the listed paths, not that those files are safe for every policy. Reviewers should open both JSON files and confirm that the environment object is empty before any paste into a chat. If the job spec gains a token, a host key, or a second mount, the kept decision is already broken.

Classify requests before they reopen

The table records how the pairing classified common requests, so a later author does not relitigate them in a side channel. Rows are teaching examples for this method, and they are not measurements from a live service or a customer system. A request that does not fit a row should reopen the pairing rather than receive an improvised exception in the prompt. The last rows also show who should stop, which matters as much as the happy path through the gate.

Request during the session	Classification	Reason kept on the board
Synthetic JSON fixtures under 200 KB	Keep	Shapes and statuses without customer values
Sanitized production dump in the prompt	Dead end	Redaction misses new fields, comments, and later pastes
Existing integration suite against staging	Dead end	Credentials and generated code would share one job
Latency comparison of unnamed free models	Dead end	No verified hardware or repeatable method in this draft
Extra source file added after sign-off	Reopen	The manifest must be regenerated and signed again
Environment entry whose name looks like a token	Reject	The job spec environment object must stay empty

Limitations of the filter

The filter misses secrets that use ordinary filenames, split tokens, or values buried inside seemingly harmless test helpers. It does not inspect archive contents, notebook outputs, git history, or environment variables already present in the parent shell. Substring checks can also false-positive on innocent names that merely contain a forbidden fragment such as a secret-related word. A reviewer still has to read the allowed list, because a green exit status is not a review.

A free server option does not, by itself, prove network isolation, data retention, region placement, or deletion timing. Those properties require current vendor documentation and, where the data is regulated, a review that sits outside this article. The worked example invents no quota, no uptime figure, and no claim that a free tier will remain available on a later date. Authors who need a guaranteed capacity number should stop and read the provider terms rather than infer one from a blog post.

The script is a poor fit for binary protocols, huge monorepos, or repositories that cannot spare a synthetic fixture tree. In those cases the pairing should keep the refusal and choose a different test design, not weaken the denylist to finish the draft. Generated code can still be wrong, unsafe, or incomplete even when the read set is clean. The gate protects the boundary around the session, and it does not certify the tests the model returns.

Who should leave this method alone

Teams that must process production data, payment data, or other regulated records should not route that material through this gate. The method is a local hygiene step for synthetic tests, not a data-loss prevention product and not a legal control. Operators who cannot review the manifest before a model call will not get the benefit the pairing was designed to keep. Anyone who needs unpublished benchmarks, named hardware, or a permanent free allocation will not find those facts in this draft.

What the session closes on

The session ends when the decision record, the empty environment block, and the synthetic fixture root all agree with one another. A later draft may improve test names and assertions, but it should not reopen the read set without the same senior review. Readers who already keep a fixture tree can run this local gate before they choose any coding assistant at all. If a free model and a free server still fit after that review, the current MonkeyCode terms are the right place to confirm availability.

Freeze One Command Allowlist Before a Generated Script Leaves the Laptop

Avery Li — Thu, 24 Sep 2026 22:04:10 +0000

A generated maintenance script should stay on the laptop until a senior pairing freezes one command allowlist and one comment rule. The useful result is an execution card that a second engineer can replay, not a shorter diff chosen for style alone. That card separates read-only inspection from a single mutation and rejects every extra command a model appends later. Teams that skip the card often meet the blast radius only after a formatter, an installer, or a comment rewrite has already landed.

What the pairing is deciding

This section is a proposed pairing session, not a measured outage report and not a personal benchmark from the publishing account. The pair reviews a module whose comments grew across several generated patches and now obscure the real constraints. A current developer conversation treats comments as the enemy of clean code, which tempts a generator to delete them in bulk. The senior treats that temptation as a risk, because a deleted constraint may be the only record of a failure mode.

Questions the senior records

The senior does not ask the model to score the laptop against a server the pair has not instrumented. The first recorded question asks which comment states a constraint that no current test actually enforces. The second recorded question asks which planned command writes files and which planned command only reads the tree. The third and fourth questions ask which tool versions must match and which output counts as evidence rather than suggestion.

Dead ends the pair refuses

The first dead end is a blanket comment purge driven by a style slogan rather than by a failing test. The second dead end is a generated comparison of machines that the pair never instrumented and cannot reproduce. The third dead end is an install command that appears helpful only because a linter is missing from the environment. The fourth dead end is a green format run that the pair mistakes for proof that runtime behavior stayed the same.

Each dead end fails for the same structural reason, even though the surface tasks look unrelated to one another. Generated text widens authority when a keeper has not yet named the allowed files, commands, and evidence. The pair therefore writes the refusal into the card, so a later model call cannot quietly reopen the same path. A refusal without a stored reason tends to be re-argued on the next patch, which wastes the senior's review time.

The decision that stays

The pair keeps a three-gate execution card together with a narrow rule for when a comment may be removed. A comment may be removed only when the keeper maps it to a test, a type, or an existing public document. Read-only commands may run on the laptop first and may be repeated on a separate server only if that option already exists. Exactly one mutating command may run after both read gates pass against the same frozen plan and the same fixture.

Any new flag, pipe, redirect, or network tool voids the card and sends the pair back to review. The model may suggest a better command, but that suggestion starts a new card instead of editing the accepted one. This rule is stricter than a typical format-on-save habit, and that strictness is the point of the pairing. The kept decision is small enough to audit in one sitting and specific enough to block a widened script.

Step 1: Freeze the comment disposition

The keeper writes a disposition file before any model is allowed to edit prose in the module. Each entry names the file, a stable anchor phrase, an action, and a reason a reviewer can check later. Dropping a comment requires a pointer to a test name or a type that already carries the same constraint. Keeping a comment requires a one-line failure mode, not a restatement of the code that immediately follows it.

# proposal: unexecuted disposition, not a production record
- file: src/report.py
  anchor: "retry only on 429"
  action: keep
  reason: "failure mode not expressed by test_report_backoff"
- file: src/report.py
  anchor: "loop over rows"
  action: drop
  reason: "narrates the next line and carries no constraint"

The sample above is an unexecuted proposal for the review packet, not a log from a production repository. A generator may draft candidate lines, yet the keeper commits the file before any further generation continues. If an anchor phrase no longer exists in the file, the entry is stale and the card returns to the senior. The disposition file stays beside the command plan so both artifacts are reviewed as one decision.

Step 2: Freeze the command plan as argv

The command plan is a JSON list of argv arrays, because a raw shell string hides pipes and redirects. Each entry carries an identifier and a class of read or mutate, and the plan allows exactly one mutate entry. The checker in this section is a proposal for local review, and it is not offered as a published benchmark. It refuses network-shaped binaries, shell metacharacters, and any mutating argv that leaves the single kept formatter.

#!/usr/bin/env python3
"""Proposal: reject a command plan that leaves the frozen allowlist."""
import json
import sys

NETWORK = {"curl", "wget", "ssh", "scp", "nc", "pip", "npm", "pnpm"}
META = set("|;&<>`$")
KEPT_MUTATE = ["python", "-m", "ruff", "format", "src/report.py"]

def fail(msg: str) -> None:
    raise SystemExit(f"plan rejected: {msg}")

def main() -> None:
    plan = json.load(sys.stdin)
    cmds = plan.get("commands")
    if not isinstance(cmds, list) or not cmds:
        fail("commands must be a non-empty list")
    mut = [c for c in cmds if c.get("class") == "mutate"]
    if len(mut) != 1:
        fail("the kept card requires exactly one mutate command")
    for c in cmds:
        argv = c.get("argv")
        kind = c.get("class")
        if not isinstance(argv, list) or not argv or kind not in {"read", "mutate"}:
            fail("each command needs class and argv")
        if argv[0] in NETWORK:
            fail("network or installer binary is blocked")
        if any(any(ch in arg for ch in META) for arg in argv):
            fail("shell metacharacters are blocked")
        if kind == "mutate" and argv != KEPT_MUTATE:
            fail("mutate argv is outside the kept formatter")
    print("plan accepted", len(cmds))

if __name__ == "__main__":
    main()

{
  "intent": "inspect one module, then format that same file",
  "commands": [
    {"id": "c1", "class": "read", "argv": ["git", "status", "--short"]},
    {"id": "c2", "class": "read", "argv": ["git", "diff", "--", "src/report.py"]},
    {"id": "c3", "class": "mutate", "argv": ["python", "-m", "ruff", "format", "src/report.py"]}
  ]
}

A plan that fails the checker never leaves the laptop and never becomes input for a server session. The formatter exception is deliberate and narrow, so a later edit cannot swap in an installer under the same class. Teams with a different formatter should change that one tuple in review, rather than disabling the class check. The negative example in the next block should fail closed, because an installer is not a formatter.

python3 tools/check_plan.py < plan.json
sha256sum plan.json disposition.yaml
printf '%s\n' '{"commands":[{"id":"bad","class":"mutate","argv":["pip","install","ruff"]}]}' | python3 tools/check_plan.py

The first command accepts the frozen plan, and the second command records hashes the senior can sign later. The third command is a negative check, and a correct checker exits without printing an acceptance line. Those three commands are proposals for the packet, and they are not a claim that a particular repository already passed them. A keeper who changes the formatter tuple should update the negative check so the sample still matches the kept rule.

Step 3: Run the local dry-run gate

The local gate runs only commands marked read, using the same JSON document the checker already accepted. A small wrapper prints each argv and skips every mutate class so the first pass cannot change files. The pair stores that printed argv beside the disposition file, which makes a later server run comparable. If the worktree is already dirty, the pair stops, because a mixed tree makes the later diff meaningless.

python3 tools/check_plan.py < plan.json
python3 - <<'PY'
import json, subprocess
plan = json.load(open("plan.json"))
for c in plan["commands"]:
    if c["class"] != "read":
        print("skip mutate", c["id"])
        continue
    print("run", " ".join(c["argv"]))
    subprocess.run(c["argv"], check=True)
PY
git status --short
git diff --stat

After the read commands finish, the keeper inspects git diff and expects no content change from this gate. A surprise diff means a read command was misclassified, and the card is void until the class is corrected. The pair does not fix that surprise by editing files by hand inside the same gate. They open a new note, reclassify the command, and rerun the checker before any server is involved.

Step 4: Repeat the read-only gate away from the laptop

MonkeyCode enters this workflow only as an optional drafter of the plan and as an optional host for the read-only gate. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The operator-supplied context for this draft is free model access and a free server option, nothing more specific than that. This article does not name a model, state a quota, describe hardware, or claim that either option is permanent.

The drafting context for this card is 25 September 2026, and any availability claim should be rechecked on that product's current pages. A free model may propose disposition lines and a JSON plan, but those proposals remain untrusted until the checker passes. The keeper still commits the disposition file and still refuses any argv the allowlist does not already contain. A free server, when the team chooses to use one, should receive a copied fixture and the read-class argv only.

Secrets, credentials, and production configuration do not belong in that fixture, even for a short inspection. The server run is comparable only when the tool versions match the versions recorded on the local card. A version mismatch is a dead end, not a reason to let the model install a different toolchain on the server. If the two transcripts disagree, the mutation gate stays closed until a human explains the difference in writing.

The pair copies the printed argv and the exit status back into the review packet beside the local transcript. A matching pair of transcripts is the only signal that lets the keeper open the mutation gate. The free server option does not become a place to explore new commands once that signal is recorded. A missing exit status is treated as a disagreement, even when the printed argv looks identical.

Step 5: Allow one mutation and stop

The mutation gate runs the single kept formatter command and then stops, even if the model offers follow-up fixes. The keeper runs the focused tests named in the disposition file, not an open-ended suite invented during the session. A failing test reopens the card, because a format change that breaks behavior is still a behavior change. A passing test does not authorize a second command, a dependency bump, or a fresh comment rewrite.

python3 -m ruff format src/report.py
python3 -m unittest tests.test_report_backoff
git diff -- src/report.py
sha256sum plan.json

The diff is accepted only when every remaining comment still matches a keep entry or a justified drop entry. The senior signs the card by recording the plan hash, the two transcripts, and the test command that was actually run. Without that signature, the generated patch stays a proposal and does not move to a shared branch. The session ends on that kept decision, rather than on a general claim that generated maintenance is safe.

A table the keeper can copy

The table below compresses the card into four rows that a reviewer can check without rereading the whole transcript. It is a teaching artifact for this proposed session, not a measurement of product throughput or server capacity. Teams should edit the mutate row to match their own formatter, test runner, and repository policy. They should not add a row for package installation unless a separate reviewed change has already approved it.

Gate	Where it runs	What may run	What voids the card
Local dry-run	Laptop worktree	Read-class argv from the frozen plan	Dirty tree, mutate class, or a network binary
Read-only repeat	Free server option with a copied fixture	Same read-class argv when versions match	Secrets in the fixture, installers, or version drift
One mutation	Laptop after both transcripts agree	The single kept formatter argv	Extra flags, a second mutate, or a new file list
Evidence check	Review packet	Named tests, plan hash, and both transcripts	Unnamed suite, missing signature, or an unjustified drop

Limitations and who should skip the card

This approach does not prove that a free server is faster, cheaper, or safer than a local runner. It does not establish a quota, a hardware shape, a region, or a support commitment for any product option. It will not satisfy a compliance review that requires a signed attestation, a retained audit log, or a change-management ticket. The checker is a small proposal and has not been certified against hostile generated plans beyond the cases written here.

Incident response should not use this card, because a live outage needs a narrower runbook than a comment-and-format session. Repositories that contain secrets, production credentials, or customer data should not copy a fixture onto a shared server for this exercise. Teams without a named human keeper should not run the mutation gate, because the model cannot sign the card for them. Readers who need a specific model name, a token allotment, or a guaranteed free period will not find those facts in this article.

Replay the card on a low-risk module

A reader who already uses the product can replay this card on one low-risk module before trusting a larger generated patch. That replay is worthwhile only after the reader checks current terms and keeps the same human signature the session required. The article remains useful without the product, because the allowlist, the disposition file, and the three gates stand on their own. The kept decision is still the same: one frozen plan, read gates first, and a single mutation that a senior can explain.

The Pairing Froze a Search Tool Schema Before Generated Clients Could Call Out

Avery Li — Wed, 23 Sep 2026 17:29:36 +0000

A generated tool client should not call a live API until the pairing writes a frozen schema and a failing contract test. The session below reconstructs that sequence as a worked example, not as a production war story with invented metrics. The senior engineer treated every extra field, extra tool, and extra HTTP verb as a defect, even when the draft compiled. The kept decision was a one-page schema freeze that both humans and any later model had to obey.

Why the pairing started with a schema, not a client

The team needed a small Python client that would call one internal search tool through a model-mediated function call. Generated drafts looked complete, imported cleanly, and printed plausible JSON, which made the danger easy to miss. The senior pairing partner refused to review implementation files until a schema file existed in the repository. That refusal became the working method of the pairing, and it later blocked an invented second tool.

Tool calling is now a common way models reach HTTP APIs, which makes invented function names a merge-time defect instead of a demo joke. A client that compiles can still post the wrong verb, require a field the server ignores, or swallow an error envelope the on-call playbook does not know. The pairing therefore treated the JSON schema as the product, and treated generated Python as a disposable adapter. Clear names in the freeze file mattered more than tidy generated comments in the client module.

Questions the senior asked before any model ran

The senior did not start with a prompt. The senior started with a short oral checklist that had to produce written answers in the repository. Those answers were copied into contracts/search_tool.json before anyone opened a chat panel. The pairing recorded the questions as statements so later reviewers could audit them without watching the call.

Name the single tool the production gateway actually exposes, including the exact spelling the router already uses.
List required arguments, optional arguments, and arguments the server must never receive from a client.
State the HTTP method, path, and content type the gateway already documents for that one tool.
Describe the success envelope and the error envelope in field names, not in prose about likely status codes.
Decide which generated file is allowed to import the freeze file, and which files must stay empty until tests fail.

Each answer had to fit in the freeze file with no commentary about future tools. The junior engineer wanted a generic invoke_tool() helper that could grow with the model. The senior rejected that helper because growth was the failure mode the pairing was there to stop. One named tool stayed in scope for the rest of the afternoon.

Dead ends the pairing walked into and then discarded

The first dead end was a generated client that added list_indexes beside search_docs because the prompt mentioned a corpus. The extra tool looked helpful, imported without error, and would have been a production 404 with a confident traceback. The senior asked the junior to delete the file instead of commenting out the extra function. Deletion was the review comment, because leftover helpers invite the next model to revive them.

The second dead end was a required limit field that the live search endpoint treats as optional and caps server-side. The generated client refused to send a query without limit, which would have broken an existing caller that only passes q. The pairing restored limit as optional with a maximum of 50 in the freeze file. The client was not allowed to invent a default that the gateway did not already apply.

The third dead end was a polite GET with query parameters, which matched many public search APIs and matched nothing on this gateway. The documented route was POST /v1/tools/search_docs with a JSON body. The senior made the junior write that method and path as literals in the freeze file, not as comments above a requests call. After that change, any generated GET became a test failure rather than a style debate.

The fourth dead end was an invented error body with a retry_after field copied from unrelated HTTP client examples. The gateway returns { "error": { "code": "string", "message": "string" } } and nothing else. The pairing added a strict decoder that rejects unknown keys. Unknown keys are how generated clients smuggle policy that nobody on-call agreed to run.

The decision the pairing kept

The kept decision was written in the pull request, not in the chat transcript. It said the repository would ship one tool named search_docs, one freeze file, and one contract test that fails on extra tools, extra required fields, extra HTTP methods, and extra error keys. Generated clients could exist only as adapters that import that freeze file. Models could propose Python after the test failed, and they could not propose a second schema.

Signal in a draft	Pairing action	Reason kept in the freeze
New tool name	Delete the file	The gateway exposes one search tool
New required field	Fail the test	Callers already omit optional `limit`
GET or query string	Fail the test	The route is POST with a JSON body
Extra error key	Fail the test	On-call runbooks decode `code` and `message`
Helper named `invoke_tool`	Reject the helper	Genericity hides invented verbs

That table is the entire review policy for this worked example. It is boring on purpose, because boredom is cheaper than a wrong POST from a fluent client. The junior engineer kept a copy of the table next to the freeze file so later pairing sessions would not reopen the same four dead ends.

Artifact: freeze file, decoder, and a failing contract test

The artifact is a tiny Python package that any later model must import. The freeze file is the source of truth. The decoder refuses unknown keys. The test should fail before a generated client is allowed to exist in src/.

{
  "tool": "search_docs",
  "http": {
    "method": "POST",
    "path": "/v1/tools/search_docs",
    "content_type": "application/json"
  },
  "arguments": {
    "required": ["q"],
    "optional": ["limit"],
    "forbidden": ["index", "api_key", "retry_after"]
  },
  "limits": {
    "q_max_chars": 200,
    "limit_max": 50
  },
  "success": {
    "type": "object",
    "required": ["hits"],
    "properties": {
      "hits": { "type": "array" }
    },
    "additionalProperties": false
  },
  "error": {
    "type": "object",
    "required": ["error"],
    "properties": {
      "error": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": { "type": "string" },
          "message": { "type": "string" }
        },
        "additionalProperties": false
      }
    },
    "additionalProperties": false
  }
}

# tool_contract.py
from __future__ import annotations

import json
from pathlib import Path
from typing import Any, Mapping

FREEZE_PATH = Path("contracts/search_tool.json")


def load_freeze() -> dict[str, Any]:
    return json.loads(FREEZE_PATH.read_text(encoding="utf-8"))


def assert_no_unknown(obj: Mapping[str, Any], allowed: set[str], label: str) -> None:
    extra = set(obj) - allowed
    if extra:
        raise ValueError(f"{label} has unknown keys: {sorted(extra)}")


def validate_call(payload: Mapping[str, Any], freeze: Mapping[str, Any] | None = None) -> dict[str, Any]:
    freeze = freeze or load_freeze()
    args = freeze["arguments"]
    required = set(args["required"])
    optional = set(args["optional"])
    forbidden = set(args["forbidden"])
    allowed = required | optional

    assert_no_unknown(payload, allowed, "call")
    missing = required - set(payload)
    if missing:
        raise ValueError(f"missing required arguments: {sorted(missing)}")
    blocked = forbidden.intersection(payload)
    if blocked:
        raise ValueError(f"forbidden arguments present: {sorted(blocked)}")

    query = payload["q"]
    if not isinstance(query, str) or not query.strip():
        raise ValueError("q must be a non-empty string")
    if len(query) > freeze["limits"]["q_max_chars"]:
        raise ValueError("q exceeds q_max_chars")

    if "limit" in payload:
        limit = payload["limit"]
        if not isinstance(limit, int) or isinstance(limit, bool):
            raise ValueError("limit must be an int")
        if limit < 1 or limit > freeze["limits"]["limit_max"]:
            raise ValueError("limit outside allowed range")

    return {
        "tool": freeze["tool"],
        "method": freeze["http"]["method"],
        "path": freeze["http"]["path"],
        "json": dict(payload),
    }


def validate_error_body(body: Mapping[str, Any], freeze: Mapping[str, Any] | None = None) -> None:
    freeze = freeze or load_freeze()
    err_schema = freeze["error"]["properties"]["error"]
    if set(body) != {"error"}:
        raise ValueError("error envelope must contain only error")
    inner = body["error"]
    if not isinstance(inner, Mapping):
        raise ValueError("error must be an object")
    assert_no_unknown(inner, set(err_schema["properties"]), "error")
    for key in err_schema["required"]:
        if key not in inner or not isinstance(inner[key], str) or not inner[key]:
            raise ValueError(f"error.{key} must be a non-empty string")

# tests/test_tool_contract.py
import pytest
from tool_contract import load_freeze, validate_call, validate_error_body


def test_freeze_names_exactly_one_tool():
    freeze = load_freeze()
    assert freeze["tool"] == "search_docs"
    assert freeze["http"]["method"] == "POST"
    assert freeze["http"]["path"] == "/v1/tools/search_docs"


def test_call_accepts_q_without_limit():
    built = validate_call({"q": "pairing schema freeze"})
    assert built["json"] == {"q": "pairing schema freeze"}
    assert built["method"] == "POST"


def test_call_rejects_invented_tool_fields():
    with pytest.raises(ValueError, match="unknown keys"):
        validate_call({"q": "x", "index": "secret-corpus"})


def test_call_rejects_required_limit():
    freeze = load_freeze()
    assert "limit" not in freeze["arguments"]["required"]
    validate_call({"q": "x"})  # must remain legal


def test_error_rejects_retry_after():
    with pytest.raises(ValueError, match="unknown keys"):
        validate_error_body({"error": {"code": "busy", "message": "wait", "retry_after": 2}})

Example commands for the local loop, labeled as a proposed workflow rather than a measured benchmark:

python -m pip install pytest
python -m pytest tests/test_tool_contract.py -q

The tests above are the pairing's gate. A generated client that builds a GET URL, requires limit, or decodes retry_after should lose in pytest before it loses in staging. The freeze file is short enough to paste into a prompt, which is the point of keeping one tool.

Numbered loop the pairing ran after the freeze existed

Commit contracts/search_tool.json and the two Python files with no client module under src/.
Run python -m pytest tests/test_tool_contract.py -q and confirm the suite is green on the freeze alone.
Add a failing adapter test that imports a not-yet-written src/search_client.py and checks it uses validate_call.
Only then ask a model to write src/search_client.py against the freeze file, with the freeze pasted into the prompt.
Re-run the suite and delete the adapter if it introduces a second tool, a second verb, or a second error key.
Keep the pull request description as a copy of the decision table, not as a chat summary of how clever the draft looked.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. After the freeze file landed, the pairing used MonkeyCode's free model access and free server option to draft the adapter that had to import validate_call instead of inventing a payload. The product was treated as a constrained typist sitting behind the pytest gate, not as an owner of the HTTP contract. The humans still owned the kept decision, the unknown-key decoder, and the merge button.

A useful prompt shape for that step is boring and local. It names the freeze path, names the forbidden tools, and forbids new JSON keys. Example prompt text, not executed in this article: write src/search_client.py that imports validate_call, posts only the returned method and path, and contains no other function that sends HTTP.

Limitations, and who should not use this freeze

The freeze does not prove the gateway is healthy, fast, or correctly authorized. It only proves the client cannot invent a second contract while remaining green. A free model can still hallucinate if the freeze file is missing from the prompt, and a free server option is not a replica of production latency, headers, or identity. Teams still need a real staging route, a real credential store, and a human who can say the tool name out loud.

This approach is a poor fit when nobody on the team owns the live schema, because the freeze then becomes another invented document. It is also a poor fit for multi-tool agents that must discover routes at runtime, or for write endpoints where a wrong POST is destructive even with a strict decoder. Do not paste secrets into the prompt that carries the freeze file. Do not let the adapter retry, page, or mutate indexes unless those verbs are written in the freeze and in an on-call document.

Generated comments do not repair an invented tool. A fluent client with extra helpers is still a contract break, even when the helpers look like clean code. The pairing kept the schema small so later sessions could argue about search quality instead of arguing about which function names a model dreamed up.

Readers who want the same freeze-then-generate loop on a throwaway branch can try MonkeyCode's free model access and free server option after the contract test already fails for the right reason.

A Senior Pairing Stopped Invented API Load With One Kept Decision

Avery Li — Tue, 22 Sep 2026 15:42:43 +0000

Generated API tests stay honest only after pairing freezes a captured request mix, before any model writes load code. Models readily invent concurrent clients, think times, and endpoint weights that look professional while describing traffic that never existed. A senior pairing session can block that fiction by keeping one decision: the mix file is the only legal input. This article records the questions, the dead ends, and the small contract that followed from that kept decision.

Why invented load fails later

API performance work collapses when the request mix is a story rather than a sample from a real window. Synthetic clients then hammer rare write paths, skip cacheable reads, and report latency that no production user would ever observe. Reviewers argue about percentiles while the underlying shape of traffic remains an unexamined guess. Pairing with a senior engineer is useful here because the senior can refuse progress until that guess is replaced by a file.

Tool-calling demos and browser agents make this failure mode easier, not rarer, because fluent clients appear in minutes. A generated k6 or pytest harness can look complete while encoding a popularity ranking the logs never supported. The pairing problem is therefore not how to prompt a better client. The pairing problem is how to keep one traffic decision before any client exists.

A labeled pairing setup

The walkthrough below is a labeled pairing example, not a report of one named incident or a measured production outage. One senior engineer owns questions, vetoes, and the kept decision recorded in the repository. One implementer owns the fixture file, the loader, and the gate that later blocks generated tests. A shared scratch buffer holds the question log so dead ends remain visible after the session ends.

The pair agreed to treat OpenAPI as a catalog of legal routes, never as evidence of route weight. They also agreed that a previous load-test folder was historical material, not a default mix. No model was allowed to edit tests until the mix file had a hash in version control. That constraint felt slow at the start and cheap after the first dead end.

Questions the senior kept asking

The senior did not start with tools, frameworks, or model prompts, and that restraint shaped the rest of the session. Each question had to be answerable from logs, traces, or an explicit unknown, rather than from model fluency. The implementer wrote answers in the scratch buffer before anyone opened a code generator.

Name the ten-minute window this test may imitate, including weekday, hour, and traffic class.
List the routes that cover at least ninety percent of observed calls inside that window.
State the maximum concurrency the pair will still call realistic, rather than a coordinated stampede.
Separate latency budgets from sample observations, and refuse to let a generator blur those two numbers.
Define the failure when a generated client invents a route the mix file does not list.
Record who may refresh the mix file, and which pull request template must quote the new capture window.

After those answers, the senior still refused to let a model draft locust, k6, or pytest-benchmark glue. The unknown list was still longer than the known list, and that gap was treated as a blocker. Pairing continued into dead ends instead of into generated clients. The scratch buffer stayed the source of truth for what had already been rejected.

Dead ends the pair walked into

Dead end one treated a previous load-test repository as if it were current traffic from the same service. The old script used equal weights across every route, which flattered a checkout path that was rare in the weekday sample. Running it would have produced a confident p95 that described a synthetic crowd, not the captured window. The senior discarded the script because copying it would have laundered an invented mix through a familiar file name.

Dead end two asked a coding model to make the test realistic from the OpenAPI document alone. The generated client invented think times, a burst pattern, and a webhook route that the captured window never showed. The output compiled, named fixtures clearly, and still described a product that did not match production shape. The pair kept that prompt only as evidence of failure, then closed the branch without merging a single helper.

Dead end three tried to derive weights from handler counts in the router module, as if existence implied popularity. Route existence is not route popularity, and the senior rejected that proxy as a category error. A health endpoint and a catalog listing would have received similar weight under that rule, which the access sample immediately contradicted. The implementer then proposed sampling live traffic for ten minutes and writing weights by hand into a checked-in JSON file.

That third proposal survived because it produced an artifact a later gate could hash, diff, and refuse to skip. The senior asked one more question about freshness, then accepted a dated captured_at field as part of the contract. Pairing time spent on the three dead ends was shorter than the review time those dead ends would have created after merge.

The decision the pairing kept

The kept decision was narrow on purpose, so later models could not widen it through helpful extras. Generated tests may read fixtures/api_mix.json and must fail closed if the file is missing, empty, or lists no routes. Generated tests may not add routes, weights, think times, or concurrency values that the mix file does not already contain. Reviewers treat any pull request that hard-codes a mix in Python as a pairing violation, even when the numbers look conservative.

The decision also split two jobs that generators like to fuse. Capturing and editing the mix file remains a human pairing task with a dated window and a named source. Generating a loader, a schema check, and a client that only iterates the file is allowed after that freeze. If the file cannot explain a request, the client does not send that request.

Artifact: mix file, loader, and a refusing gate

The example fixture below is labeled sample data for the workflow, not a claim about one production cluster. Teams should replace the routes and weights with a window they actually captured. The notes field exists so a later reader can see the limit of the sample without rereading the pairing log.

{
  "captured_at": "2026-09-21T18:00:00Z",
  "source": "edge-access-log-sample",
  "window_seconds": 600,
  "routes": [
    {"method": "GET", "path": "/v1/catalog", "weight": 0.62, "p95_ms_observed": 48},
    {"method": "GET", "path": "/v1/catalog/{id}", "weight": 0.27, "p95_ms_observed": 61},
    {"method": "POST", "path": "/v1/checkout", "weight": 0.11, "p95_ms_observed": 220}
  ],
  "think_time_ms": {"p50": 80, "p95": 400},
  "max_concurrency": 12,
  "notes": "Weights from a ten-minute weekday sample. Not a capacity or soak test."
}

The loader below rejects unknown keys on each route and refuses to run when weights do not sum near one. It also refuses extra routes supplied by a caller, which is the usual way generated clients quietly widen the mix. The functions are ordinary Python so a later generator can wrap them without replacing the rules.

# mix_gate.py — labeled example, not production telemetry
from __future__ import annotations

import json
from pathlib import Path

REQUIRED_ROUTE_KEYS = {"method", "path", "weight", "p95_ms_observed"}
MIX_PATH = Path("fixtures/api_mix.json")


def load_mix(path: Path = MIX_PATH) -> dict:
    if not path.is_file():
        raise FileNotFoundError(f"mix file missing: {path}")
    data = json.loads(path.read_text(encoding="utf-8"))
    routes = data.get("routes") or []
    if not routes:
        raise ValueError("mix file lists no routes")
    total = 0.0
    for route in routes:
        extra = set(route) - REQUIRED_ROUTE_KEYS
        missing = REQUIRED_ROUTE_KEYS - set(route)
        if extra or missing:
            raise ValueError(f"route key mismatch extra={extra} missing={missing}")
        total += float(route["weight"])
    if abs(total - 1.0) > 0.02:
        raise ValueError(f"weights must sum to 1.0 +/- 0.02, got {total}")
    if int(data.get("max_concurrency", 0)) < 1:
        raise ValueError("max_concurrency must be >= 1")
    return data


def assert_request_allowed(mix: dict, method: str, path: str) -> None:
    allowed = {(r["method"], r["path"]) for r in mix["routes"]}
    if (method, path) not in allowed:
        raise AssertionError(f"request not in captured mix: {method} {path}")

The test module is the pairing gate. It fails before any HTTP client is imported, which keeps generated glue from shipping on an empty fixture. A second test walks a hostile list of invented routes and expects each one to raise.

# tests/test_mix_gate.py
import pytest
from mix_gate import assert_request_allowed, load_mix


def test_mix_file_loads_and_weights_sum():
    mix = load_mix()
    assert mix["window_seconds"] == 600
    assert mix["max_concurrency"] == 12


@pytest.mark.parametrize(
    "method,path",
    [
        ("DELETE", "/v1/catalog/{id}"),
        ("POST", "/v1/webhooks/retry"),
        ("GET", "/internal/debug/cache"),
    ],
)
def test_invented_routes_are_rejected(method, path):
    mix = load_mix()
    with pytest.raises(AssertionError, match="not in captured mix"):
        assert_request_allowed(mix, method, path)

Commands for the same gate stay boring on purpose. The pair ran them before any model was asked to write a client loop. A green result meant only that the freeze held, not that the service was fast.

mkdir -p fixtures tests
# save the JSON and Python files, then:
python -m pytest tests/test_mix_gate.py -q

Numbered workflow after the freeze

Capture one short access window and write route weights by hand into fixtures/api_mix.json.
Commit the mix file in its own change, with captured_at, source, and a note about what the window is not.
Add mix_gate.py and the refusing tests, and merge them before any load client exists in the tree.
Only then generate a client that iterates mix["routes"], sleeps using think_time_ms, and caps threads at max_concurrency.
Reject any generated patch that introduces a path string absent from the mix file, including “helpful” health checks.
Refresh the mix file through pairing, not through a model, when the window or the product shape changes.

The workflow is intentionally hostile to convenience. Convenience is how invented checkout bursts enter a suite that later becomes the team’s memory of production. A dated JSON file is a poorer story and a better input. Generated code can still save typing after that input exists.

Where a free model may enter

After the mix file and the refusing tests exist, an implementer can ask a coding assistant to draft only the loader wrappers and the client loop. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode’s free model access and free server option can host that narrow generation step once the pairing decision is already written down. The assistant should receive the mix file as read-only context and a rule that unseen routes are bugs, not features.

The product is not a substitute for the captured window, and it should not be asked to invent weights. Teams that skip the pairing freeze will still get fluent clients, and those clients will still lie in a confident tone. The useful split is human custody of the mix, then mechanical generation of iteration code. That split remains valuable if the assistant is later replaced by another tool.

Limitations

This approach does not measure capacity, saturation, or tail latency under incident load, because the sample window is short and observational. Weights from one weekday slice will mislead a holiday sale, a batch window, or a regional failover, and the gate cannot detect that semantic stale state. The loader also cannot prove that p95_ms_observed is a budget; it is only a number copied from a sample. Teams still need separate soak tests, error-injection tests, and human review of capture quality.

The pairing log does not replace authorization to read production logs, and this article does not provide a collection pipeline. If the service has no access sample, the honest move is to refuse generated load tests rather than to ask a model for realism. Equal-weight tests can still be useful as crash finders, but they should be named as crash finders. Calling them performance tests is the error the kept decision exists to prevent.

Who should not use this

Solo prototypes with no production traffic should not pretend a mix file is empirical. Protocol work that has never seen users yet should keep functional tests and skip shape-faithful load. Teams without log access, or without a senior who will veto invented routes, will only add ceremony around the same fiction. Security-sensitive environments should also keep capture, redaction, and fixture review on a path the pairing can audit.

The kept decision is small enough to reuse, and strict enough to annoy a generator that wants to be helpful. That annoyance is the point of the pairing session. A captured mix file is a poorer narrative than a confident client, and it is the only input the pair allowed. Teams that want the implementer side of this pairing to run against a free model on a free server can try MonkeyCode after the mix file is frozen.

The Pairing Ledger That Blocked a Patch Until One Decision Was Kept

Avery Li — Mon, 21 Sep 2026 14:00:15 +0000

A pairing session with generated code is unfinished until one kept decision is written down in a checkable ledger. Generated patches often look complete while the senior's questions and rejected paths never become part of the repository. This article records a pairing pattern that treats those questions, dead ends, and the kept decision as a gate. The gate blocks remote execution until the ledger validates, which keeps pretend-complete work from reaching a shared box.

Why a transcript is not enough

A chat log is a poor control because it is long, unordered, and easy to ignore during a later merge. Seniors already ask useful questions during pairing, then watch those questions vanish when the model emits a plausible diff. Dead ends disappear even faster, which lets the next session retry the same failed idea with slightly different names. The ledger below compresses the session into three fields that a script can refuse to parse as valid.

The surrounding industry conversation keeps returning to measurement: models can look strong on tests that no longer constrain real behavior. Another recurring failure is social rather than technical, where a green check stands in for engineering work that nobody actually performed. A pairing ledger does not solve model evaluation in general, and it does not restore lost practice by itself. It only makes the missing senior work obvious before a remote run starts on a shared box.

Pairing record: webhook ingest that acknowledged poison as success

The session below is a reconstructed tutorial example, not a production incident report, and it is labeled as such. A junior engineer and a senior engineer sat with a generated patch for a webhook ingest worker that acknowledged every payload with HTTP 200. The vendor had been retrying on 5xx, and the generated handler treated all parse failures as success so the retries would stop. The senior refused to run the patch on a shared box until the pairing work was written as a ledger.

Questions the senior asked

The senior kept a short numbered list instead of a long chat export, and each item had to be answerable from the repository.

Which vendor status codes currently mean retry later rather than drop this delivery?
Which failures are poison, meaning the payload cannot become valid without a publisher change?
Which request headers are required before the body is parsed, including signature and timestamp?
Which queue name receives poison messages, and which process is allowed to replay them?
Which files is the generated patch forbidden to touch, including deploy manifests and secret loaders?

Those five questions are the pairing work, and they belong in the repository rather than in a disposable chat. They are not prompts for the model to answer in a vacuum, and they are not a substitute for reading the vendor contract. The ledger stores them as strings so later reviewers can see what was actually asked.

Dead ends the session recorded

The session recorded three rejected paths so the next model run would not rediscover them as fresh ideas.

Mapping every failure to HTTP 200 stopped vendor retries while hiding poison payloads behind a success metric.
Sleeping inside the handler dampened retry storms while blocking the worker until the timeout budget collapsed.
Parsing the body before verifying the signature simplified fixtures while accepting unsigned JSON as a verified delivery.

Each dead end includes a reason, not only a rejected snippet, because a snippet without a reason is easy to regenerate. The validator later requires at least two dead ends so a ledger cannot be filled with a single decorative failure. Teams can raise that floor when reviews are noisy, but they should not lower it to zero.

The one decision the pairing kept

The pairing kept a single decision: freeze a status matrix and a poison queue name before any generated ingest handler may run off-laptop. HTTP 200 remains reserved for verified persisted deliveries, while HTTP 400 remains reserved for poison payloads that are also written to webhook-poison. HTTP 503 remains reserved for downstream unavailability after signature verification succeeds on an otherwise well-formed request. Generated code may implement the matrix, and it may not invent new status meanings during the same session.

That kept decision is intentionally narrow, and it refuses extra scope that the model may offer in the same turn. It does not bless caching, retries, or schema migration, and it does not authorize a remote deploy. It only authorizes the next local or remote run of tests that assert the matrix. If the model wants a second decision, the pairing starts a new ledger instead of appending silent scope.

Artifact: ledger file and status matrix

The proposed ledger is a JSON document that lives next to the patch branch, not inside a chat product. A companion YAML file holds the status matrix so reviewers can read it without opening the validator. Both files are examples for this article and should be treated as unexecuted templates until a team copies them into a real repository.

{
  "schema_version": 1,
  "session_id": "pairing-webhook-2026-09-21",
  "branch": "fix/webhook-status-matrix",
  "participants": ["senior", "junior", "generated-patch"],
  "questions": [
    "Which vendor status codes currently mean retry later rather than drop this delivery?",
    "Which failures are poison, meaning the payload cannot become valid without a publisher change?",
    "Which request headers are required before the body is parsed, including signature and timestamp?",
    "Which queue name receives poison messages, and which process is allowed to replay them?",
    "Which files is the generated patch forbidden to touch, including deploy manifests and secret loaders?"
  ],
  "dead_ends": [
    {
      "path": "map-all-failures-to-200",
      "reason": "Stops vendor retries while hiding poison payloads behind a success metric."
    },
    {
      "path": "sleep-in-handler",
      "reason": "Dampens retry storms while blocking the worker until the timeout budget collapses."
    },
    {
      "path": "parse-before-signature",
      "reason": "Simplifies fixtures while accepting unsigned JSON as if it were a verified delivery."
    }
  ],
  "kept_decision": {
    "id": "freeze-status-matrix-and-poison-queue",
    "summary": "HTTP 200 only after verify+persist; HTTP 400 plus webhook-poison for poison; HTTP 503 after verify when downstream is down.",
    "forbidden_edits": [
      "deploy/",
      ".github/workflows/",
      "**/*secret*",
      "pairing_ledger.json"
    ],
    "run_target": "local-first"
  },
  "fingerprint": {
    "runtime": "python3.12",
    "lockfile": "uv.lock",
    "service": "webhook-ingest"
  }
}

# webhook_status_matrix.yml
# Proposed contract. Unexecuted until tests import it.
verified_and_persisted: 200
poison_payload: 400
poison_queue: webhook-poison
downstream_unavailable_after_verify: 503
signature_missing_or_invalid: 401

Artifact: validator that refuses to start a remote run

The validator is a proposed Python script that reads the ledger and refuses vague pairing records. It reads the ledger, checks minimum structure, and prints a run permit only when the pairing fields are present. The script does not call models, start servers, or treat a valid ledger as a production deploy approval. Operators can wrap it with a shell function that starts a remote session only after a zero exit code.

#!/usr/bin/env python3
"""Validate a pairing ledger before any remote run is attempted."""

from __future__ import annotations

import json
import sys
from pathlib import Path

MIN_QUESTIONS = 3
MIN_DEAD_ENDS = 2
REQUIRED_DECISION_KEYS = {"id", "summary", "forbidden_edits", "run_target"}
ALLOWED_TARGETS = {"local-first", "remote-after-local"}


def fail(message: str) -> None:
    print(f"ledger invalid: {message}", file=sys.stderr)
    raise SystemExit(2)


def main(argv: list[str]) -> None:
    if len(argv) != 2:
        fail("usage: validate_pairing_ledger.py pairing_ledger.json")
    raw = Path(argv[1]).read_text(encoding="utf-8")
    try:
        ledger = json.loads(raw)
    except json.JSONDecodeError as exc:
        fail(f"json parse error: {exc}")

    questions = ledger.get("questions")
    dead_ends = ledger.get("dead_ends")
    decision = ledger.get("kept_decision")

    if not isinstance(questions, list) or len(questions) < MIN_QUESTIONS:
        fail(f"need at least {MIN_QUESTIONS} questions")
    if any(not isinstance(q, str) or len(q.strip()) < 12 for q in questions):
        fail("each question must be a string of at least 12 characters")

    if not isinstance(dead_ends, list) or len(dead_ends) < MIN_DEAD_ENDS:
        fail(f"need at least {MIN_DEAD_ENDS} dead ends")
    for item in dead_ends:
        if not isinstance(item, dict) or "path" not in item or "reason" not in item:
            fail("each dead end needs path and reason")
        if len(str(item["reason"]).split()) < 8:
            fail("each dead-end reason must be at least eight words")

    if not isinstance(decision, dict):
        fail("kept_decision must be an object")
    missing = REQUIRED_DECISION_KEYS - set(decision)
    if missing:
        fail(f"kept_decision missing {sorted(missing)}")
    if decision.get("run_target") not in ALLOWED_TARGETS:
        fail("run_target must be local-first or remote-after-local")
    if "pairing_ledger.json" not in decision.get("forbidden_edits", []):
        fail("kept_decision must forbid edits to pairing_ledger.json")

    print("ledger valid: remote run still requires a separate human permit")
    print(f"kept_decision={decision['id']}")


if __name__ == "__main__":
    main(sys.argv)

A tiny pytest module can lock the matrix independently of the ledger so a generated handler cannot drift silently.

# test_webhook_status_matrix.py
from pathlib import Path
import yaml


def test_status_matrix_has_poison_path():
    matrix = yaml.safe_load(Path("webhook_status_matrix.yml").read_text())
    assert matrix["poison_payload"] == 400
    assert matrix["poison_queue"] == "webhook-poison"
    assert matrix["verified_and_persisted"] == 200
    assert matrix["verified_and_persisted"] != matrix["poison_payload"]
    assert matrix["signature_missing_or_invalid"] == 401

Numbered workflow the pairing actually follows

The steps below are local, cheap, and deliberately boring so generated confidence cannot skip them. They exist so a generated patch cannot skip the senior's recorded work merely by looking complete in review.

Create a branch and copy empty templates for pairing_ledger.json and webhook_status_matrix.yml into the service tree.
Pair for a bounded session and write questions as they are asked, not after the model emits a diff.
Register every rejected path as a dead end with an eight-word reason before trying the next idea.
Write exactly one kept decision, including forbidden edit globs and a run target of local-first.
Run python validate_pairing_ledger.py pairing_ledger.json and refuse to continue on a non-zero exit.
Run the matrix tests locally; if they fail, change code or the matrix, but do not delete ledger fields to silence the validator.
Only after local tests pass, consider a remote run, and only if run_target has been updated in a reviewed commit.

Shell operators can encode the same gate with ordinary commands and without wrapping it in a larger platform.

python validate_pairing_ledger.py pairing_ledger.json
pytest test_webhook_status_matrix.py -q
# Remote commands stay commented until the ledger and tests both pass.
# ssh remote-box 'cd /srv/webhook-ingest && pytest -q'

A second command block can show reviewers which paths the kept decision forbade, using ordinary git rather than a new dashboard.

git diff --name-only origin/main...HEAD
# Expected: ingest handler, tests, matrix, ledger.
# Rejected: deploy/, workflow files, secret loaders, pairing_ledger.json rewritten by the model.

Where free model access and a free server belong

Generated patches are useful after the ledger exists because the model then has a smaller surface to invent. Free model access is relevant when the team wants a draft implementation of the already frozen matrix, not a new product decision. A free server option is relevant only as a later run target after local validation succeeds. The team then uses an isolated box rather than a laptop for the same matrix tests.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source coding assistant with free model access and a free server option. Those options can sit behind this ledger instead of replacing the senior's kept decision. The ledger remains a repository file, and the validator remains ordinary Python, even if those free options are unused. Readers should verify current availability on the project itself rather than treating this article as a quota sheet or a hardware list.

Limitations

The ledger can be forged by writing questions after the patch already exists in the branch. A junior can invent plausible questions after the patch exists, and the validator cannot prove that pairing occurred in time. The eight-word reason check is a speed bump, not cryptography, and it will accept fluent nonsense. The status matrix is only as strong as the tests that import it during review. Those tests can be deleted in the same generated diff unless forbidden globs are enforced by review or CI.

The workflow also does not measure model quality, latency, or fitness for a production incident. It does not claim that free models are accurate, fast, or suitable for production incident response. It does not assign SLOs, token budgets, or machine sizes, because those claims would be separate evidence. Remote boxes still need ordinary access control, and a free server is not a substitute for a staging environment with real secrets removed.

Who should not use this approach

On-call engineers in an active outage should not pause to invent a ledger schema while customers are failing. Teams without a senior partner should not fill the senior fields as theater, because the whole point is a kept human decision. Regulated production changes still need the organization's change process, which this article does not replace or accelerate. People who want the model to write the ledger, the matrix, and the handler in one shot should pick another workflow. That single-shot approach collapses the gate this pairing pattern is built to protect.

The pairing ledger is a small and slightly stubborn habit that keeps remote runs from starting on unreviewed confidence. It keeps one decision visible, and it keeps rejected paths expensive to forget during the next generated attempt. The files are small enough to review in a single pull request without a new platform. Readers who already keep pairing notes can run the validator on a current branch before the next remote session.

The Pairing Transcript That Froze Retry Methods Before Generated Code Shipped

Avery Li — Sun, 20 Sep 2026 11:54:39 +0000

A pairing session should freeze retry methods and an idempotency key rule before any generated client code is allowed to ship. Free coding models write retry loops quickly, and those loops often treat every HTTP method as safe to repeat. The cost appears later as duplicate charges, repeated side effects, and logs that cannot name a canonical attempt. This article records one senior pairing as a transcript, then turns the kept decision into a checker.

The session below is a labeled worked example for a local HTTP helper, not a report of a named production outage. The pairing is completed before a model is asked to implement retries, timeouts, or backoff curves for the client. The artifact is a YAML transcript, a Python checker, a constrained client, and a small invariant test file. Teams can run the checker in CI without adopting any particular coding assistant or remote development host.

The problem the pairing had to stop

Internal tools often grow a retry wrapper after the first timeout appears in shared logs. A model can emit exponential backoff, jitter, and status-code lists in a single pass that looks complete. That output still leaves POST and PATCH inside the retry set, which is the failure mode the senior was asked to block. Review that only checks latency and HTTP status will bless the wrapper while remaining silent about duplicate side effects.

Generated tests are getting easier to produce, and that ease is part of the trap rather than the fix. A suite can prove that a call eventually returns 200 and still never ask whether the server ran a charge twice. The pairing therefore spends its time on method semantics and key identity, not on polishing sleep curves. The transcript is the review object; the later patch is only allowed to fill the envelope the transcript already closed.

Step 1: write the senior questions into a file

The pairing opens with a short question list that the senior expects answered in writing. Each answer names an owner file and a constraint, not a feeling about reliability or user impact. The worked example uses four questions only, so the session cannot wander into unrelated refactors or framework rewrites. Chat history is not the source of truth once the YAML exists on the branch.

# pairing-session.yaml
session_id: retry-helper-2026-09-20
status: kept
questions:
  - id: Q1
    ask: Which HTTP methods may the helper retry without creating duplicate side effects?
    answer: Only GET, HEAD, and PUT appear on the allowlist. POST and PATCH stay out.
    owner_file: retry_policy.yaml
  - id: Q2
    ask: What header makes two attempts the same logical request when a method is retried?
    answer: Idempotency-Key must be present, and the prefix must stay inv-2026-09-.
    owner_file: retry_policy.yaml
  - id: Q3
    ask: May generated development traffic leave the workstation for a remote coding host?
    answer: Development completion may use a remote coding host. Runtime product traffic may not.
    owner_file: egress_policy.yaml
  - id: Q4
    ask: Where do secrets for the product API live during generation and during tests?
    answer: Secrets stay in local env files that the generator cannot write. Tests use fixtures.
    owner_file: secrets.policy

Those four answers already bound the patch surface for anyone who reads the pull request later. A model prompt can receive the YAML as context, but reviewers still read the file rather than a screenshot of a conversation. If a later patch changes methods or the key prefix, the pairing status is no longer kept and the session must be reopened on purpose.

Step 2: publish the dead ends before anyone codes

Dead ends are rejected designs with a reason that a checker or a reviewer can quote without a meeting. The pairing does not keep a polite maybe for a future cleanup pull request. Each dead end blocks a tempting patch that generated code produces often when the prompt says make it more resilient. Writing them down is cheaper than arguing the same three designs after the helper already merged.

Retry every 5xx response for every method, because POST charges and webhook delivery would repeat under load.
Add exponential backoff without a method allowlist, because delay does not make a non-idempotent call safe to replay.
Let the client mint raw UUIDs as keys, because collisions across services would not share a frozen namespace.
Route runtime API calls through the same host used for code generation, because development egress is not an app dependency.

dead_ends:
  - id: D1
    rejected: retry_all_5xx
    reason: Status-code retries ignore method semantics and duplicate POST side effects.
  - id: D2
    rejected: backoff_without_allowlist
    reason: Timing policy cannot substitute for an explicit method allowlist.
  - id: D3
    rejected: unprefixed_uuid_keys
    reason: Keys without the frozen prefix cannot be grepped or revoked as a family.
  - id: D4
    rejected: runtime_via_codegen_host
    reason: A coding host is not an approved production hop for product HTTP.

When a later patch revives retry_all_5xx, the reviewer can point at D1 instead of reconstructing the argument from memory. The implementation step stays narrow because the pairing already spent its attention on the rejected shapes. That is the whole point of recording dead ends in the same commit as the helper.

Step 3: keep one decision and refuse to reopen it in the patch

The pairing keeps a single decision that later patches must not reopen while claiming to be a small cleanup. Extra improvements, including smarter jitter and hedged requests, wait for a new session with a new identifier. The kept decision in this example is narrow on purpose so a lexical checker can enforce it. Broad reliability slogans are not decisions.

Kept decision: the helper may retry only allowlisted methods, and every retried attempt must send Idempotency-Key values that start with inv-2026-09-.

kept_decision:
  id: KD-retry-allowlist
  summary: Retry GET, HEAD, and PUT only, with a frozen Idempotency-Key prefix.
  allow_methods: [GET, HEAD, PUT]
  deny_methods: [POST, PATCH, DELETE]
  key_header: Idempotency-Key
  key_prefix: inv-2026-09-
  max_attempts: 3
  reopen: false

The same rule can be read as a table during review, which is useful when the YAML is long and the patch is not.

Method	Retry allowed	Pairing reason
GET	yes	Read path in this service has no billed side effect
HEAD	yes	Metadata read is treated as idempotent
PUT	yes	Same body and key must replace one resource
POST	no	Creates charges, mail, or webhook work
PATCH	no	Partial updates are not frozen as idempotent here
DELETE	no	Replay can remove a resource the caller already replaced

Generated code likes to reopen policy while renaming functions and extracting a shared transport layer. The reopen: false flag tells both humans and tools that a new pairing is required to change methods or the prefix. Without that flag, the transcript becomes commentary and the next model run wins.

Step 4: fail CI when the patch violates the kept decision

A transcript that cannot fail CI will lose to the next generated patch, usually before lunch. The checker below is a labeled example for this tree, not production-hardened policy software. Operators should run it against their own filenames and extend the regexes if the client uses helpers. The senior accepted a cheap gate that catches the common generated pattern, not a soundness proof of every call path.

# check_kept_decision.py
from __future__ import annotations

import re
import sys
from pathlib import Path

import yaml

ALLOWED = {"GET", "HEAD", "PUT"}
DENIED = {"POST", "PATCH", "DELETE"}
PREFIX = "inv-2026-09-"
KEY_HEADER = "Idempotency-Key"

RETRY_CALL = re.compile(
    r"retry_request\(\s*method\s*=\s*[\"'](\w+)[\"']",
    re.MULTILINE,
)
KEY_LITERAL = re.compile(
    r"[\"']Idempotency-Key[\"']\s*:\s*f?[\"']([^\"']+)[\"']"
)

def load_decision(path: Path) -> dict:
    data = yaml.safe_load(path.read_text())
    decision = data["kept_decision"]
    if decision.get("reopen") is True:
        raise SystemExit("kept decision was reopened without a new pairing session")
    return decision

def scan_source(root: Path) -> list[str]:
    failures: list[str] = []
    for path in root.glob("*.py"):
        if path.name.startswith("check_"):
            continue
        text = path.read_text()
        for match in RETRY_CALL.finditer(text):
            method = match.group(1).upper()
            if method in DENIED or method not in ALLOWED:
                failures.append(
                    f"{path}: retry on {method} violates KD-retry-allowlist"
                )
        for match in KEY_LITERAL.finditer(text):
            value = match.group(1)
            if not value.startswith(PREFIX) and PREFIX not in value:
                failures.append(f"{path}: idempotency key missing prefix {PREFIX}")
        if "retry_request(" in text and KEY_HEADER not in text:
            failures.append(f"{path}: retry_request used without {KEY_HEADER}")
    return failures

def main() -> int:
    decision = load_decision(Path("pairing-session.yaml"))
    if set(decision["allow_methods"]) != ALLOWED:
        print("pairing allow_methods drifted from checker constants", file=sys.stderr)
        return 1
    failures = scan_source(Path("."))
    for item in failures:
        print(item, file=sys.stderr)
    return 1 if failures else 0

if __name__ == "__main__":
    raise SystemExit(main())

The checker is lexical on purpose, and that limitation belongs in the pairing notes rather than in a later excuse. It will miss getattr tricks, dynamic method names, and retries written in another language. Catching the default shape that models emit is still worth a few dozen lines, because that is the shape that otherwise merges.

Step 5: implement only inside the frozen envelope

After the transcript and checker exist, implementation can proceed without reopening method policy. The client below follows the kept decision and refuses denied methods before any network call is attempted. Comments and names label this as unexecuted sample code for the article. Production services still need a server that honors the same key.

# retry_client.py
from __future__ import annotations

from dataclasses import dataclass

ALLOWED_METHODS = frozenset({"GET", "HEAD", "PUT"})
KEY_PREFIX = "inv-2026-09-"

@dataclass(frozen=True)
class RetryEnvelope:
    method: str
    url: str
    idempotency_key: str
    attempts: int = 3

class PolicyError(ValueError):
    pass

def validate_envelope(env: RetryEnvelope) -> None:
    method = env.method.upper()
    if method not in ALLOWED_METHODS:
        raise PolicyError(f"{method} is outside the pairing allowlist")
    if not env.idempotency_key.startswith(KEY_PREFIX):
        raise PolicyError("idempotency key missing frozen prefix")
    if env.attempts > 3:
        raise PolicyError("attempt budget exceeds kept decision")

def retry_request(method: str, url: str, key: str, send):
    env = RetryEnvelope(method=method, url=url, idempotency_key=key)
    validate_envelope(env)
    headers = {"Idempotency-Key": env.idempotency_key}
    last_error = None
    for _ in range(env.attempts):
        try:
            return send(env.method, env.url, headers)
        except TimeoutError as exc:
            last_error = exc
    assert last_error is not None
    raise last_error

A small test file records the pairing as executable examples instead of a narrative in the pull request. These tests are the reviewer's fast path when a model sends a larger transport refactor. They do not prove exactly-once behavior on the server; they prove the client still refuses the dead ends.

# test_retry_invariants.py
import pytest
from retry_client import PolicyError, retry_request

def test_post_is_rejected():
    with pytest.raises(PolicyError):
        retry_request(
            "POST",
            "https://api.example.internal/charges",
            "inv-2026-09-a",
            lambda *args: None,
        )

def test_get_requires_prefix():
    with pytest.raises(PolicyError):
        retry_request(
            "GET",
            "https://api.example.internal/items/1",
            "other-a",
            lambda *args: None,
        )

def test_get_with_prefix_calls_send():
    seen = {}

    def send(method, url, headers):
        seen["method"] = method
        seen["headers"] = headers
        return 200

    status = retry_request(
        "GET",
        "https://api.example.internal/items/1",
        "inv-2026-09-a",
        send,
    )
    assert status == 200
    assert seen["headers"]["Idempotency-Key"].startswith("inv-2026-09-")

Local commands stay ordinary and do not require a vendor dashboard for the policy gate.

python -m pytest test_retry_invariants.py
python check_kept_decision.py

Where free model access belongs after the freeze

Generated patches arrive faster than policy arguments, which is why the transcript is committed before any implementation branch is opened. After that freeze, a coding assistant can draft the helper against the YAML without reopening the method allowlist. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source project that, per this account's operator, offers free model access and a free server option for development drafting.

Those options apply to drafting helpers like this retry client, not to production request paths or secret storage. Dead end D4 still forbids using a coding host as a runtime hop for product HTTP traffic. If a team wants a drafting host for that implementation step, MonkeyCode's free model access and free server option can host the session while the YAML and checker stay in review.

The same transcript works if a human intern writes retry_client.py by hand. Removing the product sentence does not remove the pairing, the table, or the tests. That is the test for whether the workflow is real engineering work rather than a story about tools.

Limitations

The lexical checker will miss retries hidden behind getattr, wrappers in other languages, or method names built from configuration at runtime. The frozen prefix is a review aid, not a cryptographic guarantee of exactly-once processing across services. The server on the other side must still honor the key, and this article does not implement server-side deduplication or an outbox.

No duration, quota, hardware, or benchmark is claimed for any coding host in this writeup. A free development server is not described as a production SLA, and it should not be treated as one in capacity planning. Teams that need those numbers should measure their own workloads against primary sources they control.

Who should not use this approach

Skip the workflow when the client already sits behind a queue that deduplicates by business key. Skip it when legal review forbids sending source to a remote coding host, even for drafting. Skip it when every service mints keys differently and no prefix can be frozen without a platform change.

Payment, webhook, and mail senders should not treat this helper as a substitute for an outbox or a broker with replay control. Teams without a senior who can answer the four questions should not ship a generated retry wrapper and call the pairing complete. In those cases the honest kept decision is to refuse generated retries until the ownership model exists.

The Pairing Kept a Rollback Contract Before Any Free Model Touched Staging

Avery Li — Sat, 19 Sep 2026 10:01:21 +0000

A pairing session with a senior engineer should freeze a rollback contract before any free coding model is allowed to change a shared server. The contract records every question asked, every dead-end hypothesis, and exactly one kept decision about how a patch may land. Without that freeze, free-model access turns a staging host into an unreviewed experiment rather than an engineering change. The workflow below treats the pairing log itself as the merge gate, not the generated patch from any model.

The problem the pairing is meant to catch

Free coding models make it cheap to emit a diff, and a shared staging process makes it cheap to apply that diff. Industry talk about vibe coding often stops at taste, while the operational failure is a host that changed without a reversible plan. A senior pairing partner notices that gap because the partner has been paged for similar silent edits. The pairing therefore refuses to let the model speak to the server until a rollback contract exists on disk.

Where a free model and a free server fit

Teams sometimes reach for MonkeyCode when they need free model access and a free server option for agent trials.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Those two availability facts do not replace review, ownership, or a rollback path on the host that will run the patch. The pairing log described below still applies if every product name is removed from the working method.

Worked example: overlapping POST /jobs

The following session is a labeled worked example, not a claim about a production outage at a named company. A staging service accepts POST /jobs and occasionally drops the last item when two requests overlap. The junior engineer wants a free model to rewrite the handler on the shared host immediately. The senior engineer refuses that path until four questions, two dead ends, and one kept decision are written to pairing_log.json.

1. Freeze the staging file and the failing test

The pairing starts by freezing what staging currently does, not by asking a model for a better handler. A health check and a copy of the running file become the rollback baseline for the rest of the session. The senior engineer will not discuss prompt text until those two artifacts exist beside the repository. The commands below assume a local staging replica that mirrors the shared host layout for this exercise.

mkdir -p app .pairing_frozen/app
python3 - <<'PY'
from pathlib import Path
src = Path("app/jobs.py")
if not src.exists():
    raise SystemExit("app/jobs.py missing; stop before any model edit")
Path(".pairing_frozen/app/jobs.py").write_text(src.read_text())
Path(".pairing_frozen/stamp").write_text("frozen\n")
print("froze", src, "->", ".pairing_frozen/app/jobs.py")
PY
python3 test_overlap.py --expect-fail

The buggy handler used in the example is a read-copy-write on a process-wide list, which loses items under overlapping POSTs. The unused lock in the file is deliberate, because it shows how a model can “see” a lock and still patch the wrong region. The pairing freezes this file first so later rollback does not depend on git history being clean.

# app/jobs.py — labeled worked example, currently racy
from http.server import BaseHTTPRequestHandler
import json
import threading

JOBS = []
_lock = threading.Lock()  # present, but the handler never takes it


class Handler(BaseHTTPRequestHandler):
    def log_message(self, format, *args):
        return

    def do_POST(self):
        length = int(self.headers.get("Content-Length", "0"))
        payload = json.loads(self.rfile.read(length) or b"{}")
        current = list(JOBS)
        current.append(payload)
        JOBS[:] = current  # overlap can drop an append
        body = json.dumps({"stored": len(JOBS)}).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

# test_overlap.py — twenty concurrent posts against a threaded server
from __future__ import annotations

import importlib.util
import json
import sys
import threading
import urllib.request
from http.server import ThreadingHTTPServer
from pathlib import Path


def load_jobs():
    path = Path(__file__).parent / "app" / "jobs.py"
    spec = importlib.util.spec_from_file_location("jobs", path)
    mod = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    return mod


def main() -> None:
    mod = load_jobs()
    server = ThreadingHTTPServer(("127.0.0.1", 0), mod.Handler)
    threading.Thread(target=server.serve_forever, daemon=True).start()
    port = server.server_address[1]
    errors: list[str] = []

    def post(n: int) -> None:
        req = urllib.request.Request(
            f"http://127.0.0.1:{port}/jobs",
            data=json.dumps({"id": n}).encode(),
            headers={"Content-Type": "application/json"},
            method="POST",
        )
        try:
            with urllib.request.urlopen(req, timeout=2) as resp:
                resp.read()
        except Exception as exc:  # noqa: BLE001
            errors.append(str(exc))

    workers = [threading.Thread(target=post, args=(i,)) for i in range(20)]
    for worker in workers:
        worker.start()
    for worker in workers:
        worker.join()
    server.shutdown()
    stored = len(mod.JOBS)
    print(f"posted=20 stored={stored} errors={len(errors)}")
    lost = stored < 20
    expect_fail = "--expect-fail" in sys.argv
    if expect_fail and lost:
        sys.exit(0)
    if expect_fail and not lost:
        sys.exit("race did not drop jobs; freeze a failing baseline instead")
    if not expect_fail and (lost or errors):
        sys.exit("overlap still drops jobs; restore the frozen handler")
    sys.exit(0)


if __name__ == "__main__":
    main()

2. Store the senior questions as required fields

Spoken chat transcripts vanish quickly, so the senior's questions are stored as required fields in pairing_log.json. Each question has an owner, a one-line answer, and a timestamp so later patches cannot pretend the discussion never happened. The pairing session does not proceed while any answer field is still empty in that log. The four questions used in this worked example are listed with answers after the JSON schema.

{
  "session_id": "jobs-overlap-2026-09-19",
  "questions": [
    {
      "asked_by": "senior",
      "text": "What is the smallest input that still drops a job?",
      "answer": "Twenty concurrent POST /jobs bodies with distinct id fields.",
      "answered_at": "2026-09-19T10:12:00Z"
    },
    {
      "asked_by": "senior",
      "text": "Which single file is allowed to change in this session?",
      "answer": "app/jobs.py only.",
      "answered_at": "2026-09-19T10:14:00Z"
    },
    {
      "asked_by": "senior",
      "text": "Which command restores the frozen handler if the overlap test still fails?",
      "answer": "cp .pairing_frozen/app/jobs.py app/jobs.py",
      "answered_at": "2026-09-19T10:16:00Z"
    },
    {
      "asked_by": "senior",
      "text": "Who watches the shared staging process for the next hour?",
      "answer": "Junior owns the process; senior owns the rollback command.",
      "answered_at": "2026-09-19T10:18:00Z"
    }
  ],
  "dead_ends": [],
  "kept_decision": {}
}

The senior asked about the smallest failing input first, because a full rewrite is usually a way to hide an unproven race. File ownership came second, so the model would not receive a license to touch configuration, tests, and the handler in one prompt. The restore command came third, because a shared server without a known undo path is not a pairing environment. Watch ownership came last, so paging duty would not dissolve into the model transcript after the session ended.

3. Write the dead ends before the next prompt

The first dead end was wrapping the entire handler in a process-wide lock, which hid the race by destroying concurrency. The second dead end was introducing an external queue in the same change, which mixed infrastructure work with a one-line race fix. Both ideas are recorded with a reject reason so a later model prompt cannot revive them quietly. The senior engineer treats a recycled dead end as a failed pairing, not as creative iteration on the same bug.

{
  "dead_ends": [
    {
      "hypothesis": "Hold _lock across the entire do_POST body, including JSON writes.",
      "reject_reason": "Serializes every request to hide the race instead of protecting the list swap.",
      "rejected_by": "senior"
    },
    {
      "hypothesis": "Replace JOBS with an external queue inside the same patch.",
      "reject_reason": "Expands scope from one file race to new infrastructure on the shared host.",
      "rejected_by": "senior"
    }
  ]
}

A free model will often rediscover both ideas because they are locally coherent and appear in many training examples. The pairing log makes that rediscovery expensive, because the apply script can refuse a patch whose comments or diff hunks match a rejected hypothesis. The worked example keeps that check human-readable rather than turning it into a classifier. The important part is the written reject reason, not a clever similarity score.

4. Keep one rollback contract

The kept decision is narrow on purpose, so only app/jobs.py may change during this pairing session. The apply tool must restore the frozen copy if the overlap test still fails after the patch. The rollback command is part of the decision, not a comment the model can quietly ignore. That single-decision rule is what keeps a free model from expanding the blast radius on a shared server.

{
  "kept_decision": {
    "summary": "Take _lock only around the list copy and swap in app/jobs.py.",
    "allowed_files": ["app/jobs.py"],
    "rollback_command": "cp .pairing_frozen/app/jobs.py app/jobs.py",
    "verify_command": "python3 test_overlap.py",
    "second_decision": null
  }
}

The intended patch is then small enough to review in one screen. The lock already sitting in the file is used only around the copy and assignment, which preserves request concurrency for JSON encoding. No configuration file, Dockerfile, or test rewrite is in scope, even if a model offers them as a bonus. The pairing ends if a second decision appears, including a “while we are here” rename.

5. Enforce the contract before overwrite

A small Python gate reads the log, the frozen snapshot, and the proposed diff before any file is overwritten. The script exits nonzero when questions, dead ends, or the rollback command are missing from the log. It also rejects a patch that touches a path outside allowed_files, which is the mechanical form of the kept decision.

#!/usr/bin/env python3
"""Refuse to apply a patch unless the pairing log holds a rollback contract."""
from __future__ import annotations

import json
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent
LOG_PATH = ROOT / "pairing_log.json"
FROZEN_DIR = ROOT / ".pairing_frozen"
RECEIPT_PATH = ROOT / "pairing_receipt.json"


def fail(message: str) -> None:
    print(f"pairing-gate: {message}", file=sys.stderr)
    raise SystemExit(1)


def load_log() -> dict:
    if not LOG_PATH.exists():
        fail("pairing_log.json is missing; freeze questions before any patch")
    return json.loads(LOG_PATH.read_text())


def require_questions(log: dict) -> None:
    questions = log.get("questions") or []
    if len(questions) < 4:
        fail("senior pairing requires at least four answered questions")
    for item in questions:
        if not item.get("text") or not item.get("answer") or not item.get("asked_by"):
            fail("each question needs text, asked_by, and a nonempty answer")


def require_dead_ends(log: dict) -> None:
    dead_ends = log.get("dead_ends") or []
    if not dead_ends:
        fail("record at least one rejected hypothesis before applying a patch")
    for item in dead_ends:
        if not item.get("hypothesis") or not item.get("reject_reason"):
            fail("each dead end needs a hypothesis and a reject_reason")


def require_decision(log: dict) -> None:
    decision = log.get("kept_decision") or {}
    if not decision.get("summary"):
        fail("kept_decision.summary is missing")
    if not decision.get("allowed_files"):
        fail("kept_decision.allowed_files must list the only paths a patch may touch")
    if not decision.get("rollback_command"):
        fail("kept_decision.rollback_command is the contract; do not apply without it")
    if decision.get("second_decision"):
        fail("this pairing allows one kept decision only")


def main(argv: list[str]) -> None:
    if len(argv) < 2:
        fail("usage: pairing_gate.py <file> [<file> ...]")
    log = load_log()
    require_questions(log)
    require_dead_ends(log)
    require_decision(log)
    allowed = set(log["kept_decision"]["allowed_files"])
    extra = [path for path in argv[1:] if path not in allowed]
    if extra:
        fail(f"patch touches files outside the kept decision: {extra}")
    for path in argv[1:]:
        frozen = FROZEN_DIR / path
        if not frozen.exists():
            fail(f"no frozen snapshot for {path}; freeze staging before the model runs")
    receipt = {
        "kept_decision": log["kept_decision"]["summary"],
        "files": argv[1:],
        "rollback_command": log["kept_decision"]["rollback_command"],
    }
    RECEIPT_PATH.write_text(json.dumps(receipt, indent=2) + "\n")
    print("pairing-gate: contract complete; operator may apply the listed files")


if __name__ == "__main__":
    main(sys.argv)

6. Apply, verify, or restore

After the gate passes, the overlap test runs against the staging replica before anyone celebrates the model output. Failure restores the frozen file and appends a new dead-end record instead of leaving the host half-patched. Success writes a short decision receipt so the next pairing session cannot claim the change was unsigned. The receipt is ordinary JSON, which later reviews can grep without opening a chat export from the model.

python3 pairing_gate.py app/jobs.py
# operator applies the one allowed file only after the gate prints success
python3 test_overlap.py || cp .pairing_frozen/app/jobs.py app/jobs.py

The patched region that matches the kept decision is the lock around the list swap, not a new framework. The rest of the handler, including status codes and logging behavior, stays frozen because it was never in the contract. If the overlap test still loses jobs, the copy command in the log is the entire incident response for this session. The pairing does not open a second prompt to “just try another idea” on the live host.

# kept patch inside do_POST — still a labeled example, not a benchmark
with _lock:
    current = list(JOBS)
    current.append(payload)
    JOBS[:] = current

Stop rules

A pairing session still needs a stop rule when the senior and the model disagree about scope. The markdown table below is the stop rule used in this worked example for staging patches. Rows are evaluated in order, and the first matching row wins without extra debate in chat. The gate script encodes the same rows so a tired operator cannot skip them under time pressure.

Condition	Pairing action	Server action
pairing_log.json missing an answered question	Stop the session	Leave staging untouched
Proposed files outside allowed_files	Reject the patch as a second decision	Leave staging untouched
Overlap test still loses jobs after apply	Append a dead-end record	Run rollback_command
Overlap test passes and receipt is written	Close the session	Keep the single-file change

Limitations

This workflow assumes two humans can sit with the same repository and a writable pairing_log.json file. It does not measure model quality, token burn, or server capacity, and it invents none of those numbers. A solo developer can still keep the log, but the senior questions then become self-review prompts with weaker resistance. Shared hosts that cannot snapshot a single file should not use the apply script at all.

The overlap test is a teaching probe for one race, not a load test and not a proof of thread safety under every runtime. ThreadingHTTPServer on localhost will not reproduce every failure mode of a remote free server under real traffic. The gate also cannot see side effects outside the listed files, such as crontab edits or manual package installs. Those gaps are why the kept decision stays small enough to undo with one copy command.

Who should skip this method

Teams with a real deployment pipeline, signed commits, and automatic rollback should not replace that pipeline with this pairing gate. The method is a teaching brake for agent trials on disposable staging, including a free server used for experiments. It is the wrong tool for production traffic, regulated data, or any host that other customers already share. It is also the wrong tool when nobody in the pairing can answer the four questions without guessing.

What the pairing actually kept

Engineering remains the pairing, the frozen baseline, and the one kept rollback contract written before the patch. Free model access only changes how fast a rejected idea can reappear, which is why dead ends must be files. Readers who already run agent trials on a shared host can copy the gate script and keep their current models. A useful next step is to run this freeze once on the next agent patch, then stop if the log cannot be filled honestly.

The Pairing Wrote a Failing Probe Before Any Free Model Could Patch

Avery Li — Fri, 18 Sep 2026 08:20:07 +0000

The pairing kept one rule when a green suite hid a defect: a senior-authored probe had to fail first. Coverage percentages did not count as evidence, because they never named the invariant the path violated. The session treated existing tests as a map of prior beliefs, not as an oracle for this bug. Only after that failing probe existed did the pair allow a free model run on an allowlisted server.

Green coverage is a memory, not a verdict

A modern agent can raise line coverage while leaving the real contract untouched, especially on branches that serialize money, identity, or retries. The suite still reports success because earlier engineers asserted shapes, status codes, and happy paths, not the missing invariant. Pairing with a senior is useful here because the senior can name what the suite never said. The junior and the model cannot recover that missing name from passing tests or from a coverage badge alone.

Recent public debate about vibe coding versus engineering often collapses into taste, slogans, and tool loyalty. This pairing ignored that noise and instead asked a narrower question about what counted as evidence. A patch was not engineering work until a human could point at one failing check the suite had omitted. Without that check, a free model would optimize for the tests that already existed and would look productive while remaining wrong.

Questions the senior asked before any model ran

The senior did not start by opening an editor or by pasting a stack trace into a chat panel. The senior walked the failing production path on a whiteboard and forced every claim into a named object. The pairing recorded four questions in the session notes before any assistant call was made. Those answers later became fields on a small probe card checked into the branch.

What sentence states the invariant in domain language, without mentioning mocks, fixtures, or framework glue?
What input is the smallest counterexample that currently returns a wrong value or performs a forbidden side effect?
Which assertion in the existing suite would stay green even when that counterexample is replayed against the handler?
What side effect must the new probe forbid, such as a second charge or a dropped idempotency key?

Each question required an answer that named a path, a symbol, or a concrete payload. Vague answers such as the payment flow or the tests around checkout were rejected and rewritten on the spot. The pairing did not proceed while any of the four answers still pointed at a directory instead of a file or a value.

Dead ends the session closed

The first dead end was asking a model to write the new tests before a human had named the invariant. That order looks efficient, yet it lets the model invent assertions it can already satisfy. The second dead end was treating a high coverage badge as permission to ship, even though the counterexample never entered the suite. The third dead end was booting a shared server early so the agent could explore, which mixed probe evaluation with unbounded shell access.

Those three paths were written into the session notes as closed, not as later options. Closing them mattered because each path would have produced a plausible transcript and a green job. The pairing needed a result that could still fail after the existing suite had passed. The senior kept the conversation on that single gap until the probe card had a failing command.

The decision the pair kept

The kept decision was a probe gate, not a broader process rewrite and not a new chat persona. A human had to commit one failing contract probe that encoded the missing invariant in ordinary test code. A model could propose a patch only against an explicit file list, and only after that probe failed on the current branch. A free server could run only allowlisted commands that executed the probe, not an open shell.

The pair then used MonkeyCode only as the later execution lane, after the failing probe and the command allowlist already existed. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source coding assistant with operator-supplied free model access and a free server option, which the pairing treated as a constrained runner rather than as an author of tests. Free model access was reserved for proposing a patch against the frozen file list, not for inventing coverage. The free server option was reserved for running allowlisted probe commands, not for open-ended exploration of the repository.

A probe card the branch can carry

The pairing stored the answers as a short Markdown card beside the probe, so later reviewers could see the invariant without replaying the conversation. The card below is a proposed template, not a claim about any product file format. Teams can keep it in pairing/probe-card.md or fold the same fields into the test docstring.

# Probe card: double charge on retry

- Invariant: a paid idempotency key must not create a second capture.
- Counterexample: POST /charges with key K1, then replay the same body after a 504.
- Existing suite gap: tests/test_charges_api.py asserts HTTP 201 and JSON shape only.
- Forbidden side effect: ledger.capture_count(K1) must remain 1.
- Probe command: pytest -q tests/test_contract_probe.py::test_replay_does_not_double_capture
- Writable files: app/charges.py, app/ledger.py
- Frozen files: tests/test_charges_api.py, pairing/probe-card.md
- Allowlisted commands: python -m pytest, python -m compileall app

The card is small on purpose, because a long narrative invites the next session to skip reading it. Reviewers should be able to reject a patch that touches a frozen file without debating model quality. The probe command should be one line that a gate script can run twice: once before the patch, and once after. If the before run does not fail, the gate has nothing honest to measure.

Contract probe the senior wrote by hand

The example below is labeled as an unexecuted illustration of a missing invariant around charge replay. It does not pretend to be production billing code, and it does not call any hosted model. The important property is that the existing suite can stay green while this probe fails on the same handler.

# tests/test_contract_probe.py
# Proposed local example. Not executed against a live payment network.

from app.charges import ChargeHandler
from app.ledger import InMemoryLedger


def test_replay_does_not_double_capture():
    ledger = InMemoryLedger()
    handler = ChargeHandler(ledger)
    body = {"idempotency_key": "K1", "amount_cents": 1500, "currency": "USD"}

    first = handler.create_charge(body, upstream_status=201)
    replay = handler.create_charge(body, upstream_status=504)

    assert first.status in {"captured", "pending"}
    assert replay.status in {"captured", "pending", "replayed"}
    assert ledger.capture_count("K1") == 1
    assert ledger.captures_for("K1")[0].amount_cents == 1500

A matching handler sketch helps the pairing show why coverage can lie. The buggy version increments the ledger on every retry path that looks new to the HTTP layer. The existing API test never replays a 504, so it never sees the second capture. The probe makes that gap visible without asking a model to notice it.

# app/charges.py  (buggy sketch for the pairing, not a library)

class ChargeHandler:
    def __init__(self, ledger):
        self.ledger = ledger

    def create_charge(self, body, upstream_status=201):
        key = body["idempotency_key"]
        # Bug: retry after 504 is treated as a fresh capture.
        if upstream_status == 504 or not self.ledger.has(key):
            self.ledger.capture(key, body["amount_cents"])
            return type("Result", (), {"status": "captured"})()
        return type("Result", (), {"status": "replayed"})()

Numbered pairing workflow

The workflow is a gate, so each step has an exit that does not spend model time. The commands are local proposals that any repository can adopt. Replace tool names with the team runner if the pair already has one.

Write the probe card and the failing test in the same change, with frozen files listed explicitly.
Run the probe once on the current branch and store the failing output beside the card.
Refuse to continue if the probe is green, because then the invariant is not actually missing.
Open a constrained assistant session only after the failing output exists in git or in the session notes.
Allow the model to edit only the writable files, then rerun the same probe command with no extra flags.
Keep the patch only when the probe turns green and the frozen files still match git diff --stat.

# Proposed local gate. Label: unexecuted example.
set -euo pipefail
PROBE="tests/test_contract_probe.py::test_replay_does_not_double_capture"
CARD="pairing/probe-card.md"
ALLOW="pairing/allowlist.txt"

test -f "$CARD"
git diff --name-only -- "$CARD" | grep -q . && echo "card should be committed before model work" && exit 1

if pytest -q "$PROBE"; then
  echo "probe is green; the gate has no defect to measure"
  exit 1
fi

echo "probe failed as required; model work may start on writable files only"

After a patch is proposed, the pair reruns one allowlisted command and inspects the file list. The review is boring on purpose. Boring reviews are cheaper than arguing about whether the model understood checkout.

# After the proposed patch
pytest -q tests/test_contract_probe.py::test_replay_does_not_double_capture
git diff --name-only > /tmp/touched.txt
# fail if any frozen file appears in /tmp/touched.txt

Allowlist for the free server lane

The pairing did not treat a free server as a general workstation. It treated the server as a place to evaluate one command family. The allowlist below is a proposed text file, not a documented product interface. A wrapper can reject any argv that is not a prefix match.

# pairing/allowlist.txt
python -m pytest tests/test_contract_probe.py
python -m pytest tests/test_contract_probe.py::test_replay_does_not_double_capture
python -m compileall app
git diff --name-only
git diff --stat

# scripts/allowlist_exec.py
# Proposed local wrapper. Unexecuted example.

from pathlib import Path
import subprocess
import sys

allowed = [
    line.strip()
    for line in Path("pairing/allowlist.txt").read_text().splitlines()
    if line.strip() and not line.startswith("#")
]
request = " ".join(sys.argv[1:])
if request not in allowed:
    raise SystemExit(f"command not allowlisted: {request}")
raise SystemExit(subprocess.call(sys.argv[1:]))

The wrapper is intentionally strict, including exact command strings instead of regex. Strictness prevents a model from appending -k filters, extra paths, or shell metacharacters that the senior never approved. If the pair needs a new command, a human adds it to the allowlist in a separate change. That extra commit is part of the evidence, not ceremony.

Decision table for the gate

Observation on the branch	Action the pairing takes	Why the action is kept
Existing suite green, probe missing	Stop and write the probe card	No invariant has been named
Probe green on current code	Rewrite the counterexample	The gate cannot measure a defect
Probe red, frozen file dirty	Revert the frozen file	The suite gap must remain visible
Probe red, writable files only	Allow a constrained model pass	The patch has a failing check to beat
Probe green after patch, allowlist intact	Keep the diff for human review	The missing invariant is now asserted
Command not in allowlist	Reject the server run	Exploration is not evaluation

The table is the artifact reviewers can apply without joining the original pairing session. It also prevents a later session from reopening the three dead ends under a friendlier name. If a row does not match, the pair writes a new card instead of stretching this one. Stretching cards is how green suites become fiction again.

Limitations

The probe is only as honest as the invariant the senior named, and seniors are sometimes wrong about production. A precise probe can still miss a neighboring defect, such as a currency mismatch that the replay never included. An allowlist can be copied too widely, after which the free server lane becomes an ordinary shell with extra steps. Free model access and a free server option are availability claims for this workflow, not a promise of capacity, latency, model identity, or lasting uptime.

The gate also does not replace code review, threat modeling, or a staging replay against real vendor sandboxes. It only blocks a common failure mode in which an assistant looks busy while the original suite stays silent. Teams that need quantitative comparisons should measure their own probe fail-then-pass rate on their own branches. This article does not offer unpublished benchmarks, model names, token quotas, or hardware details.

Who should not use this approach

Solo work without anyone who can name a domain invariant should not pretend this gate exists. Incident commanders under time pressure should not pause a live outage to invent a probe card format. Teams whose policy forbids remote execution should not route secrets, customer payloads, or production credentials through a free server lane. Security-sensitive patching that can change authorization should stay on an internal runner with a reviewed identity, even if a probe already fails locally.

The pairing format also wastes time on purely cosmetic diffs, dependency bumps, and generated code where no business invariant is at stake. In those cases a linter or a compiler is already a better oracle than a senior interview. Use the probe gate when a green suite can hide a second charge, a dropped key, or another contract the tests never wrote down. Leave it idle when the change cannot produce that class of lie.

Readers who already keep a failing probe in git can try the same order with free model access and a free server option, then keep or discard the patch based on that probe alone.

The Pairing Computed a Blame Window Before Any Free Model Saw the Bug

Avery Li — Thu, 17 Sep 2026 06:37:09 +0000

A pairing session should freeze a git blame window before any free model or free server sees the failing test. Unbounded agent search burns tokens on refactors, generated files, and comments that never caused the regression. The senior in this protocol treats blame as a contract, not as a hint, and refuses remote help until that contract exists. The kept decision is a small packet of paths, commits, and a replay command that any later model must respect.

The pairing problem

Agent debugging often starts with a paste of the repository tree and a request to find the bug. That opening move hides ownership, mixes generated noise with real edits, and makes later review almost impossible. The protocol below is a proposed pairing workflow, not a report of a single production incident. It exists so a senior and a driver can leave a replayable packet instead of a chat transcript.

Questions the senior asked

The senior does not start with model selection and does not start with a remote machine. The senior starts with a short question list that the driver must answer from local evidence. Each answer must name a file, a command, or a commit, because adjectives do not shrink a search. The pairing records those answers in questions.md before anyone discusses models or a free server.

The recorded file is a pairing artifact, not a chat log, and it stays in the repository beside the failing test. The driver fills every line from commands already run on the laptop, never from memory of an earlier agent session. Incomplete answers are treated as a stop condition rather than as a reason to widen the prompt. The proposed questions.md shape looks like the block below.

# questions.md — pairing record (proposed, unexecuted example)

Q1. Which test is the first unique failure, including file, case, and assertion text?
A1. tests/billing/test_proration.py::test_partial_month_keeps_credit
    signature: AssertionError: expected 420, got 399

Q2. Which source path last changed the failing assertion, according to git blame?
A2. billing/proration.py:88  commit 9f2c1aa  (not the formatting commit on line 1)

Q3. Does that path sit in generated code, vendor code, or a large rename window?
A3. No. Denylist rejected proto/*, vendor/*, and **/*.snap.

Q4. What command replays the failure in under one minute on a cold checkout?
A4. pytest -q tests/billing/test_proration.py::test_partial_month_keeps_credit

Q5. What will this pairing refuse to send off the machine?
A5. Anything outside blame_window.json paths, plus secrets, .env, and fixture dumps.

Dead ends the pairing logged

The first dead end appeared when the driver blamed an entire service file after a generic test name. Git blame then pointed at a formatting commit, a rename, and a license header that never touched control flow. The pairing discarded that window because it could not name a unique assertion or a unique function. The dead-end register stored the rejected command so the next model prompt could not repeat it.

The second dead end appeared when vendor directories and generated protobuf stubs entered the same blame window. Those paths changed often, carried no readable intent, and would have dominated any later model context window. The senior required a path denylist before any further blame computation could be considered a complete packet. The register recorded the denylist as a first-class file rather than as a remembered conversation detail.

The next dead end used HEAD~50 as a lazy commit range after a large directory rename in history. Follow-up copies of the same function appeared twice, and the failing assertion no longer mapped to one side. The pairing replaced the numeric range with an explicit merge-base against the last known green default branch. That replacement became the only commit bound that the pairing later allowed inside the kept decision packet.

A further dead end sent a full stack trace without extracting the unique assertion message from the test runner. Models then proposed patches for log lines, retries, and timeouts that never appeared in the failing expectation. The pairing now requires a one-line failure signature copied from the test output before remote work starts. Without that signature, the gate script exits nonzero and no free model call is constructed at all.

The dead-end register is append-only JSONL so a later reader can see rejected paths without reconstructing Slack. Each line names the hypothesis, the command, the reason, and the next constraint the senior added. The pairing does not delete dead ends when a better window appears, because deleted failures return as fresh suggestions. A proposed log looks like the following example.

{"id":"de-01","hypothesis":"blame whole billing/proration.py","command":"git blame billing/proration.py","reason":"window included license header and a rename","next":"blame only the assertion line"}
{"id":"de-02","hypothesis":"include generated stubs for extra context","command":"git diff --stat proto/","reason":"generated paths churn every build","next":"add proto/ and vendor/ to denylist"}
{"id":"de-03","hypothesis":"HEAD~50 is a safe default window","command":"git log --oneline HEAD~50..HEAD -- billing/","reason":"rename duplicated the function","next":"use merge-base with origin/main"}
{"id":"de-04","hypothesis":"paste full traceback into the model","command":"pytest -vv","reason":"trace mixed timeouts with the real assertion","next":"keep one-line failure signature only"}

The decision the pairing kept

After the dead ends, the pairing kept one decision and wrote it down as a machine-checkable packet. The packet contains a blame window, a path denylist, a replay script, and a one-line failure signature. Remote or free-model help may read only those files, plus the source paths listed in the window. Anything outside that set is treated as leakage and is a protocol failure, not a convenience.

The kept decision is boring on purpose, because boring packets are reviewable in a pull request. The senior signs the packet by merging blame_window.json before any agent diff is allowed to land. The driver may still type in a model product after that merge, but the prompt is generated by a gate, not by memory. The rest of this article is the packet format and the commands that enforce it.

Artifact: the blame window packet

The packet lives in the repository root beside the failing test, not in a disposable chat sidebar. The pairing treats missing keys as a failed build rather than as an invitation to improvise. The following workflow is labeled as a proposed, unexecuted example and should be adapted to the local default branch name. Numbered steps keep the senior and the driver on the same checklist.

Step 1: Capture a unique failure signature

The driver reruns one test until the assertion line is stable across two consecutive executions. The pairing copies that one line into the packet and ignores the surrounding traceback frames. A signature that still mentions retries, sockets, or timestamps is rejected as too broad. The command below is the only replay the later gate will accept.

# Proposed local replay. Label: unexecuted example.
pytest -q tests/billing/test_proration.py::test_partial_month_keeps_credit
# Expected unique signature:
# AssertionError: expected 420, got 399

Step 2: Compute a candidate blame window

The driver blames the assertion line, not the file, and prints porcelain output for a single range. The senior watches for formatting commits, copy-right headers, and generated markers before accepting the sha. If blame lands on a generated path, the pairing logs a dead end and stops. The helper script below encodes that stop condition.

#!/usr/bin/env bash
# compute_blame_window.sh — proposed pairing helper, unexecuted example.
set -euo pipefail

FAIL_FILE="${1:?path to failing source file}"
FAIL_LINE="${2:?1-based line number}"
DEFAULT_BRANCH="${3:-origin/main}"
DENY_FILE="${4:-blame_denylist.txt}"

if [[ ! -f "$FAIL_FILE" ]]; then
  echo "dead_end: missing_file $FAIL_FILE" >&2
  exit 2
fi

if [[ -f "$DENY_FILE" ]] && echo "$FAIL_FILE" | grep -E -f "$DENY_FILE" >/dev/null; then
  echo "dead_end: path_denied $FAIL_FILE" >&2
  exit 3
fi

MERGE_BASE="$(git merge-base HEAD "$DEFAULT_BRANCH")"
echo "merge_base=$MERGE_BASE"

git blame -L "$FAIL_LINE,$FAIL_LINE" --porcelain "$FAIL_FILE" | awk '
  /^[0-9a-f]{40} / { sha=$1 }
  /^filename / { fname=$2 }
  END { print "blame_sha=" sha; print "blame_file=" fname }
'

A tiny denylist keeps the second dead end from returning on the next session. The pairing reviews that file the same way it reviews .gitignore, because both files define what must stay local. Generated stubs, snapshots, and vendored trees belong there even when they appear in the stack. The example denylist is intentionally short.

# blame_denylist.txt
^proto/
^vendor/
\.snap$
\.pb\.go$
\.generated\.

Step 3: Bind the merge-base instead of a numeric range

Numeric ranges look fast and then fail after renames, squash merges, and bot commits. The pairing asks git for the merge-base with the last known green default branch and stores that sha. Later prompts may read diffs only inside that bound, which keeps rename copies from doubling the window. The driver records the bound in the packet rather than in a spoken agreement.

# Proposed bound. Label: unexecuted example.
git merge-base HEAD origin/main
git diff --name-only "$(git merge-base HEAD origin/main)" -- billing/proration.py

Step 4: Write the packet the gate will trust

The packet is JSON because a missing key should fail in CI, not in a hallway conversation. The senior reads the paths array aloud and confirms each path is a real tracked file. The replay field must be a single command the driver has already run twice. The proposed packet for this writeup is the object below.

{
  "failure_signature": "AssertionError: expected 420, got 399",
  "merge_base": "b4e91c0d9f3a7c1e2a8b0d4f6c7e9a1023344556",
  "paths": ["billing/proration.py", "tests/billing/test_proration.py"],
  "denylist": ["proto/", "vendor/", "*.snap"],
  "replay": "pytest -q tests/billing/test_proration.py::test_partial_month_keeps_credit",
  "kept_decision": "Send only the blame window packet off-machine. Reject whole-repo prompts."
}

Step 5: Gate any remote or free-model prompt

The gate reads the packet, builds a constrained prompt, and refuses to run when keys are missing. Humans can still bypass the gate, which is why the pairing also reviews the prompt file in the same pull request. The script prints the prompt to stdout so the driver can see exactly what leaves the laptop. This is proposed code, not a production security boundary.

#!/usr/bin/env python3
"""gate_before_remote.py — proposed pairing gate, unexecuted example."""
import json
import sys
from pathlib import Path

REQUIRED = ("failure_signature", "merge_base", "paths", "replay", "denylist")


def load_packet(path: Path) -> dict:
    data = json.loads(path.read_text())
    missing = [key for key in REQUIRED if key not in data]
    if missing:
        raise SystemExit(f"dead_end: missing_keys {missing}")
    if not str(data["failure_signature"]).strip():
        raise SystemExit("dead_end: empty_failure_signature")
    if not data["paths"]:
        raise SystemExit("dead_end: empty_paths")
    if not str(data["replay"]).strip():
        raise SystemExit("dead_end: empty_replay")
    return data


def build_prompt(data: dict) -> str:
    path_lines = "\n".join(f"- {path}" for path in data["paths"])
    deny_lines = "\n".join(f"- {rule}" for rule in data["denylist"])
    return (
        "Stay inside the blame window. Do not request other files.\n"
        f"Failure signature: {data['failure_signature']}\n"
        f"Merge base: {data['merge_base']}\n"
        f"Paths:\n{path_lines}\n"
        f"Denylist:\n{deny_lines}\n"
        f"Replay: {data['replay']}\n"
        "Propose a patch only if the replay command stays unchanged.\n"
    )


if __name__ == "__main__":
    packet = load_packet(Path(sys.argv[1]))
    sys.stdout.write(build_prompt(packet))

Step 6: Compare any later patch to the replay, not to the chat

The pairing applies a candidate patch on a fresh branch and runs only the stored replay command. If the unique signature disappears, the pairing still reads the diff against the blame paths before merge. If the patch touches a denylisted path, the pairing logs another dead end and reverts. Chat agreement never overrides a failed replay.

# Proposed verification. Label: unexecuted example.
git checkout -b pairing/proration-window
# apply the candidate patch, then:
python3 gate_before_remote.py blame_window.json > /tmp/pairing-prompt.txt
pytest -q tests/billing/test_proration.py::test_partial_month_keeps_credit
git diff --name-only

Decision table the senior keeps on the desk

The table is part of the artifact because it turns arguments into rows the pairing can reject quickly. The driver does not negotiate extra files after the packet is written, except by logging a new dead end and starting over. The senior uses the table during review to explain why a convenient paste was refused. The rows below match the dead ends already recorded.

Observation	Pairing action	Allowed off-machine
Unique assertion plus one blamed line	Write `blame_window.json`	Packet paths only
Blame hits `vendor/` or generated stubs	Log dead end, extend denylist	Nothing until packet is rewritten
Numeric `HEAD~N` after a rename	Replace with `git merge-base`	Nothing until merge-base is stored
Full traceback without a one-line signature	Stop the gate	Nothing
Candidate patch changes denylisted paths	Revert and log dead end	Nothing
Replay still fails with the same signature	Keep the packet, reject the patch	Packet may be reused

Using free model access only after the packet exists

Once the packet exists, the pairing still does not paste the repository into a chat box. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source coding assistant with operator-supplied free model access and a free server option. Those two availability claims are the only product capabilities this protocol depends on, and no quota, model name, or hardware size is asserted here. The pairing uses that access only as a runner for the already-narrowed packet, never as a search engine for the whole tree.

The practical sequence is local packet, local gate, then a constrained session if the pairing still wants a second reader. The free server option matters when the laptop should not keep a long agent process, not when the repository still lacks a blame window. The free model path matters when the pairing wants another pass over the same four files without opening a paid account first. Neither option repairs a missing signature, a missing merge-base, or a denylist the senior has not reviewed.

A pairing that skips the packet and jumps straight to any hosted agent is doing a different activity. That activity can still find bugs, but it leaves no replayable ownership trail for the next reviewer. This protocol prefers a smaller, duller prompt that a later engineer can regenerate from git. The product mention stays secondary because the gate would work with any later runner that accepts a text prompt.

Limitations

The blame window protocol fails when the regression is a configuration change with no line to blame in application code. It also fails when the failing assertion is nondeterministic, because the signature will not stay unique across two replays. Binary fixtures, data migrations, and time-dependent tests need a different packet, usually built from seeds and clocks rather than from git blame. Pairings that ignore those cases will freeze the wrong files and then trust a confident patch.

The gate script is not a sandbox, not a secret scanner, and not an access-control system for a shared server. A driver can still paste extra files, and a model can still ask for them. The protocol only makes that extra paste visible in questions.md, dead_ends.jsonl, and the generated prompt file. Teams that need isolation still need their existing policy for credentials, production data, and licensed dependencies.

Git history itself can lie after copy, squash, or filter-repo, which is why the senior still reads the blamed commit. Merge-base against a moving default branch can shift between pairing sessions if someone lands unrelated work. The packet should therefore pin the merge-base sha rather than the branch name at review time. Without that pin, two pairings can believe they share a window while reading different diffs.

Who should not use this approach

Solo developers who already know the failing line and can patch it in one edit do not need this packet. Incident responders who must change production configuration in minutes should not wait on blame porcelain and a denylist review. Pairings working in generated-only repositories, such as some schema-first trees, will spend the session fighting the denylist. Beginners who have not yet learned git merge-base should practice that command on a toy repo before adding a model runner.

Teams without a unique automated test should also skip this workflow, because the replay field would be theater. If the only reproduction is a manual click path, the pairing needs a scripted client first, then a blame window. The protocol assumes the senior can reject extra files without political cost, which is not true in every organization. Where that rejection is impossible, the packet becomes documentation of a leak rather than a gate.

What the pairing leaves behind

The useful residue is not a clever prompt. The useful residue is questions.md, dead_ends.jsonl, blame_window.json, and a replay that still fails or still passes on a clean checkout. A later engineer can regenerate the same constrained prompt without trusting anyone's memory of the session. That is the whole point of computing the blame window before any free model sees the bug.

Pairs that already keep a blame window packet can run the same gate, then try MonkeyCode's free model access and free server option against that packet and compare the replay log with the kept decision.