Skip to content

docs: a count is a copy too — four places still said deploying is three steps (C-343) - #507

Merged
Polichinel merged 1 commit into
developmentfrom
docs/c343-step-count-drift
Oct 20, 2026
Merged

Polichinel merged 1 commit into
developmentfrom
docs/c343-step-count-drift

Conversation

@Polichinel

Copy link
Copy Markdown
Contributor

The deploy worked, which is what made the audit possible

v1.15.0 deployed with all four blocks, and all three of block 4's commands named the same version:

cat ~/.views-deploy-tag                                → v1.15.0
git describe --tags --exact-match                      → v1.15.0
ls .venv/lib/python*/site-packages | grep views_data…  → views_datafactory-1.15.0.dist-info

uv sync printed - views-datafactory==1.14.0 / + views-datafactory==1.15.0, so block 3 is now
load-bearing on two measurements rather than one.

The new fact is not that it worked — it is that block 4 ran at all. On 2026-10-16 its first
command died on the ~-expansion defect, which means the verification block added on 2026-10-13 had
never once executed successfully. #498's fix is confirmed by execution rather than by reading, which
is the distinction this entry keeps failing on.

Then the grep that found round five

Writing that up prompted a search for the step count rather than the step content — a
dimension none of the four previous rounds audited. Four live copies still said three:

Location Said
reports/technical_risk_register.md — C-343's row in ## Open Items Summary "deploy with all three server_quickref.md steps", then listed the three checks that constitute step 4
reports/technical_risk_register.md — C-343's own Trigger: field "Deploy with all three steps from server_quickref.md"
docs/guides/hetzner_deployment_guide.md release-ritual item 5 "Deploy = three steps on the server, not one", enumerating exactly three
scripts/refresh_pipeline.sh header comment "with ALL THREE steps in docs/guides/server_quickref.md"

Two of the four were inside the entry doing the hunting, one of them its Trigger: — the field an
operator is meant to act on.

The script comment is the sharpest

Its very next sentence reads:

"two copies of a procedure drifting apart is what C-343 IS, and a fix that adds a third copy would
be the same bug"

And it had drifted. It carefully avoided duplicating the commands, then duplicated the number — which
was the one part that changed. A count is a copy too. The comment now records that it said THREE
until today, five weeks after the fourth block was added, because a comment that was wrong about the
thing it warns against should say so.

Why no new register entry

Same entry, same mechanism, fifth round. What the round changes is where the mechanism hides:
rounds one through four hunted copies of the procedure and found them in guides and ADRs. This one
found that the procedure's cardinality is independently copyable, and that #500 audited seven
duration figures across the same guides without checking a step count — because nothing suggested a
count could rot.

A fifth instance of the confusion, one layer up, and it is mine

The #501 instrumentation was merged to development and then described to the operator as something
the next cron run would pick up "automatically". It would not have: the server runs a tag, and
v1.14.0 did not contain it. Merging the instrumentation is not deploying the instrumentation is
the same confusion as writing the tag is not deploying, displaced from the tag file to the branch —
committed three days after this entry's fourth round, by whoever wrote that round. Corrected on #501
before any wait was incurred.

Recorded on the entry because five instances across three months is the evidence, and every one came
from reasoning about the procedure instead of opening it.

Deliberately left as written

Per #500's precedent — a record is amended, never rewritten to look current:

  • C-331's narrative at "deploying is three steps, not one" — true when written, and the sentence
    is about the one-run lag rather than the procedure
  • docs/ADRs/022_tag_based_deployment_gate.md's "This section previously gave deploying as three
    steps"
    — correct as a description of what it previously said
  • reports/register_changelog.md's account of a past redeploy "run as all three steps" — it was
    three at the time

And docs/guides/server_quickref.md:136's "use all three checks in step 4" is correct: step 4
holds three commands. Four blocks whose fourth contains three checks is a fair part of why the count
drifted, and is noted as such rather than treated as a defect.

What remains, and is not in this PR

Five rounds of documentation correction have produced a procedure that executes correctly when
followed. They have produced nothing that notices when it is not followed. #424's pre-flight gate
would catch a tag/HEAD mismatch; it would not catch the #501 variant, where the code never
reached a tag at all. Nothing compares what the server is running against what the repository
expects, at any layer.

Verification

Check Result
uv run pytest — full suite, exit code captured EXIT=0, 0 FAILED, 0 ERROR
All 14 register-reading test files, run not sampled 41 passed
uv run ruff check . All checks passed
uv run mypy src/ Success — 89 source files
bash docs/validate_docs.sh PASSED
bash -n scripts/refresh_pipeline.sh syntax OK
notebooks/acled_cursor_parity.ipynb re-executed, no network 3 slices, 106,329 events, every oracle held, 0 errors; digests identical on all three

Exit code captured rather than inferred from absent FAILED lines — 137 is SIGKILL/OOM and prints no
failures at all (C-345).

