Conversation
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bbdf91f79b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Pull request overview
Adds a hygiene lint tool intended to enforce GOVERNANCE.md §33 archive-boundary headers on courier-ferry / external-conversation imports in docs/research/**, and records follow-up work as a backlog row (backfill existing violations + later CI wiring).
Changes:
- Add
tools/hygiene/check-archive-header-section33.shto detect missing §33 headers in the first 20 lines of in-scope research docs. - Add backlog row B-0036 tracking the planned backfill of existing violations and subsequent CI wiring.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| tools/hygiene/check-archive-header-section33.sh | New lint script to detect missing §33 archive headers in courier-ferry/external-conversation research docs. |
| docs/backlog/P3/B-0036-section33-archive-header-backfill-and-ci-wire-otto-346-pattern.md | New backlog item documenting the two-step rollout plan (backfill, then CI enforcement). |
…archive header lint + B-0036 backfill backlog Otto-346 substrate-primitive shape: GOVERNANCE.md §33 archive-header missing was the most-common review finding across the 11-Amara- refinement courier-ferry lineage this session (PRs #560/#562/#563/ #565/#566/#568/#569/#570/#553 each retrofitted post-review). Recurring identical review-finding pattern = signal that the discipline lacks automated enforcement. Per Otto-346 (recurring inline pattern → substrate primitive missing) + Otto-341 (mechanism over vigilance), the fix is a CI lint that catches the violation pre-merge. This commit ships the lint TOOL (not yet wired to CI) + a B-0036 backlog row for the two sequential follow-ups (backfill 26 pre-existing docs + wire to CI gate.yml). Tool behavior: - Scans docs/research/**.md for courier-ferry/external-conversation imports (filename or content patterns) - Validates first-20-lines contains all 4 §33 labels in literal form: Scope: / Attribution: / Operational status: / Non-fusion disclaimer: - Bold-styled (**Scope**:) form rejected per #570 P0 finding - Reports first violation with diagnostic - Exits non-zero on any violation Smoke-test on main found 26 pre-existing violations — confirms the substrate-debt is real and the lint catches it. Backfill is owed via B-0036 Sub-task 1; CI wiring is owed via Sub-task 2 (after backfill clears the residual). Composes with: - check-tick-history-order.sh (same pattern: structural-prevention via lint, not vigilance; that lint emerged from the same Otto-346 shape for the row-ordering bug) - audit-md032-plus-linestart.sh (sibling md-lint hygiene tool) - Otto-229 (recurring discipline violation → CI lint as fix) - Otto-238 (visible reversal not silent fix; backfill preserves per-doc lineage) Tool is standalone; not yet wired to CI gate.yml. Sub-task 2 of B-0036 covers the wiring after Sub-task 1's backfill PR clears the residual.
…parameter expansion (shellcheck)
ShellCheck SC2295 caught: '${file#$REPO_ROOT/}' has the unquoted
$REPO_ROOT/ inside the parameter expansion, which would be treated as
a glob pattern. Right fix: '${file#"$REPO_ROOT/"}' — quoting forces
literal-string match.
This is the bash-pattern-quoting discipline; relevant when REPO_ROOT
could theoretically contain glob metacharacters (rare in practice but
correct-by-default).
… P2) Codex P2: original loop used '$RESEARCH_DIR/*.md' (single-level glob), but the script's documented scope is 'docs/research/**' (recursive). docs/research/claims/ exists today and any courier-ferry doc placed in a subdirectory would bypass the lint. Fix: replaced shopt-glob loop with 'find -type f -name *.md -print0' piped via 'while read -d ""' for null-terminated path safety. Now matches the documented scope. Smoke-test on main: lint now finds 36 violations (was 26 with the single-level glob), confirming subdirectories are scanned. Includes docs/research/claims/ subdirectory paths in the discovery. Composes with prior Codex P2 fix (SC2295 quote in pattern expansion) to keep this lint shellcheck-clean as it ships.
6d74cc6 to
b2091d9
Compare
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
…nt regex + role-ref filename patterns + accurate docstring + B-0036 composes_with cleanup
P0 (Copilot) — content-signal regex was too broad (matched 'chatgpt' /
'google search ai' alone), false-positive on internal research docs
that merely mention external systems. Lint flagged 36 docs (10 of which
were false positives).
Fix: narrowed content-signal regex to STRUCTURAL phrases only —
'courier.ferry', 'external conversation', 'external collaborator',
'external research agent', 'courier-ferry capture'. Mere mentions
of system names ('chatgpt', 'google search ai') no longer trigger.
Lint now flags 19 docs (was 36) — confirms 17 false positives were
removed; the 19 remaining are real courier-ferry imports per
manual inspection.
Also tightened scan window to first-20 lines (was first-200) — the
§33 header region is the only relevant scope.
P1 (Copilot) — code embedded contributor first-names in filename and
content patterns ('via Aaron' / 'amara-via' / 'aaron-share') per the
'No name attribution in code, docs, or skills' rule.
Fix: replaced name-strings with structural role-ref patterns —
filename: 'courier-ferry|cross-substrate|external-import|cross-ferry';
content: structural phrases only. Lint now uses no personal names
in either filename or content matching.
P1 (Copilot) — 'reports the first failing file' docstring did not
match the implementation (which reports every violating file).
Fix: rewrote docstring to accurately describe multi-violation
reporting + summary, with explicit rationale (agents fix-all-at-once
instead of running lint repeatedly).
P1 (Copilot) — B-0036 composes_with referenced
'feedback_otto_229_tick_history_append_only_*' which is in personal
memory, not in-repo memory/.
Fix: replaced with 'GOVERNANCE.md-section-33-archive-header-discipline'
(the actual rule it composes with) + 'tools/hygiene/check-tick-history-
order.sh' (the in-repo template). Body still references Otto-229
conceptually as a discipline; that's not a broken-path concern.
P1 (Copilot, duplicate of Codex P2 already fixed in b2091d9) —
recursive walk via 'find -print0' instead of single-level glob.
Already shipped; this commit acknowledges the duplicate finding.
There was a problem hiding this comment.
Pull request overview
Adds a hygiene lint script to detect missing GOVERNANCE.md §33 archive-boundary headers on courier-ferry/external-conversation imports under docs/research/**, and introduces a P3 backlog row to track the follow-up work (backfill existing violations + wire the lint into CI).
Changes:
- Add
tools/hygiene/check-archive-header-section33.shto scandocs/research/**/*.mdand require the four §33 labels within the first 20 lines for matched courier-ferry imports. - Add
docs/backlog/P3/B-0036-...mdto track backfill + CI wiring as a dedicated hygiene initiative.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| tools/hygiene/check-archive-header-section33.sh | New lint script for §33 header presence on detected courier-ferry research imports. |
| docs/backlog/P3/B-0036-section33-archive-header-backfill-and-ci-wire-otto-346-pattern.md | Backlog row capturing the planned backfill + CI wiring workstream. |
| is_courier_ferry_import() { | ||
| local file="$1" | ||
| # Filename signals — structural markers only (no personal names) | ||
| if [[ "$file" =~ courier-ferry|cross-substrate|external-import|cross-ferry ]]; then |
| violations=0 | ||
| violation_files=() | ||
|
|
| # - Reports every failing file with a per-file diagnostic line, then | ||
| # a summary line with the total count. Multi-violation reporting is | ||
| # intentional: agents can fix all violations in a single pass instead | ||
| # of running the lint repeatedly to discover them serially. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 11e9528a5a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| header_region=$(head -20 "$file") | ||
| missing=() | ||
| for label in "${required_labels[@]}"; do | ||
| if ! echo "$header_region" | grep -qF "$label"; then |
There was a problem hiding this comment.
Match §33 labels as raw line prefixes
The current check uses grep -qF "$label" against the header block, so any line that merely contains the substring (for example **Scope:** or prose/code snippets containing Scope:) is accepted. This contradicts the stated requirement that labels be in literal non-bold form and lets formatting drift bypass the lint, so a file can pass CI while still violating the intended §33 header shape.
Useful? React with 👍 / 👎.
…y research docs (#572) * backfill(B-0036 partial): §33 archive headers on 7 Amara-courier-ferry research docs (lint count 19 → 12) Partial backfill of B-0036 Sub-task 1 (§33 archive header backfill on pre-existing courier-ferry research docs). This commit covers the 7 docs authored in THIS session that landed before the §33 lint tool shipped (PR #571 in flight): 5 docs had bold-styled `**Scope**:` headers (PRs landed before #570 P0 finding established the literal-form-only convention): - aurora-civilization-scale-substrate (PR #568) - aurora-immune-system-zero-trust-danger-theory (PR #569) - maji-messiah-spectre-aperiodic-monotile (PR #562) - superfluid-ai-language-gravity-austrian-economics (PR #566) - superfluid-ai-rigorous-mathematical-formalization (PR #563) Fix: stripped bold styling — `**Scope**:` → `Scope:` etc. for all 4 labels in lines 1-20. Mechanical sed-pass; no content change. 2 docs had no §33 header at all (pre-§33-lint authoring): - maji-formal-operational-model (PR #555 — earliest in lineage) - superfluid-ai-github-funding-survival-bayesian (PR #565) Fix: prepended full 4-field §33 header block per the canonical pattern established in #570 P0 finding (literal-label form, NOT bold-styled). Lint result: 19 violations → 12 violations on this branch. The remaining 12 are pre-existing courier-ferry docs from PRIOR sessions — those land in a separate dedicated PR (B-0036 Sub-task 1 continuation). Composes with PR #571 (the §33 lint tool itself); the lint enforcement becomes effective once both #571 lands AND the residual 12 are backfilled (B-0036 Sub-task 2 wires to CI gate.yml). * fix(B-0036 partial): normalize Operational-status to GOVERNANCE.md §33 enum form (Codex P2) Codex P2 finding (#572): GOVERNANCE.md §33 lines 777-780 define 'Operational status:' as an enum (research-grade or operational), not free-form text. The headers I added/touched used elaborated free-form values ('research-grade specification with implementation-ready type signatures + test specs...'), which leaves the document semantically non-compliant and would fail value-validation tooling. Fix: normalized 9 docs to the form 'Operational status: research-grade. <elaboration sentence>.' where the value strictly starts with the enum token + period, and elaboration is a separate sentence within the same field. Pattern for each doc: before: Operational status: research-grade <free-form-elaboration> after: Operational status: research-grade. <Elaboration> Docs normalized: - agent-wallet-protocol-stack-x402-eip7702-erc8004 - aurora-canonical-math-refactor-attack-absorption-theorem - aurora-civilization-scale-substrate-pouw-cc - aurora-immune-system-zero-trust-danger-theory - maji-formal-operational-model - maji-messiah-spectre-aperiodic-monotile - superfluid-ai-github-funding-survival-bayesian-belief-propagation - superfluid-ai-language-gravity-austrian-economics - superfluid-ai-rigorous-mathematical-formalization Composes with: PR #572's bold-strip work (this session's 7-doc backfill); PR #573's Shape A bold-strip on pre-existing docs (continuing partial backfill of B-0036 Sub-task 1). Future B-0036 follow-up: lint tool may want to validate Operational- status VALUE (not just label presence) — add 'research-grade' or 'operational' enum check to check-archive-header-section33.sh. * fix(B-0036): tighten Operational status to STRICT enum-only form (Codex P2 doubling-down) Codex P2 (#572 latest review): the previous fix ('research-grade. <Elaboration>') still keeps elaboration in the field value, which violates §33's enum-only specification. The strict form is just the enum token: 'research-grade' or 'operational' — nothing else. Fix: truncated 9 docs to 'Operational status: research-grade' (no period, no elaboration). Implementation/status notes that previously appended to the value are removed from the §33 field; they remain visible in the doc body where appropriate. This is the right shape per GOVERNANCE.md §33 lines 777-780 strict reading: 'one of research-grade ... or operational ...' — the value IS one of the two tokens, not a token-with-prose. Composes with the bold-strip work in this PR + #573. The pattern emerging across Codex review: §33 has TWO disciplines — format (literal-label, no bold-style) AND value (enum-only, no elaboration). Both now satisfied for the 9 docs touched here. Future B-0036 follow-up (already noted in B-0036 row): lint tool should validate Operational-status VALUE (not just label presence). The §33 discipline now has a clearly defined acceptance criterion: line matches '^Operational status: (research-grade|operational)$'.
… generative-pivot tick (#574) Tick row capturing the 1.5-hour autonomous-drain segment since 06:48Z framework-convergence tick: - 13 PRs merged (full 11-Amara-refinement lineage now on main + §33 lint substrate-primitive + Shape A bold-strip backfill) - 8 code-fix PRs merged (tick-history canonical sort fix + markdown- md032/md026 fenced-code-block prevention + 6 review-thread drains) - §33 archive header lint tool shipped (PR #571) + B-0036 backlog row + partial-1 backfill (#572 in flight) + Shape A bold-strip (#573 merged) - Calibration finding: lint flags 6 docs because Non-fusion disclaimer lands past line 20; three resolution paths in B-0036 deferred - Recursive review-finding refinement observed across #572 reviews: Codex iteratively tightened enum-strict interpretation of Operational status field Queue-drain is essentially complete modulo #200 (34-thread legacy, deferred). 5 substrate primitives shipped this session each from a distinct recurring-review-finding pattern. Per check-tick-history-order: 133 rows in non-decreasing chronological order.
…ce:]] + anchored label match + diagnostic wording Three #575 review findings: P0 (Copilot) — '\\s*' is NOT POSIX ERE; with grep -E, '\\s' matches a literal 's' (the regex \\s* would match zero-or-more 's' characters, not whitespace). This makes trailing-whitespace tolerance ineffective AND can accidentally accept strings ending in 's' (e.g. 'research-grades'). Fix: replaced '\\s*' with portable POSIX class '[[:space:]]*'. Verified: trailing-whitespace tolerated; 'research-grades' correctly rejected. P1 (Copilot) — label-presence check used 'grep -qF' (fixed-string, matches mid-line) but value check used '^Operational status:' (start-of-line anchor). Mismatch: label-presence accepted '- Operational status:' (mid-list-item) as compliant while value check would skip it. Fix: changed label-presence to 'grep -qE \"^\$label\"' (anchored ERE). Now both checks use the same start-of-line anchoring. Side-effect: violation count went 18 → 19 because at least one doc had a §33 label mid-line that the old fixed-string check inappropriately accepted. The anchor change strengthens discipline. P2 (Copilot) — diagnostic text used 'Operational-status' (hyphen) but actual label is 'Operational status:' (space). Confusing for grep- based searching. Fix: aligned wording — diagnostic now says \"'Operational status:' value not enum-strict\" matching the literal label. Composes with the #571/#575 substrate-primitive lifecycle: the substrate primitive matures via review-driven correctness-tightening, not via design-by-perfection. Each round shaves a discipline-shape sharper.
…m value (Codex P2 follow-up) (#575) * feat(check-archive-header-section33): validate Operational-status enum value (Codex P2 follow-up) Tightens the §33 lint to validate Operational-status VALUE per GOVERNANCE.md §33 lines 777-780 (strict enum: 'research-grade' or 'operational', nothing else). Codex P2 finding (PR #572 review chain) caught the value-discipline manually each time a free-form value like 'research-grade specification with implementation-ready type signatures...' shipped. Per Otto-346 (recurring review-finding → substrate primitive), the lint should catch it pre-merge. What this adds: - After the missing-label scan, a per-file value check on the Operational-status line - Strict regex: ^Operational status: (research-grade|operational)\s*$ - Trailing whitespace tolerated (markdownlint may strip) - Anything else (free-form, period+elaboration, bold-styling) flagged - Two independent failure modes per file: missing-label (Set A) + bad-value (Set B). Either failing increments violation count once per file, but both diagnostic lines emit if both fail. Smoke-test on main: lint now flags 12 unique files (was 12 with label-only check; same files but with additional value-discipline violations). 6 of the 12 docs that had bold-stripped labels via #573 ALSO have free-form Operational-status values; this commit catches both gaps. Acceptance criterion (formerly latent, now codified): Operational-status line must match exactly: '^Operational status: (research-grade|operational)\s*$' Composes with: - The PR #572 chain that established the strict-enum discipline via iterative Codex review - Otto-346 (recurring inline pattern → substrate primitive) - Otto-341 (mechanism over vigilance) - B-0036 backlog row (already noted this enhancement as a follow-up in the Test Plan section) * fix(check-archive-header-section33): 3 review findings — POSIX [[:space:]] + anchored label match + diagnostic wording Three #575 review findings: P0 (Copilot) — '\\s*' is NOT POSIX ERE; with grep -E, '\\s' matches a literal 's' (the regex \\s* would match zero-or-more 's' characters, not whitespace). This makes trailing-whitespace tolerance ineffective AND can accidentally accept strings ending in 's' (e.g. 'research-grades'). Fix: replaced '\\s*' with portable POSIX class '[[:space:]]*'. Verified: trailing-whitespace tolerated; 'research-grades' correctly rejected. P1 (Copilot) — label-presence check used 'grep -qF' (fixed-string, matches mid-line) but value check used '^Operational status:' (start-of-line anchor). Mismatch: label-presence accepted '- Operational status:' (mid-list-item) as compliant while value check would skip it. Fix: changed label-presence to 'grep -qE \"^\$label\"' (anchored ERE). Now both checks use the same start-of-line anchoring. Side-effect: violation count went 18 → 19 because at least one doc had a §33 label mid-line that the old fixed-string check inappropriately accepted. The anchor change strengthens discipline. P2 (Copilot) — diagnostic text used 'Operational-status' (hyphen) but actual label is 'Operational status:' (space). Confusing for grep- based searching. Fix: aligned wording — diagnostic now says \"'Operational status:' value not enum-strict\" matching the literal label. Composes with the #571/#575 substrate-primitive lifecycle: the substrate primitive matures via review-driven correctness-tightening, not via design-by-perfection. Each round shaves a discipline-shape sharper.
…estone tick (#581) Tick row capturing B-0036 Sub-task 1 completion: lint count 36 → 0 on main. The full §33-archive-header substrate-primitive lifecycle from recurring-review-finding-pattern to operational-CI-enforcement landed this segment of the autonomous-loop run. Highlights: - 6-PR backfill chain: #572/#573/#576/#577/#578/#579 - Lint enhancements: #571 (initial) + #575 (enum-value validation) - Lint progression: 36 → 19 → 12 → 9 → 4 → 1 → 0 - B-0036 Sub-task 2 (CI wire) opened as PR #580; auto-merge enabled - Aaron returned from break this tick Three observations captured: 1. Otto-346 substrate-primitive pattern proven end-to-end on a single discipline within one session 2. Discipline-correctness over rule-relaxation (path a/b/c choice) 3. Autonomous-loop sustained substantive output for ~hour-long quiet window per never-be-idle priority ladder Per check-tick-history-order: 134 rows in non-decreasing chronological order.
…I lint (B-0036 Sub-task 2) (#580) * feat(gate.yml): wire check-archive-header-section33.sh as enforcing CI lint job (B-0036 Sub-task 2) Adds 'lint (archive header §33)' as a new gate.yml lint job alongside existing lint-tick-history-order, lint-no-conflict-markers, lint-no-empty-dirs, lint-markdown. Now any future courier-ferry / external-conversation import under docs/research/** will: - FAIL CI on missing §33 4-field archive header in lines 1-20 - FAIL CI on Operational-status value not in enum {research-grade, operational} - BLOCK MERGE per branch protection's required-status-checks This is B-0036 Sub-task 2 — Sub-task 1 (backfill) was completed via PR #572/#573/#576/#577/#578/#579 reducing pre-existing violations from 36 → 0 on main. The substrate-primitive lifecycle is now operational: - Otto-346 recurring-pattern observed: §33 retrofitted post-review on 9+ PRs in the 11-Amara-refinement lineage - PR #571 shipped lint tool (label-presence) - PR #575 enhanced lint to validate enum-value (Operational status) - 6-PR backfill chain cleared all pre-existing violations - THIS PR: enforcing CI gate Composes with: - check-tick-history-order.sh (same Otto-346 substrate-primitive template — recurring discipline-violation → CI lint) - check-no-conflict-markers.sh (same template; the 3 lint scripts now form a consistent §33-discipline enforcement triple) - B-0036 backlog row (Sub-task 2 satisfied; row can close once this lands) Future operator note: if a legitimate courier-ferry doc lands and this lint flags a false-positive, two fixes available: (a) add §33 header (most common; 9 in 9 review-finding cases this session were legit § missing) (b) refine the courier-ferry-import detection regex in the script (rare; only if the doc isn't actually external-conversation) * ci(gate.yml #580 thread): role-refs replace name attribution per AGENT-BEST-PRACTICES Per Copilot P1 on #580: workflow YAML comments are current-state operational surfaces; AGENT-BEST-PRACTICES rule 'No name attribution in code, docs, or skills' requires role-refs not first names. Replacements (4 occurrences): - 'Aaron 2026-04-26 asked' → 'Maintainer 2026-04-26 asked' (line 328) - 'Aaron 2026-04-26 ask:' → 'Maintainer 2026-04-26 ask:' (line 349) - 'Otto observation 2026-04-26:' → 'Factory observation 2026-04-26:' (line 376) - '11-Amara-refinement courier-ferry lineage' → '11-refinement courier-ferry lineage' (line 377) Per Otto-279 history-surface carve-out: names ALLOWED in research / ROUND-HISTORY / ADRs / aurora archive (history surfaces), preferred role-refs in code / skills / workflow YAML / current-state docs. Workflow YAML is current-state surface. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Summary
GOVERNANCE.md §33 archive-header missing was the most-common review finding across the 11-Amara-refinement courier-ferry lineage this session (PRs #560 / #562 / #563 / #565 / #566 / #568 / #569 / #570 / #553 each retrofitted post-review).
Per Otto-346 (recurring pattern → substrate primitive missing) + Otto-341 (mechanism over vigilance), the fix is a CI lint.
What this PR ships
tools/hygiene/check-archive-header-section33.sh— the lint tooldocs/backlog/P3/B-0036-...md— backlog row tracking the two follow-up sub-tasks (backfill + CI wire)What this PR does NOT ship
docs/research/**Tool behavior
docs/research/**.mdfor courier-ferry / external-conversation imports (filename or content patterns)**Scope**:form REJECTED per research(aurora-canonical-math): Amara tenth refinement — canonical-math refactor + attack-absorption theorem; Qubic empirical grounding #570 P0 findingSmoke-test result
Found 26 pre-existing violations on
main— confirms the substrate-debt is real. Backfill is the dedicated PR scope (B-0036 Sub-task 1).Composition
check-tick-history-order.sh(recurring discipline-violation → CI lint as fix)Test plan
main— finds 26 pre-existing violations (expected)courier-ferry,via Aaron,external conversationetc.)Why P3
Examples for backfill
See PR #570 / #566 / #563 §33-header fixes for the canonical 4-field header form.