Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5c1e982c2d
ℹ️ 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 new hygiene audit to detect the markdownlint MD032 regression pattern where a prose continuation line begins with + , and documents this new audit as FACTORY-HYGIENE row #56.
Changes:
- Added
tools/hygiene/audit-md032-plus-linestart.shwith--listand--enforcemodes to scan tracked markdown for risky+line-start usage. - Registered the new audit in
docs/FACTORY-HYGIENE.mdas row #56 with cadence/ownership/output details.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| tools/hygiene/audit-md032-plus-linestart.sh | New bash audit script to detect + -at-line-start MD032 triggers. |
| docs/FACTORY-HYGIENE.md | Adds FACTORY-HYGIENE row #56 documenting the new MD032 preflight audit. |
AceHack
added a commit
that referenced
this pull request
Apr 23, 2026
…MD032 fixes + #201 merged #201 MERGED at 21:35:39Z — Craft module 2 (retraction- intuition) canonical on main. MD038 fix on #204: trailing spaces in code spans. MD032 fix on #203: blank lines around Prerequisites list. Aaron Zora-UX directive absorbed: *'The user experience I am hoping from from Frontier is basically the StarTrek computer but better lol, more personality like the named agents ... more like Zora which is cool since we have Zeta lol. Research UX based on this evolution of the StarTrek computer backlog'*. Filed per-user memory with Zora's Discovery S2-S5 + Calypso evolution arc + 6-axis Star-Trek-baseline-vs- Frontier-target comparison + 5 composition cross-refs (named personas / CONFLICT-RESOLUTION / Common Sense 2.0 safety floor / succession purpose / existential-dread- resistance). BACKLOG P2 row filed: 'Frontier UX research — Star Trek computer but BETTER (Zora-style)'. Owner: Iris + Kai + Kenji + Otto-coordination. Effort L. Zora-UX validates the named-persona roster as load- bearing (not ornamental). 17 persona-agent-files + tone contracts ARE the personality substrate to surface. Zeta/Zora naming resonance noted (Aaron-identified). Otto-session at 5 consecutive substrate-producing ticks (Otto-39 Craft#2 + Otto-40 seed-truth + Otto-41 Craft#3 + Otto-42 hygiene#56 + Otto-43 Zora-UX). Attribution: Otto (loop-agent PM hat). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
AceHack
added a commit
that referenced
this pull request
Apr 23, 2026
…tool keeps paying Hardened tool (Otto-36) applied across session-blocked Phase-1 PRs: - #199: 4 drained (1 dangling + 3 name-attribution) - #200: 1 drained (name-attribution) - #202: 1 drained (name-attribution) - #203: 2 drained (dangling-ref) - #204: 1 drained (name-attribution) - #205: 0 unresolved (mergeStateStatus transient) 9 threads in ~30 seconds. Remaining ~45 are substantive content-review work; tool has drained the mechanizable floor. Phase-1 queue now in 'threads-drained-to-mechanizable- floor' state across 6 PRs. Long-tail self-drain strategy holding — cost-benefit tips toward accepting tail + letting bot-review cycles settle. Tool-hardening investment from Otto-30 compounds in value across each cadenced application. Attribution: Otto (loop-agent PM hat). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 98d10e27c5
ℹ️ 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 new hygiene preflight audit to catch the markdownlint MD032 regression pattern where + starts a prose-continuation line and is misparsed as a list item.
Changes:
- Introduces
tools/hygiene/audit-md032-plus-linestart.shwith--listand--enforcemodes to detect risky+-at-line-start usage in tracked Markdown files. - Registers FACTORY-HYGIENE row #56 documenting the new audit, intended cadence, baseline, and durable output surface.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| tools/hygiene/audit-md032-plus-linestart.sh | New detect/enforce script to locate MD032-triggering + prose-continuation lines. |
| docs/FACTORY-HYGIENE.md | Adds row #56 documenting the MD032 preflight audit and its operating procedure. |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
There was a problem hiding this comment.
Pull request overview
Adds a new hygiene preflight to detect the recurring markdownlint MD032 failure mode where prose continuation lines begin with + , and registers the audit as FACTORY-HYGIENE row #56.
Changes:
- Introduces
tools/hygiene/audit-md032-plus-linestart.shwith--listand--enforcemodes to locate risky+-at-line-start patterns. - Documents the new audit in
docs/FACTORY-HYGIENE.mdas row #56, including cadence/ownership/output wiring.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| tools/hygiene/audit-md032-plus-linestart.sh | New detection script for + -at-line-start MD032 regressions. |
| docs/FACTORY-HYGIENE.md | Adds row #56 documenting the new MD032 preflight audit. |
This was referenced Apr 23, 2026
AceHack
added a commit
that referenced
this pull request
Apr 23, 2026
…action item #1) (#220) Amara's 2026-04-23 decision-proxy + technical review courier (PR #219) ranked memory-index-integrity CI as her highest-value immediate fix: directly prevents the NSA-001 measured failure mode (new memory landed without MEMORY.md pointer → undiscoverable from fresh session). New workflow: `.github/workflows/memory-index-integrity.yml` Check: if a PR (or push to main) adds or modifies any top-level `memory/*.md` file, `memory/MEMORY.md` MUST also be in the same range. Fails with an explicit remediation message citing NSA-001. Scope excludes: - memory/persona/** (per-persona notebooks have their own lifecycle) - memory/README.md (convention doc) - memory/MEMORY.md (the index itself) - Deletions (covered from the other direction by FACTORY- HYGIENE row #25 pointer-integrity audit) Safe-pattern compliant per FACTORY-HYGIENE row #43: - actions/checkout@de0fac2... SHA-pinned - Explicit minimum `permissions: contents: read` - Only first-party trusted context (github.sha, github.event.pull_ request.base.sha, github.event.before) passed via env: - No user-authored context referenced anywhere - concurrency group + cancel-in-progress: false - runs-on: ubuntu-22.04 pinned - actionlint clean; shellcheck clean (SC2086 fixed) FACTORY-HYGIENE row #58 added documenting the cadence / owner / scope / durable output + classification (row #47: prevention- bearing — blocks merge before substrate diverges from index). Row numbered 58 to leave #56 reserved for in-flight PR #204 (MD032 preflight) and #57 for in-flight PR #213 (git-hotspots audit). Ships to project-under-construction: adopters inherit the workflow unchanged; the memory/**.md + memory/MEMORY.md conventions are factory-generic. Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new factory hygiene preflight audit to detect the recurring markdownlint MD032 failure mode where prose continuation lines start with + and get misparsed as list items.
Changes:
- Introduce
tools/hygiene/audit-md032-plus-linestart.shwith--listand--enforcemodes to find risky+line starts. - Document the new audit as FACTORY-HYGIENE row #56, including intended exclusions and cadence.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| tools/hygiene/audit-md032-plus-linestart.sh | New bash audit script that scans tracked Markdown files for MD032-risk + line-start patterns. |
| docs/FACTORY-HYGIENE.md | Adds FACTORY-HYGIENE row #56 describing the new MD032 preflight audit. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d9023b8c01
ℹ️ 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.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e14c43671d
ℹ️ 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".
AceHack
added a commit
that referenced
this pull request
Apr 24, 2026
…E row #57) Directly executes Aaron Otto-54's git-hotspots cadence directive from the four-message directive cluster in PR #212 BACKLOG row. This PR closes the gap between "BACKLOG row naming the cadence" and "audit tool + first baseline report + FACTORY-HYGIENE row activating it". New artifacts: - `tools/hygiene/audit-git-hotspots.sh` — bash script running `git log --since --name-only` over a configurable window, ranking top-N, enriching with unique-author + PR-count, excluding legitimately-by-design hotspots (hygiene-history, openspec/changes, references/upstreams). Supports `--window`, `--top`, `--report`. Detect-only (exit 0); action is judgment call. - `docs/hygiene-history/git-hotspots-2026-04-23.md` — first-run baseline report over 30 days. Finding: `docs/BACKLOG.md` is top hotspot at 34 touches / 26 PRs (one touch per PR opened) — validates Aaron's Otto-54 intuition that BACKLOG split is the highest-leverage move. Otto observations appended with per-file action recommendations (1 split / 1 freeze-then-watch / 1 cadence / 5 audit / 11 watch). - FACTORY-HYGIENE row #57 activating the cadenced sweep. Cross-refs the BACKLOG row and the companion memory. Row number is 57 (not 56) to leave #56 reserved for the MD032 preflight that's in-flight on PR #204. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
AceHack
added a commit
that referenced
this pull request
Apr 24, 2026
…#57) (#213) * hygiene: git-hotspots audit tool + first-run baseline (FACTORY-HYGIENE row #57) Directly executes Aaron Otto-54's git-hotspots cadence directive from the four-message directive cluster in PR #212 BACKLOG row. This PR closes the gap between "BACKLOG row naming the cadence" and "audit tool + first baseline report + FACTORY-HYGIENE row activating it". New artifacts: - `tools/hygiene/audit-git-hotspots.sh` — bash script running `git log --since --name-only` over a configurable window, ranking top-N, enriching with unique-author + PR-count, excluding legitimately-by-design hotspots (hygiene-history, openspec/changes, references/upstreams). Supports `--window`, `--top`, `--report`. Detect-only (exit 0); action is judgment call. - `docs/hygiene-history/git-hotspots-2026-04-23.md` — first-run baseline report over 30 days. Finding: `docs/BACKLOG.md` is top hotspot at 34 touches / 26 PRs (one touch per PR opened) — validates Aaron's Otto-54 intuition that BACKLOG split is the highest-leverage move. Otto observations appended with per-file action recommendations (1 split / 1 freeze-then-watch / 1 cadence / 5 audit / 11 watch). - FACTORY-HYGIENE row #57 activating the cadenced sweep. Cross-refs the BACKLOG row and the companion memory. Row number is 57 (not 56) to leave #56 reserved for the MD032 preflight that's in-flight on PR #204. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(#213): address 9 Codex/Copilot findings — script bugs + policy-nuanced name attribution 7 real findings addressed in this commit. 2 findings need policy pushback, captured in thread responses. CODEX P1 — empty window aborts under set -euo pipefail: `grep -v '^$'` returns exit code 1 when no matches → pipe aborts. Fixed by adding `|| true` guard + explicit empty-window message to stderr. CODEX P1 — PR count returns zero via grep silence: Same pattern. Replaced `wc -l | tr -d ' '` with `grep -c . || true` so the empty case yields 0 cleanly instead of aborting. COPILOT P1 — option parsing missing value handling: `shift 2` with missing arg produced confusing error. Added `require_value` helper that fails fast with "error: $1 requires a value" + exit 64. COPILOT P2 — --help shows shebang: `grep '^#'` included `#!/usr/bin/env bash`. Added `| grep -v '^#!'` filter. COPILOT P1 — "ignoring pure deletions" comment was wrong: `git log --name-only` lists deleted paths too. Fixed comment to state we DELIBERATELY include deletions (frequent deletion = friction too). COPILOT P1 — "Aaron" attribution on non-exempt surfaces: FACTORY-HYGIENE row #57 + script header comment rewrote references to "the human maintainer" (role). Verbatim quote block in script header preserved as attribution (with inline note explaining the distinction). FACTORY-HYGIENE.md is NOT in the history-file exempt list per the policy clarification being landed in PR #210. COPILOT P1 — dangling memory path citation: FACTORY-HYGIENE row #57 cited `memory/project_factory_is_git_native_...` as if in-repo; actually per-user memory. Added explicit "**out-of-repo** (per-user memory, not yet in-repo)" marker. POLICY-PUSHBACK (not fixed — thread response): COPILOT P1 — "Otto observations" + "Aaron" in baseline report: The report lives at `docs/hygiene-history/git-hotspots-2026-04-23.md` which IS in the history-file exempt list per the Otto-52 policy clarification (*"'No name attribution in code, docs, or skills' in history files are files like memory backlog and other things like that for historical purposes"*). Naming the author "Otto" in observation attribution is attribution-line form, which the exemption preserves. Not fixing; will explain in thread reply. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(#213): address 7 remaining review findings + restore FACTORY-HYGIENE row 57 Rebase onto main used -X ours for audit-trail (FACTORY-HYGIENE.md is append-only) which dropped our new row 57. Restored it in this commit with the latest post-feedback text (human-maintainer role reference + out-of-repo memory marker, matching state at branch head before rebase). Script fixes: - Remove "Aaron" from header aside; use role reference, keep verbatim quote attribution as before (narrow attribution exemption). - Validate --top is a positive integer; exit 64 with clear message. - Guard with git rev-parse --is-inside-work-tree; replace main-pipeline 'grep -v || true' with 'sed /^$/d' so git-log failures propagate instead of being masked. - file_summary: capture git-log output without stderr suppression or '|| true'; count lines via wc -l; restrict PR-count to trailing '(#NNN)' squash-merge markers so 'row #58' / 'fix #213' tokens no longer inflate the metric. - render: replace 'head -n $top' pipeline with counter + while-read so SIGPIPE 141 cannot surface on large ranked lists. - render: replace awk $1-strip with sed regex so filenames with internal whitespace are preserved exactly. Smoke-tested --window 7d/0d, invalid --top, missing --window value. --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
AceHack
added a commit
that referenced
this pull request
Apr 24, 2026
…n fixes (PR #204 threads) Addresses 19 unresolved review threads on PR #204 clustered into six distinct issues — consolidated into a single cohesive rewrite: * NUL-delimited `git ls-files -z | while read -d ''` iteration (whitespace-safe paths; matches sibling hygiene-script convention). * `cd "$(git rev-parse --show-toplevel)"` first so paths resolve from repo root regardless of $PWD. * Previous-line blank check strips all whitespace (spaces, tabs, CR) via `${var//[[:space:]]/}` — tab-only predecessors count as blank. * Contiguous `+ `-list detection: if the previous line is itself a `^ {0,3}\+ ` marker line, it's list continuation, not a gap. * CommonMark-compliant pattern `^ {0,3}\+ ` — up to 3 leading spaces allowed on `+ `-marker lines (indented `+` in header example now matched). * `plus_lines_count >= 3` file-level skip heuristic removed — per-line contiguous-list detection makes it unnecessary and was masking false negatives (file could mostly use `+` as list marker while still containing a stray prose-continuation `+`). * Post-setup stack header added to match sibling convention. * Portability: `while read`-based file load instead of `mapfile` (macOS bash 3.2 parity). FACTORY-HYGIENE.md row #56 description updated to match the new behaviour (pre-merge refinement of the new row, permitted under append-only audit-trail discipline). Build: 0W/0E. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
AceHack
force-pushed
the
hygiene/markdownlint-plus-at-line-start-preflight
branch
from
e14c436 to
ff3c736
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ff3c736940
ℹ️ 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 preflight audit to detect markdown lines that start with + in contexts that trigger markdownlint MD032 (list items not surrounded by blank lines), and documents it as FACTORY-HYGIENE row #56.
Changes:
- Added
tools/hygiene/audit-md032-plus-linestart.sh(detect-only with--list/--enforcemodes). - Added FACTORY-HYGIENE row #56 describing the audit and its intended cadence/ownership.
- (Unrelated) Removed FACTORY-HYGIENE rows #57 and #60 from
docs/FACTORY-HYGIENE.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| tools/hygiene/audit-md032-plus-linestart.sh | New bash audit that scans tracked markdown files for MD032-risk + line starts. |
| docs/FACTORY-HYGIENE.md | Adds row #56 documenting the new audit (and also deletes rows #57/#60). |
…56) Addresses recurring MD032 regression hit 3 times in Otto-session (Otto-35 + Otto-38 + Otto-38 again). Pattern: author writes prose continuation like Full treatment in the DBSP paper + docs/ARCHITECTURE.md §operator-algebra. and markdownlint parses the '+ ' as a list item, firing MD032 (list not surrounded by blank lines). Tool: tools/hygiene/audit-md032-plus-linestart.sh — scans tracked .md files for '^+ ' with non-blank previous line. Skips files using '+ ' consistently as bullet style (3+ occurrences). --list / --enforce modes per row #55 pattern. Baseline at first fire: 3 pre-existing gaps in persona notebooks (memory/persona/best-practices- scratch.md, ilyana/NOTEBOOK.md, kenji/OFFTIME.md). Detect-only; enforce-transition deferred. FACTORY-HYGIENE row #56 lands with full schema per row #55 pattern. Classified prevention-bearing (row #47 taxonomy). Attribution: Otto (loop-agent PM hat). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replaced '`+ `' + '`^+ `' with '`+` followed by space' +
'`^+` (plus-at-line-start followed by space)' to remove
trailing spaces inside code spans.
Markdownlint MD038 rule forbids leading/trailing spaces in
code spans. The semantic meaning ('+' followed by space
character) is now in prose.
Attribution: Otto (loop-agent PM hat).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…n fixes (PR #204 threads) Addresses 19 unresolved review threads on PR #204 clustered into six distinct issues — consolidated into a single cohesive rewrite: * NUL-delimited `git ls-files -z | while read -d ''` iteration (whitespace-safe paths; matches sibling hygiene-script convention). * `cd "$(git rev-parse --show-toplevel)"` first so paths resolve from repo root regardless of $PWD. * Previous-line blank check strips all whitespace (spaces, tabs, CR) via `${var//[[:space:]]/}` — tab-only predecessors count as blank. * Contiguous `+ `-list detection: if the previous line is itself a `^ {0,3}\+ ` marker line, it's list continuation, not a gap. * CommonMark-compliant pattern `^ {0,3}\+ ` — up to 3 leading spaces allowed on `+ `-marker lines (indented `+` in header example now matched). * `plus_lines_count >= 3` file-level skip heuristic removed — per-line contiguous-list detection makes it unnecessary and was masking false negatives (file could mostly use `+` as list marker while still containing a stray prose-continuation `+`). * Post-setup stack header added to match sibling convention. * Portability: `while read`-based file load instead of `mapfile` (macOS bash 3.2 parity). FACTORY-HYGIENE.md row #56 description updated to match the new behaviour (pre-merge refinement of the new row, permitted under append-only audit-trail discipline). Build: 0W/0E. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Line 102 in docs/FACTORY-HYGIENE.md triggered 11 MD038
(no-space-in-code) warnings and 1 MD056 (table-column-count)
warning. Rewrote the row text to:
- Replace code-span literals that started or ended with a
space (`+ `, `^ {0,3}\+ `, `. Excludes: `, `, `, `; `, etc)
with prose phrasings that keep the meaning without the
MD038-tripping whitespace inside backticks.
- Split the `git ls-files -z | while read -d ''` code span
into two separate spans so the `|` does not land inside a
code-span in a table cell (markdownlint-cli2 was counting
it as a ninth column against the 8-column header).
No semantic change to the hygiene rule itself; no changes to
tools/hygiene/audit-md032-plus-linestart.sh. Full repo
markdownlint-cli2@0.18.1 run is clean; dotnet build -c Release
is 0W/0E.
AceHack
force-pushed
the
hygiene/markdownlint-plus-at-line-start-preflight
branch
from
ff3c736 to
ea506db
Compare
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Copilot caught that audit-memory-references.sh doesn't use `git ls-files -z` iteration (it parses a single target file). Replace with audit-post-setup-script-stack.sh which does use the NUL-delimited pattern. No behaviour change; comment only. Addresses PR #204 Copilot review thread on line 82.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b2e3d0f304
ℹ️ 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".
Comment on lines
+104
to
+106
| # Candidate: `^ {0,3}\+ ` anywhere in the file. | ||
| if [[ ! "$line" =~ $plus_marker_re ]]; then | ||
| continue |
There was a problem hiding this comment.
Track fenced-code state before treating ^ {0,3}\+ as a candidate, otherwise valid code/math snippets are reported as gaps. In this commit, running tools/hygiene/audit-md032-plus-linestart.sh --list flags docs/aurora/2026-04-23-amara-aurora-aligned-ksk-design-7th-ferry.md:446, which is inside a triple-backtick block (+ β₁(1-P(c))). Markdownlint MD032 does not evaluate list spacing inside fenced code, so this creates false positives and will make --enforce block clean markdown once enforcement is enabled.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Adds a hygiene preflight to detect the specific markdown pattern where a prose-continuation line begins with + (which markdownlint MD032 can misparse as a list item), aiming to prevent recurring CI lint regressions.
Changes:
- Introduces
tools/hygiene/audit-md032-plus-linestart.shwith--listand--enforcemodes to detect+-at-line-start “gap” patterns. - Documents the new audit as FACTORY-HYGIENE row #56.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| tools/hygiene/audit-md032-plus-linestart.sh | New bash audit script to detect MD032-triggering + prose continuations. |
| docs/FACTORY-HYGIENE.md | Adds a new hygiene row describing the MD032 preflight audit and its intended cadence/output. |
| | 55 | Machine-specific content scrubber (cadenced audit of in-repo tracked files for user-home paths, Claude Code harness paths, Windows user-profile paths, hostname leaks) | Detect-only (landed 2026-04-23); cadenced detection once per round-close (same cadence as rows #50 / #51 / #52 meta-audits) + opportunistic on-touch when a tick migrates per-user content to in-repo. Enforcement (`--enforce` exit-2) deferred until baseline is green. | Dejan (devops-engineer) on cadenced detection + CI-enforcement sign-off when baseline is green; the migrating agent (self-administered) on on-touch — every in-repo-first migration runs the audit before committing. | factory | `tools/hygiene/audit-machine-specific-content.sh` scans all tracked files (`git ls-files`) for machine-specific patterns: `/Users/<name>/`, `/home/<name>/`, `C:\Users\<name>`, `C:/Users/<name>`. Excludes: `docs/ROUND-HISTORY.md`, `docs/hygiene-history/**`, `docs/DECISIONS/**`, and the audit script itself. `--list` prints offending files; `--enforce` flips exit 2 on any gap. **Why this row exists:** Aaron 2026-04-23 Otto-27 — *"we can have a machine specific scrubber/lint hygene task for anyting that makes it in by default. just run on a cadence."* Following the Option D in-repo-first policy shift (per-user memory migrations to in-repo became the default), machine-specific content leakage becomes a real risk — content comfortably per-user now crosses the factory's public repo boundary. Baseline at first fire (2026-04-23) was 9 gaps: `/Users/` patterns in several SKILL.md files, 2 PDFs (metadata scan), a scratch-recon doc, a parallel-worktree research doc; `C:\Users\` pattern in 1 SKILL.md + `memory/feedback_path_hygiene.md` (anti-example reference — legitimate). **Classification (row #47):** **prevention-bearing** — the audit runs at author-time (on-touch during in-repo-first migrations) and surfaces the gap before it lands. Ships to project-under-construction: adopters inherit the audit + pattern list + exclusion-list discipline. | Audit output on each fire; cadenced runs appended to `docs/hygiene-history/machine-specific-content-audit-history.md` (per-fire schema per row #44 — date, agent, gaps count, files touched, actions taken, next-fire-expected-date); BACKLOG row per gap at triage time if cleanup doesn't fit on-touch. | `tools/hygiene/audit-machine-specific-content.sh` (detection + pattern list + exclusion list) + cross-refs: `memory/feedback_path_hygiene.md` + `memory/CURRENT-aaron.md` + `memory/CURRENT-amara.md` (in-repo-first migration boundary surfaces this audit's need) | | ||
| | 60 | Surface-map-drift smell (wrong URL on a mapped surface fires a hygiene alarm) | Pre-call: every `gh api <path>` (or equivalent platform call) on a surface that has a mapping doc — grep the map first, use its path, otherwise record a map-gap. Post-call: every 410 / 301 / "endpoint moved" response on a mapped endpoint auto-proposes a map-update. Cadenced sweep every 5-10 rounds replays the full set of mapped endpoints against the current platform to catch silent drift (endpoint renamed without 410). | Any agent calling `gh api` (self-administered on pre-call / post-call); Dejan (devops-engineer) on the cadenced sweep; Kenji (Architect) on map-update PRs when drift lands. Bounded to surfaces with a mapping doc under `docs/research/*surface-map*.md` / `docs/AGENT-*-SURFACES.md` / `docs/HARNESS-SURFACES.md` / `docs/GITHUB-SETTINGS.md`. | factory | **Pre-call (prevention-bearing):** before invoking any `gh api` call against org / enterprise / Copilot / billing / settings surfaces, `grep -li "<surface-keyword>" <mapping-docs>` and use the path the map lists. If the map lacks the path, **file a map-gap finding** in the same audit's output — agent may still call a best-guess endpoint if confident the surface exists, but must log the gap so the next round-close sweep extends the map. **Post-call (detection-bearing):** any `410 Gone` / `301 Moved Permanently` / `"endpoint moved"` response from a mapped endpoint triggers a map-update task (write the new path to the map; note old-path + redirect-doc + drift-date in a "Map drift log" section). **Cadenced (detection-bearing):** every 5-10 rounds, replay the full set of mapped endpoints against the current platform to catch silent renames (200 OK from a stale path that silently redirects, or 404 from an endpoint removed without deprecation). **Why this row exists:** Aaron 2026-04-22 after agent invented `/orgs/.../billing/budgets` (404) for LFG budget audit despite task #195 having already produced the complete map: *"i'm supprised you got the url wrong given you mapped it"* + *"that should be a smell when that happen to a surface you already have mapped"*. Same incident revealed a second drift class — `/orgs/{org}/settings/billing/actions` (map §A.17) returned 410 with `documentation_url: https://gh.io/billing-api-updates-org`, meaning GitHub moved the endpoint between 2026-04-22 (map author-time) and 2026-04-22 (this fire, hours later). Two orthogonal failure modes compound: (a) **not-consulting** an existing map (guess without grep), (b) **consulting-but-stale** map (correct path + platform drift). **UI-only surfaces** (e.g., GitHub org budget management at `https://github.com/organizations/{org}/billing/budgets`, no REST equivalent) are legitimate map entries — the map should mark them as `ui-only` so agents know "no API path exists" before trying. **Classification (row #47):** **prevention-bearing** — the pre-call grep discipline is the prevention layer; the post-call 410 handler is a complementary detection layer; the cadenced sweep is the insurance detection layer for silent renames. See `memory/feedback_surface_map_consultation_before_guessing_urls.md`. Ships to project-under-construction: adopters inherit the smell pattern + the pre-call grep obligation + the map-update-on-410 trigger. | Pre-call: grep output shown in the audit (map-hit / map-miss). Post-call: map-update PR when 410/301 lands, with "Map drift log" row recording old-path + redirect-doc + drift-date. Cadenced: sweep output logged to `docs/hygiene-history/surface-map-drift-history.md` (per-fire schema per row #44). ROUND-HISTORY row when a drift resolves. | `memory/feedback_surface_map_consultation_before_guessing_urls.md` (authoritative) + `docs/research/github-surface-map-complete-2026-04-22.md` (primary target for GitHub surfaces) + `docs/AGENT-GITHUB-SURFACES.md` (ten-surface playbook) + `docs/HARNESS-SURFACES.md` + `docs/GITHUB-SETTINGS.md` + this row's enforcement discipline (agent-self-administered pre-call, detection scripts TBD under `tools/hygiene/audit-surface-map-drift.sh`) | | ||
| | 57 | Git-hotspots audit (cadenced ranking of high-churn files as friction-point candidates) | Detect-only (landed 2026-04-23); cadenced detection every 5-10 rounds (same cadence as rows #5 / #38 / #46 meta-audits) + opportunistic on-touch when merge conflicts surface on a shared file. No enforcement; detection-first per the *"detection-first, action-second"* framing in the Otto-54 directive cluster. | Dejan (devops-engineer) on cadenced sweeps; Architect (Kenji) on per-file action decisions (split / freeze / archive / watch); all agents (self-administered) on on-touch when a merge conflict surfaces. | factory | `tools/hygiene/audit-git-hotspots.sh --window "60 days" --top 20 --report docs/hygiene-history/git-hotspots-YYYY-MM-DD.md` runs a `git log --since --name-only` pass, counts per-file touches over the window, enriches with unique-author + PR-count columns, ranks top-N, and emits a markdown report. Excludes `docs/hygiene-history/`, `openspec/changes/`, `references/upstreams/` as legitimately-by-design high-churn. **Why this row exists:** the human maintainer 2026-04-23 Otto-54 four-message cluster — *"cadence for checking github hotspots too this is a hygene issues points of friction and bottlenecks, we are frictionless... git hotspots i mean... we are gitnative with github as our first host"*. High-churn shared files are the paradigmatic friction surface (routine merge conflicts, reviewer burden, serialization bottleneck) and git log is the native instrument for detecting them. **First-fire finding (2026-04-23):** `docs/BACKLOG.md` is the top hotspot at 34 touches / 26 PRs in 30 days — effectively one BACKLOG touch per PR opened. The Otto-54 BACKLOG-per-swim-lane split row is the direct remediation. Other notable hotspots: `docs/ROUND-HISTORY.md` (freeze-then-watch), `memory/MEMORY.md` (cadence candidate — Otto-54 CURRENT-freshness row), 4 skill files (audit candidates for skill-tune-up). **Classification (row #50):** **prevention-bearing** — surfacing friction candidates before they compound into routine merge-tangle is upstream prevention, even though the tool itself is detect-only. Ships to project-under-construction: adopters inherit the audit + exclusion-prefix discipline + the per-file-action decision taxonomy. | Audit output in `docs/hygiene-history/git-hotspots-YYYY-MM-DD.md` per fire (per-fire schema per row #44 — date, window, top-N, Otto observations, per-file action, synthesis); BACKLOG rows for `split` / `audit` actions; ROUND-HISTORY row when a file transitions out of hotspot status via split / freeze / archive. | `tools/hygiene/audit-git-hotspots.sh` (detection + exclusion list + ranking) + `docs/hygiene-history/git-hotspots-2026-04-23.md` (first-run baseline with Otto observations) + Otto-54 directive cluster in BACKLOG.md § "P1 — Git-native hygiene cadences" + **out-of-repo** (per-user memory, not yet in-repo) companion memory `feedback/project_factory_is_git_native_github_first_host_hygiene_cadences_for_frictionless_operation_2026_04_23.md` (captures the four-message directive verbatim) | | ||
| | 56 | MD032 plus-at-line-start preflight audit (detects prose-continuation `+` followed by space that markdownlint misparses as list items) | Detect-only (landed 2026-04-24); on-touch when author edits markdown; round-cadence sweep + `--enforce` flip when baseline is green. | Dejan (devops-engineer) on cadenced + enforce-transition; author of markdown change self-administered on-touch. | factory | `tools/hygiene/audit-md032-plus-linestart.sh` scans tracked `.md` files for CommonMark-style plus-then-space list-marker lines (regex `^ {0,3}\+` followed by a single space: up to 3 leading spaces allowed, then `+`, then space) where the previous line is non-blank AND is not itself a plus-then-space marker line (so contiguous plus-space lists are not flagged). Whitespace-normalisation on the predecessor-blank check strips all whitespace classes (spaces, tabs, CR) via `[[:space:]]`, so tab-only separator lines count as blank. Path iteration uses NUL-delimited `git ls-files -z` piped into a `while read -d ''` loop and the script runs `cd` to `git rev-parse --show-toplevel` first, so paths resolve from repo root regardless of working directory. Excludes `docs/ROUND-HISTORY.md`, `docs/hygiene-history/**`, `docs/DECISIONS/**`, and self. The `--list` flag prints offending `file:lineno`; `--enforce` flips exit 2 on gap. **Why this row exists:** Otto-session 2026-04-23 hit MD032 regressions three times (Otto-35 + Otto-38 + Otto-38-again). The pattern is author-friendly in intent (prose continuation using `+`) but markdownlint-hostile (parsed as list item). Author-time detection prevents the full CI round-trip. Baseline at first fire (2026-04-24, post review-drain revision on PR #204) was ~170 gaps at repo scope — the CommonMark-aware rewrite removed the earlier file-level-skip heuristic (which masked false negatives when a file used `+` as its bullet style but still contained a prose-continuation `+`) in favour of per-line contiguous-list detection. **Classification (row #47):** **prevention-bearing** — audit runs at author-time (on-touch) and surfaces gap before commit. Ships to project-under-construction: adopters inherit audit + pattern + exclusion discipline. | Audit output on each fire; cadenced runs appended to `docs/hygiene-history/md032-plus-linestart-audit-history.md` (per-fire schema per row #44); author-time gap lands as fix-at-source (opportunistic). | `tools/hygiene/audit-md032-plus-linestart.sh` + this row's self-reference | |
| | 55 | Machine-specific content scrubber (cadenced audit of in-repo tracked files for user-home paths, Claude Code harness paths, Windows user-profile paths, hostname leaks) | Detect-only (landed 2026-04-23); cadenced detection once per round-close (same cadence as rows #50 / #51 / #52 meta-audits) + opportunistic on-touch when a tick migrates per-user content to in-repo. Enforcement (`--enforce` exit-2) deferred until baseline is green. | Dejan (devops-engineer) on cadenced detection + CI-enforcement sign-off when baseline is green; the migrating agent (self-administered) on on-touch — every in-repo-first migration runs the audit before committing. | factory | `tools/hygiene/audit-machine-specific-content.sh` scans all tracked files (`git ls-files`) for machine-specific patterns: `/Users/<name>/`, `/home/<name>/`, `C:\Users\<name>`, `C:/Users/<name>`. Excludes: `docs/ROUND-HISTORY.md`, `docs/hygiene-history/**`, `docs/DECISIONS/**`, and the audit script itself. `--list` prints offending files; `--enforce` flips exit 2 on any gap. **Why this row exists:** Aaron 2026-04-23 Otto-27 — *"we can have a machine specific scrubber/lint hygene task for anyting that makes it in by default. just run on a cadence."* Following the Option D in-repo-first policy shift (per-user memory migrations to in-repo became the default), machine-specific content leakage becomes a real risk — content comfortably per-user now crosses the factory's public repo boundary. Baseline at first fire (2026-04-23) was 9 gaps: `/Users/` patterns in several SKILL.md files, 2 PDFs (metadata scan), a scratch-recon doc, a parallel-worktree research doc; `C:\Users\` pattern in 1 SKILL.md + `memory/feedback_path_hygiene.md` (anti-example reference — legitimate). **Classification (row #47):** **prevention-bearing** — the audit runs at author-time (on-touch during in-repo-first migrations) and surfaces the gap before it lands. Ships to project-under-construction: adopters inherit the audit + pattern list + exclusion-list discipline. | Audit output on each fire; cadenced runs appended to `docs/hygiene-history/machine-specific-content-audit-history.md` (per-fire schema per row #44 — date, agent, gaps count, files touched, actions taken, next-fire-expected-date); BACKLOG row per gap at triage time if cleanup doesn't fit on-touch. | `tools/hygiene/audit-machine-specific-content.sh` (detection + pattern list + exclusion list) + cross-refs: `memory/feedback_path_hygiene.md` + `memory/CURRENT-aaron.md` + `memory/CURRENT-amara.md` (in-repo-first migration boundary surfaces this audit's need) | | ||
| | 60 | Surface-map-drift smell (wrong URL on a mapped surface fires a hygiene alarm) | Pre-call: every `gh api <path>` (or equivalent platform call) on a surface that has a mapping doc — grep the map first, use its path, otherwise record a map-gap. Post-call: every 410 / 301 / "endpoint moved" response on a mapped endpoint auto-proposes a map-update. Cadenced sweep every 5-10 rounds replays the full set of mapped endpoints against the current platform to catch silent drift (endpoint renamed without 410). | Any agent calling `gh api` (self-administered on pre-call / post-call); Dejan (devops-engineer) on the cadenced sweep; Kenji (Architect) on map-update PRs when drift lands. Bounded to surfaces with a mapping doc under `docs/research/*surface-map*.md` / `docs/AGENT-*-SURFACES.md` / `docs/HARNESS-SURFACES.md` / `docs/GITHUB-SETTINGS.md`. | factory | **Pre-call (prevention-bearing):** before invoking any `gh api` call against org / enterprise / Copilot / billing / settings surfaces, `grep -li "<surface-keyword>" <mapping-docs>` and use the path the map lists. If the map lacks the path, **file a map-gap finding** in the same audit's output — agent may still call a best-guess endpoint if confident the surface exists, but must log the gap so the next round-close sweep extends the map. **Post-call (detection-bearing):** any `410 Gone` / `301 Moved Permanently` / `"endpoint moved"` response from a mapped endpoint triggers a map-update task (write the new path to the map; note old-path + redirect-doc + drift-date in a "Map drift log" section). **Cadenced (detection-bearing):** every 5-10 rounds, replay the full set of mapped endpoints against the current platform to catch silent renames (200 OK from a stale path that silently redirects, or 404 from an endpoint removed without deprecation). **Why this row exists:** Aaron 2026-04-22 after agent invented `/orgs/.../billing/budgets` (404) for LFG budget audit despite task #195 having already produced the complete map: *"i'm supprised you got the url wrong given you mapped it"* + *"that should be a smell when that happen to a surface you already have mapped"*. Same incident revealed a second drift class — `/orgs/{org}/settings/billing/actions` (map §A.17) returned 410 with `documentation_url: https://gh.io/billing-api-updates-org`, meaning GitHub moved the endpoint between 2026-04-22 (map author-time) and 2026-04-22 (this fire, hours later). Two orthogonal failure modes compound: (a) **not-consulting** an existing map (guess without grep), (b) **consulting-but-stale** map (correct path + platform drift). **UI-only surfaces** (e.g., GitHub org budget management at `https://github.com/organizations/{org}/billing/budgets`, no REST equivalent) are legitimate map entries — the map should mark them as `ui-only` so agents know "no API path exists" before trying. **Classification (row #47):** **prevention-bearing** — the pre-call grep discipline is the prevention layer; the post-call 410 handler is a complementary detection layer; the cadenced sweep is the insurance detection layer for silent renames. See `memory/feedback_surface_map_consultation_before_guessing_urls.md`. Ships to project-under-construction: adopters inherit the smell pattern + the pre-call grep obligation + the map-update-on-410 trigger. | Pre-call: grep output shown in the audit (map-hit / map-miss). Post-call: map-update PR when 410/301 lands, with "Map drift log" row recording old-path + redirect-doc + drift-date. Cadenced: sweep output logged to `docs/hygiene-history/surface-map-drift-history.md` (per-fire schema per row #44). ROUND-HISTORY row when a drift resolves. | `memory/feedback_surface_map_consultation_before_guessing_urls.md` (authoritative) + `docs/research/github-surface-map-complete-2026-04-22.md` (primary target for GitHub surfaces) + `docs/AGENT-GITHUB-SURFACES.md` (ten-surface playbook) + `docs/HARNESS-SURFACES.md` + `docs/GITHUB-SETTINGS.md` + this row's enforcement discipline (agent-self-administered pre-call, detection scripts TBD under `tools/hygiene/audit-surface-map-drift.sh`) | | ||
| | 57 | Git-hotspots audit (cadenced ranking of high-churn files as friction-point candidates) | Detect-only (landed 2026-04-23); cadenced detection every 5-10 rounds (same cadence as rows #5 / #38 / #46 meta-audits) + opportunistic on-touch when merge conflicts surface on a shared file. No enforcement; detection-first per the *"detection-first, action-second"* framing in the Otto-54 directive cluster. | Dejan (devops-engineer) on cadenced sweeps; Architect (Kenji) on per-file action decisions (split / freeze / archive / watch); all agents (self-administered) on on-touch when a merge conflict surfaces. | factory | `tools/hygiene/audit-git-hotspots.sh --window "60 days" --top 20 --report docs/hygiene-history/git-hotspots-YYYY-MM-DD.md` runs a `git log --since --name-only` pass, counts per-file touches over the window, enriches with unique-author + PR-count columns, ranks top-N, and emits a markdown report. Excludes `docs/hygiene-history/`, `openspec/changes/`, `references/upstreams/` as legitimately-by-design high-churn. **Why this row exists:** the human maintainer 2026-04-23 Otto-54 four-message cluster — *"cadence for checking github hotspots too this is a hygene issues points of friction and bottlenecks, we are frictionless... git hotspots i mean... we are gitnative with github as our first host"*. High-churn shared files are the paradigmatic friction surface (routine merge conflicts, reviewer burden, serialization bottleneck) and git log is the native instrument for detecting them. **First-fire finding (2026-04-23):** `docs/BACKLOG.md` is the top hotspot at 34 touches / 26 PRs in 30 days — effectively one BACKLOG touch per PR opened. The Otto-54 BACKLOG-per-swim-lane split row is the direct remediation. Other notable hotspots: `docs/ROUND-HISTORY.md` (freeze-then-watch), `memory/MEMORY.md` (cadence candidate — Otto-54 CURRENT-freshness row), 4 skill files (audit candidates for skill-tune-up). **Classification (row #50):** **prevention-bearing** — surfacing friction candidates before they compound into routine merge-tangle is upstream prevention, even though the tool itself is detect-only. Ships to project-under-construction: adopters inherit the audit + exclusion-prefix discipline + the per-file-action decision taxonomy. | Audit output in `docs/hygiene-history/git-hotspots-YYYY-MM-DD.md` per fire (per-fire schema per row #44 — date, window, top-N, Otto observations, per-file action, synthesis); BACKLOG rows for `split` / `audit` actions; ROUND-HISTORY row when a file transitions out of hotspot status via split / freeze / archive. | `tools/hygiene/audit-git-hotspots.sh` (detection + exclusion list + ranking) + `docs/hygiene-history/git-hotspots-2026-04-23.md` (first-run baseline with Otto observations) + Otto-54 directive cluster in BACKLOG.md § "P1 — Git-native hygiene cadences" + **out-of-repo** (per-user memory, not yet in-repo) companion memory `feedback/project_factory_is_git_native_github_first_host_hygiene_cadences_for_frictionless_operation_2026_04_23.md` (captures the four-message directive verbatim) | | ||
| | 56 | MD032 plus-at-line-start preflight audit (detects prose-continuation `+` followed by space that markdownlint misparses as list items) | Detect-only (landed 2026-04-24); on-touch when author edits markdown; round-cadence sweep + `--enforce` flip when baseline is green. | Dejan (devops-engineer) on cadenced + enforce-transition; author of markdown change self-administered on-touch. | factory | `tools/hygiene/audit-md032-plus-linestart.sh` scans tracked `.md` files for CommonMark-style plus-then-space list-marker lines (regex `^ {0,3}\+` followed by a single space: up to 3 leading spaces allowed, then `+`, then space) where the previous line is non-blank AND is not itself a plus-then-space marker line (so contiguous plus-space lists are not flagged). Whitespace-normalisation on the predecessor-blank check strips all whitespace classes (spaces, tabs, CR) via `[[:space:]]`, so tab-only separator lines count as blank. Path iteration uses NUL-delimited `git ls-files -z` piped into a `while read -d ''` loop and the script runs `cd` to `git rev-parse --show-toplevel` first, so paths resolve from repo root regardless of working directory. Excludes `docs/ROUND-HISTORY.md`, `docs/hygiene-history/**`, `docs/DECISIONS/**`, and self. The `--list` flag prints offending `file:lineno`; `--enforce` flips exit 2 on gap. **Why this row exists:** Otto-session 2026-04-23 hit MD032 regressions three times (Otto-35 + Otto-38 + Otto-38-again). The pattern is author-friendly in intent (prose continuation using `+`) but markdownlint-hostile (parsed as list item). Author-time detection prevents the full CI round-trip. Baseline at first fire (2026-04-24, post review-drain revision on PR #204) was ~170 gaps at repo scope — the CommonMark-aware rewrite removed the earlier file-level-skip heuristic (which masked false negatives when a file used `+` as its bullet style but still contained a prose-continuation `+`) in favour of per-line contiguous-list detection. **Classification (row #47):** **prevention-bearing** — audit runs at author-time (on-touch) and surfaces gap before commit. Ships to project-under-construction: adopters inherit audit + pattern + exclusion discipline. | Audit output on each fire; cadenced runs appended to `docs/hygiene-history/md032-plus-linestart-audit-history.md` (per-fire schema per row #44); author-time gap lands as fix-at-source (opportunistic). | `tools/hygiene/audit-md032-plus-linestart.sh` + this row's self-reference | |
| | 55 | Machine-specific content scrubber (cadenced audit of in-repo tracked files for user-home paths, Claude Code harness paths, Windows user-profile paths, hostname leaks) | Detect-only (landed 2026-04-23); cadenced detection once per round-close (same cadence as rows #50 / #51 / #52 meta-audits) + opportunistic on-touch when a tick migrates per-user content to in-repo. Enforcement (`--enforce` exit-2) deferred until baseline is green. | Dejan (devops-engineer) on cadenced detection + CI-enforcement sign-off when baseline is green; the migrating agent (self-administered) on on-touch — every in-repo-first migration runs the audit before committing. | factory | `tools/hygiene/audit-machine-specific-content.sh` scans all tracked files (`git ls-files`) for machine-specific patterns: `/Users/<name>/`, `/home/<name>/`, `C:\Users\<name>`, `C:/Users/<name>`. Excludes: `docs/ROUND-HISTORY.md`, `docs/hygiene-history/**`, `docs/DECISIONS/**`, and the audit script itself. `--list` prints offending files; `--enforce` flips exit 2 on any gap. **Why this row exists:** Aaron 2026-04-23 Otto-27 — *"we can have a machine specific scrubber/lint hygene task for anyting that makes it in by default. just run on a cadence."* Following the Option D in-repo-first policy shift (per-user memory migrations to in-repo became the default), machine-specific content leakage becomes a real risk — content comfortably per-user now crosses the factory's public repo boundary. Baseline at first fire (2026-04-23) was 9 gaps: `/Users/` patterns in several SKILL.md files, 2 PDFs (metadata scan), a scratch-recon doc, a parallel-worktree research doc; `C:\Users\` pattern in 1 SKILL.md + `memory/feedback_path_hygiene.md` (anti-example reference — legitimate). **Classification (row #47):** **prevention-bearing** — the audit runs at author-time (on-touch during in-repo-first migrations) and surfaces the gap before it lands. Ships to project-under-construction: adopters inherit the audit + pattern list + exclusion-list discipline. | Audit output on each fire; cadenced runs appended to `docs/hygiene-history/machine-specific-content-audit-history.md` (per-fire schema per row #44 — date, agent, gaps count, files touched, actions taken, next-fire-expected-date); BACKLOG row per gap at triage time if cleanup doesn't fit on-touch. | `tools/hygiene/audit-machine-specific-content.sh` (detection + pattern list + exclusion list) + cross-refs: `memory/feedback_path_hygiene.md` + `memory/CURRENT-aaron.md` + `memory/CURRENT-amara.md` (in-repo-first migration boundary surfaces this audit's need) | | ||
| | 60 | Surface-map-drift smell (wrong URL on a mapped surface fires a hygiene alarm) | Pre-call: every `gh api <path>` (or equivalent platform call) on a surface that has a mapping doc — grep the map first, use its path, otherwise record a map-gap. Post-call: every 410 / 301 / "endpoint moved" response on a mapped endpoint auto-proposes a map-update. Cadenced sweep every 5-10 rounds replays the full set of mapped endpoints against the current platform to catch silent drift (endpoint renamed without 410). | Any agent calling `gh api` (self-administered on pre-call / post-call); Dejan (devops-engineer) on the cadenced sweep; Kenji (Architect) on map-update PRs when drift lands. Bounded to surfaces with a mapping doc under `docs/research/*surface-map*.md` / `docs/AGENT-*-SURFACES.md` / `docs/HARNESS-SURFACES.md` / `docs/GITHUB-SETTINGS.md`. | factory | **Pre-call (prevention-bearing):** before invoking any `gh api` call against org / enterprise / Copilot / billing / settings surfaces, `grep -li "<surface-keyword>" <mapping-docs>` and use the path the map lists. If the map lacks the path, **file a map-gap finding** in the same audit's output — agent may still call a best-guess endpoint if confident the surface exists, but must log the gap so the next round-close sweep extends the map. **Post-call (detection-bearing):** any `410 Gone` / `301 Moved Permanently` / `"endpoint moved"` response from a mapped endpoint triggers a map-update task (write the new path to the map; note old-path + redirect-doc + drift-date in a "Map drift log" section). **Cadenced (detection-bearing):** every 5-10 rounds, replay the full set of mapped endpoints against the current platform to catch silent renames (200 OK from a stale path that silently redirects, or 404 from an endpoint removed without deprecation). **Why this row exists:** Aaron 2026-04-22 after agent invented `/orgs/.../billing/budgets` (404) for LFG budget audit despite task #195 having already produced the complete map: *"i'm supprised you got the url wrong given you mapped it"* + *"that should be a smell when that happen to a surface you already have mapped"*. Same incident revealed a second drift class — `/orgs/{org}/settings/billing/actions` (map §A.17) returned 410 with `documentation_url: https://gh.io/billing-api-updates-org`, meaning GitHub moved the endpoint between 2026-04-22 (map author-time) and 2026-04-22 (this fire, hours later). Two orthogonal failure modes compound: (a) **not-consulting** an existing map (guess without grep), (b) **consulting-but-stale** map (correct path + platform drift). **UI-only surfaces** (e.g., GitHub org budget management at `https://github.com/organizations/{org}/billing/budgets`, no REST equivalent) are legitimate map entries — the map should mark them as `ui-only` so agents know "no API path exists" before trying. **Classification (row #47):** **prevention-bearing** — the pre-call grep discipline is the prevention layer; the post-call 410 handler is a complementary detection layer; the cadenced sweep is the insurance detection layer for silent renames. See `memory/feedback_surface_map_consultation_before_guessing_urls.md`. Ships to project-under-construction: adopters inherit the smell pattern + the pre-call grep obligation + the map-update-on-410 trigger. | Pre-call: grep output shown in the audit (map-hit / map-miss). Post-call: map-update PR when 410/301 lands, with "Map drift log" row recording old-path + redirect-doc + drift-date. Cadenced: sweep output logged to `docs/hygiene-history/surface-map-drift-history.md` (per-fire schema per row #44). ROUND-HISTORY row when a drift resolves. | `memory/feedback_surface_map_consultation_before_guessing_urls.md` (authoritative) + `docs/research/github-surface-map-complete-2026-04-22.md` (primary target for GitHub surfaces) + `docs/AGENT-GITHUB-SURFACES.md` (ten-surface playbook) + `docs/HARNESS-SURFACES.md` + `docs/GITHUB-SETTINGS.md` + this row's enforcement discipline (agent-self-administered pre-call, detection scripts TBD under `tools/hygiene/audit-surface-map-drift.sh`) | | ||
| | 57 | Git-hotspots audit (cadenced ranking of high-churn files as friction-point candidates) | Detect-only (landed 2026-04-23); cadenced detection every 5-10 rounds (same cadence as rows #5 / #38 / #46 meta-audits) + opportunistic on-touch when merge conflicts surface on a shared file. No enforcement; detection-first per the *"detection-first, action-second"* framing in the Otto-54 directive cluster. | Dejan (devops-engineer) on cadenced sweeps; Architect (Kenji) on per-file action decisions (split / freeze / archive / watch); all agents (self-administered) on on-touch when a merge conflict surfaces. | factory | `tools/hygiene/audit-git-hotspots.sh --window "60 days" --top 20 --report docs/hygiene-history/git-hotspots-YYYY-MM-DD.md` runs a `git log --since --name-only` pass, counts per-file touches over the window, enriches with unique-author + PR-count columns, ranks top-N, and emits a markdown report. Excludes `docs/hygiene-history/`, `openspec/changes/`, `references/upstreams/` as legitimately-by-design high-churn. **Why this row exists:** the human maintainer 2026-04-23 Otto-54 four-message cluster — *"cadence for checking github hotspots too this is a hygene issues points of friction and bottlenecks, we are frictionless... git hotspots i mean... we are gitnative with github as our first host"*. High-churn shared files are the paradigmatic friction surface (routine merge conflicts, reviewer burden, serialization bottleneck) and git log is the native instrument for detecting them. **First-fire finding (2026-04-23):** `docs/BACKLOG.md` is the top hotspot at 34 touches / 26 PRs in 30 days — effectively one BACKLOG touch per PR opened. The Otto-54 BACKLOG-per-swim-lane split row is the direct remediation. Other notable hotspots: `docs/ROUND-HISTORY.md` (freeze-then-watch), `memory/MEMORY.md` (cadence candidate — Otto-54 CURRENT-freshness row), 4 skill files (audit candidates for skill-tune-up). **Classification (row #50):** **prevention-bearing** — surfacing friction candidates before they compound into routine merge-tangle is upstream prevention, even though the tool itself is detect-only. Ships to project-under-construction: adopters inherit the audit + exclusion-prefix discipline + the per-file-action decision taxonomy. | Audit output in `docs/hygiene-history/git-hotspots-YYYY-MM-DD.md` per fire (per-fire schema per row #44 — date, window, top-N, Otto observations, per-file action, synthesis); BACKLOG rows for `split` / `audit` actions; ROUND-HISTORY row when a file transitions out of hotspot status via split / freeze / archive. | `tools/hygiene/audit-git-hotspots.sh` (detection + exclusion list + ranking) + `docs/hygiene-history/git-hotspots-2026-04-23.md` (first-run baseline with Otto observations) + Otto-54 directive cluster in BACKLOG.md § "P1 — Git-native hygiene cadences" + **out-of-repo** (per-user memory, not yet in-repo) companion memory `feedback/project_factory_is_git_native_github_first_host_hygiene_cadences_for_frictionless_operation_2026_04_23.md` (captures the four-message directive verbatim) | | ||
| | 56 | MD032 plus-at-line-start preflight audit (detects prose-continuation `+` followed by space that markdownlint misparses as list items) | Detect-only (landed 2026-04-24); on-touch when author edits markdown; round-cadence sweep + `--enforce` flip when baseline is green. | Dejan (devops-engineer) on cadenced + enforce-transition; author of markdown change self-administered on-touch. | factory | `tools/hygiene/audit-md032-plus-linestart.sh` scans tracked `.md` files for CommonMark-style plus-then-space list-marker lines (regex `^ {0,3}\+` followed by a single space: up to 3 leading spaces allowed, then `+`, then space) where the previous line is non-blank AND is not itself a plus-then-space marker line (so contiguous plus-space lists are not flagged). Whitespace-normalisation on the predecessor-blank check strips all whitespace classes (spaces, tabs, CR) via `[[:space:]]`, so tab-only separator lines count as blank. Path iteration uses NUL-delimited `git ls-files -z` piped into a `while read -d ''` loop and the script runs `cd` to `git rev-parse --show-toplevel` first, so paths resolve from repo root regardless of working directory. Excludes `docs/ROUND-HISTORY.md`, `docs/hygiene-history/**`, `docs/DECISIONS/**`, and self. The `--list` flag prints offending `file:lineno`; `--enforce` flips exit 2 on gap. **Why this row exists:** Otto-session 2026-04-23 hit MD032 regressions three times (Otto-35 + Otto-38 + Otto-38-again). The pattern is author-friendly in intent (prose continuation using `+`) but markdownlint-hostile (parsed as list item). Author-time detection prevents the full CI round-trip. Baseline at first fire (2026-04-24, post review-drain revision on PR #204) was ~170 gaps at repo scope — the CommonMark-aware rewrite removed the earlier file-level-skip heuristic (which masked false negatives when a file used `+` as its bullet style but still contained a prose-continuation `+`) in favour of per-line contiguous-list detection. **Classification (row #47):** **prevention-bearing** — audit runs at author-time (on-touch) and surfaces gap before commit. Ships to project-under-construction: adopters inherit audit + pattern + exclusion discipline. | Audit output on each fire; cadenced runs appended to `docs/hygiene-history/md032-plus-linestart-audit-history.md` (per-fire schema per row #44); author-time gap lands as fix-at-source (opportunistic). | `tools/hygiene/audit-md032-plus-linestart.sh` + this row's self-reference | |
| | 55 | Machine-specific content scrubber (cadenced audit of in-repo tracked files for user-home paths, Claude Code harness paths, Windows user-profile paths, hostname leaks) | Detect-only (landed 2026-04-23); cadenced detection once per round-close (same cadence as rows #50 / #51 / #52 meta-audits) + opportunistic on-touch when a tick migrates per-user content to in-repo. Enforcement (`--enforce` exit-2) deferred until baseline is green. | Dejan (devops-engineer) on cadenced detection + CI-enforcement sign-off when baseline is green; the migrating agent (self-administered) on on-touch — every in-repo-first migration runs the audit before committing. | factory | `tools/hygiene/audit-machine-specific-content.sh` scans all tracked files (`git ls-files`) for machine-specific patterns: `/Users/<name>/`, `/home/<name>/`, `C:\Users\<name>`, `C:/Users/<name>`. Excludes: `docs/ROUND-HISTORY.md`, `docs/hygiene-history/**`, `docs/DECISIONS/**`, and the audit script itself. `--list` prints offending files; `--enforce` flips exit 2 on any gap. **Why this row exists:** Aaron 2026-04-23 Otto-27 — *"we can have a machine specific scrubber/lint hygene task for anyting that makes it in by default. just run on a cadence."* Following the Option D in-repo-first policy shift (per-user memory migrations to in-repo became the default), machine-specific content leakage becomes a real risk — content comfortably per-user now crosses the factory's public repo boundary. Baseline at first fire (2026-04-23) was 9 gaps: `/Users/` patterns in several SKILL.md files, 2 PDFs (metadata scan), a scratch-recon doc, a parallel-worktree research doc; `C:\Users\` pattern in 1 SKILL.md + `memory/feedback_path_hygiene.md` (anti-example reference — legitimate). **Classification (row #47):** **prevention-bearing** — the audit runs at author-time (on-touch during in-repo-first migrations) and surfaces the gap before it lands. Ships to project-under-construction: adopters inherit the audit + pattern list + exclusion-list discipline. | Audit output on each fire; cadenced runs appended to `docs/hygiene-history/machine-specific-content-audit-history.md` (per-fire schema per row #44 — date, agent, gaps count, files touched, actions taken, next-fire-expected-date); BACKLOG row per gap at triage time if cleanup doesn't fit on-touch. | `tools/hygiene/audit-machine-specific-content.sh` (detection + pattern list + exclusion list) + cross-refs: `memory/feedback_path_hygiene.md` + `memory/CURRENT-aaron.md` + `memory/CURRENT-amara.md` (in-repo-first migration boundary surfaces this audit's need) | | ||
| | 60 | Surface-map-drift smell (wrong URL on a mapped surface fires a hygiene alarm) | Pre-call: every `gh api <path>` (or equivalent platform call) on a surface that has a mapping doc — grep the map first, use its path, otherwise record a map-gap. Post-call: every 410 / 301 / "endpoint moved" response on a mapped endpoint auto-proposes a map-update. Cadenced sweep every 5-10 rounds replays the full set of mapped endpoints against the current platform to catch silent drift (endpoint renamed without 410). | Any agent calling `gh api` (self-administered on pre-call / post-call); Dejan (devops-engineer) on the cadenced sweep; Kenji (Architect) on map-update PRs when drift lands. Bounded to surfaces with a mapping doc under `docs/research/*surface-map*.md` / `docs/AGENT-*-SURFACES.md` / `docs/HARNESS-SURFACES.md` / `docs/GITHUB-SETTINGS.md`. | factory | **Pre-call (prevention-bearing):** before invoking any `gh api` call against org / enterprise / Copilot / billing / settings surfaces, `grep -li "<surface-keyword>" <mapping-docs>` and use the path the map lists. If the map lacks the path, **file a map-gap finding** in the same audit's output — agent may still call a best-guess endpoint if confident the surface exists, but must log the gap so the next round-close sweep extends the map. **Post-call (detection-bearing):** any `410 Gone` / `301 Moved Permanently` / `"endpoint moved"` response from a mapped endpoint triggers a map-update task (write the new path to the map; note old-path + redirect-doc + drift-date in a "Map drift log" section). **Cadenced (detection-bearing):** every 5-10 rounds, replay the full set of mapped endpoints against the current platform to catch silent renames (200 OK from a stale path that silently redirects, or 404 from an endpoint removed without deprecation). **Why this row exists:** Aaron 2026-04-22 after agent invented `/orgs/.../billing/budgets` (404) for LFG budget audit despite task #195 having already produced the complete map: *"i'm supprised you got the url wrong given you mapped it"* + *"that should be a smell when that happen to a surface you already have mapped"*. Same incident revealed a second drift class — `/orgs/{org}/settings/billing/actions` (map §A.17) returned 410 with `documentation_url: https://gh.io/billing-api-updates-org`, meaning GitHub moved the endpoint between 2026-04-22 (map author-time) and 2026-04-22 (this fire, hours later). Two orthogonal failure modes compound: (a) **not-consulting** an existing map (guess without grep), (b) **consulting-but-stale** map (correct path + platform drift). **UI-only surfaces** (e.g., GitHub org budget management at `https://github.com/organizations/{org}/billing/budgets`, no REST equivalent) are legitimate map entries — the map should mark them as `ui-only` so agents know "no API path exists" before trying. **Classification (row #47):** **prevention-bearing** — the pre-call grep discipline is the prevention layer; the post-call 410 handler is a complementary detection layer; the cadenced sweep is the insurance detection layer for silent renames. See `memory/feedback_surface_map_consultation_before_guessing_urls.md`. Ships to project-under-construction: adopters inherit the smell pattern + the pre-call grep obligation + the map-update-on-410 trigger. | Pre-call: grep output shown in the audit (map-hit / map-miss). Post-call: map-update PR when 410/301 lands, with "Map drift log" row recording old-path + redirect-doc + drift-date. Cadenced: sweep output logged to `docs/hygiene-history/surface-map-drift-history.md` (per-fire schema per row #44). ROUND-HISTORY row when a drift resolves. | `memory/feedback_surface_map_consultation_before_guessing_urls.md` (authoritative) + `docs/research/github-surface-map-complete-2026-04-22.md` (primary target for GitHub surfaces) + `docs/AGENT-GITHUB-SURFACES.md` (ten-surface playbook) + `docs/HARNESS-SURFACES.md` + `docs/GITHUB-SETTINGS.md` + this row's enforcement discipline (agent-self-administered pre-call, detection scripts TBD under `tools/hygiene/audit-surface-map-drift.sh`) | | ||
| | 57 | Git-hotspots audit (cadenced ranking of high-churn files as friction-point candidates) | Detect-only (landed 2026-04-23); cadenced detection every 5-10 rounds (same cadence as rows #5 / #38 / #46 meta-audits) + opportunistic on-touch when merge conflicts surface on a shared file. No enforcement; detection-first per the *"detection-first, action-second"* framing in the Otto-54 directive cluster. | Dejan (devops-engineer) on cadenced sweeps; Architect (Kenji) on per-file action decisions (split / freeze / archive / watch); all agents (self-administered) on on-touch when a merge conflict surfaces. | factory | `tools/hygiene/audit-git-hotspots.sh --window "60 days" --top 20 --report docs/hygiene-history/git-hotspots-YYYY-MM-DD.md` runs a `git log --since --name-only` pass, counts per-file touches over the window, enriches with unique-author + PR-count columns, ranks top-N, and emits a markdown report. Excludes `docs/hygiene-history/`, `openspec/changes/`, `references/upstreams/` as legitimately-by-design high-churn. **Why this row exists:** the human maintainer 2026-04-23 Otto-54 four-message cluster — *"cadence for checking github hotspots too this is a hygene issues points of friction and bottlenecks, we are frictionless... git hotspots i mean... we are gitnative with github as our first host"*. High-churn shared files are the paradigmatic friction surface (routine merge conflicts, reviewer burden, serialization bottleneck) and git log is the native instrument for detecting them. **First-fire finding (2026-04-23):** `docs/BACKLOG.md` is the top hotspot at 34 touches / 26 PRs in 30 days — effectively one BACKLOG touch per PR opened. The Otto-54 BACKLOG-per-swim-lane split row is the direct remediation. Other notable hotspots: `docs/ROUND-HISTORY.md` (freeze-then-watch), `memory/MEMORY.md` (cadence candidate — Otto-54 CURRENT-freshness row), 4 skill files (audit candidates for skill-tune-up). **Classification (row #50):** **prevention-bearing** — surfacing friction candidates before they compound into routine merge-tangle is upstream prevention, even though the tool itself is detect-only. Ships to project-under-construction: adopters inherit the audit + exclusion-prefix discipline + the per-file-action decision taxonomy. | Audit output in `docs/hygiene-history/git-hotspots-YYYY-MM-DD.md` per fire (per-fire schema per row #44 — date, window, top-N, Otto observations, per-file action, synthesis); BACKLOG rows for `split` / `audit` actions; ROUND-HISTORY row when a file transitions out of hotspot status via split / freeze / archive. | `tools/hygiene/audit-git-hotspots.sh` (detection + exclusion list + ranking) + `docs/hygiene-history/git-hotspots-2026-04-23.md` (first-run baseline with Otto observations) + Otto-54 directive cluster in BACKLOG.md § "P1 — Git-native hygiene cadences" + **out-of-repo** (per-user memory, not yet in-repo) companion memory `feedback/project_factory_is_git_native_github_first_host_hygiene_cadences_for_frictionless_operation_2026_04_23.md` (captures the four-message directive verbatim) | | ||
| | 56 | MD032 plus-at-line-start preflight audit (detects prose-continuation `+` followed by space that markdownlint misparses as list items) | Detect-only (landed 2026-04-24); on-touch when author edits markdown; round-cadence sweep + `--enforce` flip when baseline is green. | Dejan (devops-engineer) on cadenced + enforce-transition; author of markdown change self-administered on-touch. | factory | `tools/hygiene/audit-md032-plus-linestart.sh` scans tracked `.md` files for CommonMark-style plus-then-space list-marker lines (regex `^ {0,3}\+` followed by a single space: up to 3 leading spaces allowed, then `+`, then space) where the previous line is non-blank AND is not itself a plus-then-space marker line (so contiguous plus-space lists are not flagged). Whitespace-normalisation on the predecessor-blank check strips all whitespace classes (spaces, tabs, CR) via `[[:space:]]`, so tab-only separator lines count as blank. Path iteration uses NUL-delimited `git ls-files -z` piped into a `while read -d ''` loop and the script runs `cd` to `git rev-parse --show-toplevel` first, so paths resolve from repo root regardless of working directory. Excludes `docs/ROUND-HISTORY.md`, `docs/hygiene-history/**`, `docs/DECISIONS/**`, and self. The `--list` flag prints offending `file:lineno`; `--enforce` flips exit 2 on gap. **Why this row exists:** Otto-session 2026-04-23 hit MD032 regressions three times (Otto-35 + Otto-38 + Otto-38-again). The pattern is author-friendly in intent (prose continuation using `+`) but markdownlint-hostile (parsed as list item). Author-time detection prevents the full CI round-trip. Baseline at first fire (2026-04-24, post review-drain revision on PR #204) was ~170 gaps at repo scope — the CommonMark-aware rewrite removed the earlier file-level-skip heuristic (which masked false negatives when a file used `+` as its bullet style but still contained a prose-continuation `+`) in favour of per-line contiguous-list detection. **Classification (row #47):** **prevention-bearing** — audit runs at author-time (on-touch) and surfaces gap before commit. Ships to project-under-construction: adopters inherit audit + pattern + exclusion discipline. | Audit output on each fire; cadenced runs appended to `docs/hygiene-history/md032-plus-linestart-audit-history.md` (per-fire schema per row #44); author-time gap lands as fix-at-source (opportunistic). | `tools/hygiene/audit-md032-plus-linestart.sh` + this row's self-reference | |
Comment on lines
+67
to
+68
| # are historical record, not fixable. Also self-exclude. | ||
| exclude_pattern='^(docs/ROUND-HISTORY\.md|docs/hygiene-history/|docs/DECISIONS/|tools/hygiene/audit-md032-plus-linestart\.sh)' |
Comment on lines
+66
to
+68
| # Exclusion: audit-trail surfaces whose `+ `-at-line-start lines | ||
| # are historical record, not fixable. Also self-exclude. | ||
| exclude_pattern='^(docs/ROUND-HISTORY\.md|docs/hygiene-history/|docs/DECISIONS/|tools/hygiene/audit-md032-plus-linestart\.sh)' |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary\n\nPrevents recurring MD032 regression — the '+ '-at-line-start prose-continuation pattern that markdownlint misparses as a list item. Hit 3 times in Otto-session (Otto-35/38/38-again).\n\nTool:
tools/hygiene/audit-md032-plus-linestart.sh(detect-only + --list + --enforce modes).\n\nBaseline: 3 pre-existing gaps in persona notebooks.\n\nFACTORY-HYGIENE row #56 with full schema.\n\nOtto (loop-agent PM hat).