The notebook was re-executed to a scratch copy, so the committed version is untouched; it is in this
PR's verification because it is the artifact that can still make the offset-vs-cursor parity claim
after 27 October, when the offset side can no longer be recorded.

Refs #501.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EfeuULbPTqrx4qtNki5dy9

…ee steps (C-343)

v1.15.0 deployed with all four blocks and all three verification commands
naming the same version, so C-343's corrected procedure completed end to end
for the first time — step 4 included. That matters because on 2026-10-16 step
4's first command died on the `~`-expansion defect, meaning the verification
block added on 2026-10-13 had never once executed successfully. #498's fix is
now confirmed by execution rather than by reading.

Writing that up prompted a grep for the step COUNT rather than the step
CONTENT — a dimension none of the four previous rounds had audited. Four live
copies still said three:

  reports/technical_risk_register.md  C-343's Open Items Summary row
  reports/technical_risk_register.md  C-343's own Trigger: field
  docs/guides/hetzner_deployment_guide.md  release-ritual item 5
  scripts/refresh_pipeline.sh  header comment

Two of the four were inside the entry doing the hunting, one of them its
trigger — the field an operator is meant to act on. The summary row said
"three steps" and then listed the three checks that constitute step 4, so it
described four things while naming three.

The script comment is the sharpest. Its very next sentence reads "two copies
of a procedure drifting apart is what C-343 IS, and a fix that adds a third
copy would be the same bug" — and it had drifted, because a count is a copy
too. It carefully avoided duplicating the commands and then duplicated the
number, which was the one part that changed. The comment now records that it
said THREE until today, five weeks after the fourth block was added.

No new register entry: same entry, same mechanism, fifth round. What the round
relocates is where the mechanism hides — rounds one to four hunted copies of
the procedure and found them in guides and ADRs; this one found that the
procedure's cardinality is independently copyable.

Also recorded on the entry, because it is the same confusion one layer up: the
#501 instrumentation was merged to development and then described to the
operator as something the next cron would pick up automatically. It would not
have — the server runs a tag and v1.14.0 did not contain it. Merging the
instrumentation is not deploying the instrumentation, committed three days
after the fourth correction by whoever wrote it. Corrected on #501 before any
wait was incurred.

Left as written, per #500's precedent that a record is amended and never
rewritten to look current: C-331's narrative, ADR-022's "previously gave
deploying as three steps", and register_changelog.md's account of a past
redeploy. server_quickref.md:136's "all three checks in step 4" is correct —
step 4 does hold three commands, and four blocks whose fourth contains three
checks is a fair part of why the count drifted.

Verification: full suite EXIT=0, 0 FAILED, 0 ERROR; all 14 register-reading
test files 41 passed; ruff check . clean; mypy src/ clean (89 files);
validate_docs.sh PASSED; bash -n scripts/refresh_pipeline.sh OK.
notebooks/acled_cursor_parity.ipynb re-executed from committed fixtures with
no network: 3 slices, 106,329 events, every oracle held, 0 errors.

Refs #501.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EfeuULbPTqrx4qtNki5dy9
@Polichinel
Polichinel enabled auto-merge (squash) October 20, 2026 02:19
@Polichinel
Polichinel merged commit bdfce76 into development Oct 20, 2026
6 checks passed
@Polichinel
Polichinel deleted the docs/c343-step-count-drift branch October 20, 2026 02:32
Polichinel added a commit that referenced this pull request Oct 20, 2026
…ve times in eight days (C-343) (#509)

Covers the export phase instrumentation (#501/#502), four rounds of C-343
correction (#497-#500), the release/publish/deploy of v1.15.0, a fifth C-343
round found while writing this up (#507), and a licensing contradiction found
while onboarding an external consumer (#508).

The v1.11.0 post-mortem named the spine running through everything it
reported: "a written record that was true when written and stopped being true
without anything failing." Both it and its companion observation — that the
post-mortem convention keeps failing to be applied — recurred.

Three of the four releases since are unwritten and now never will be. The
spine produced five fresh instances in eight days, all in C-343, the fifth
found inside the register entry created to track the first, including in its
Trigger: field. A sixth variant was committed by the author of the fourth
correction three days later: merging the instrumentation is not deploying the
instrumentation.

The conclusion recorded is not "try harder". Every instance in this window was
found by a human asking an unprompted question or by an author re-reading
their own work. Five rounds have produced a procedure that is right and
nothing that notices when a copy of it goes wrong.

Also records what went well rather than only the failures: block 4 of the
deploy procedure executed successfully for the first time since it was
written, the #501 falsification criterion was committed before any production
figure existed, three guards were sabotaged and confirmed red, and the clean-
venv publish check caught a defect in itself rather than a false alarm on the
release.

Verification: validate_docs.sh PASSED; all 14 register-reading test files
41 passed. Every figure quoted is cited to a file rather than recalled; the
release count was corrected against `git tag` before committing.

Refs #501, #508.


Claude-Session: https://claude.ai/code/session_01EfeuULbPTqrx4qtNki5dy9

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant