Skip to content

feat(m8): assemble operator procedures from named fences, with lints - #214

Merged
sushiHex merged 8 commits into
mainfrom
feat/m8-procedure-packager
Oct 16, 2026
Merged

sushiHex merged 8 commits into
mainfrom
feat/m8-procedure-packager

Conversation

@sushiHex

@sushiHex sushiHex commented Oct 16, 2026 •

Copy link
Copy Markdown
Owner

Refs #186

Why

Every recent live M8 session stopped on a defect at the procedure's composition or transport boundary, never on the code under test:

All of them came from step scripts copied together by hand.

Change

scripts/m8_procedure_package.py takes a reviewed procedure document's single TOML Composition block. It builds:

  • the exact step files (LF only);
  • each step's declared stdout file;
  • a MANIFEST.sha256, with the manifest's own SHA-256 printed.

Steps are built only from named fences in hash-pinned frozen sources and the document itself. Nothing is copied by hand. It refuses, naming the step:

  • an unresolvable source pin, heading or fence index, a CRLF document or source, or a repeated or invalid step name;
  • any text naming the lane CLI array (LANE) unless it comes from an allowlisted, reviewed lane-boundary block: Reconcile operator procedure output checks with real lane CLI summaries #210 L1–L3, OC Setup, S1 and S6a. Literals never may. The real frozen OC S4 and ER R1 bytes are refused;
  • strict schema violations: unknown keys, wrong types, empty parts or selections, and mixed parts;
  • a selected fence that isn't bash. Fences are parsed CommonMark-style, so indented fences, longer fences and exact closers are handled, and headings inside fences are ignored;
  • an undeclared or historical generation label. This is a spelling check, not proof of fresh paths;
  • an assigned =UNREVIEWED or =UNPREPARED placeholder, outside --template;
  • any CR in a built file, and declared stdout over 64 KiB. Output is renamed into place atomically.

It never runs anything. It's the first half of the end-to-end rehearsal; the g12 procedure, its Composition and a fake-host rehearsal of the built steps follow in the next PR.

Review

One Codex pass (gpt-6.1-sol, high) at 5488dd8 found introduced defects. All are fixed in 97843e8:

  • The lane lint was bypassable (lane_capture x true; "${LANE[@]}", command substitution, any backgrounded call that discards its output) and also refused harmless forms. It is replaced by a source allowlist that needs no shell parsing.
  • Permissive TOML shapes changed meaning. The schema is now strict.
  • LF was enforced on input only. Built output is now checked.
  • Indented and four-backtick fences were misparsed.
  • A sentinel was flagged as a placeholder.
  • check was not strict.

One finding was found independently and also fixed: headings inside fences.

Accepted as a design limit and documented: labels are a spelling check.

Evidence

  • tests/test_m8_procedure_package.py: 28 passed locally.
  • Ruff is clean.

The design was checked with Fable before implementation. It adopted:

  • the spec as a TOML block inside the frozen document, so one hash covers both;
  • the packager and lints first, as most of the value for the least effort;
  • explicit rehearsal skips for facts CI cannot provide.

🤖 Generated with Claude Code

https://claude.ai/code/session_01S7VMTaJ9XePzc8fjmBBFfs

Live sessions have stopped on composition defects, never on the code under
test: a blanket empty-stderr rule against a CLI summary, a block hardcoding
the previous generation's paths, quoting at a transport boundary. Each was
caused by hand-copying blocks into step scripts.

scripts/m8_procedure_package.py reads one TOML Composition block in a
reviewed procedure document. It builds exact LF step files, their declared
stdout and a SHA-256 manifest from named fences in hash-pinned frozen
sources. It refuses, naming the step:
- unresolvable sources, headings or fence indexes;
- a lane CLI call outside lane_capture, which would have caught the g11 S4
  stop;
- undeclared or historical generation labels, which would have caught the H7
  path gap;
- unreviewed placeholders outside --template;
- CRLF documents.

It never runs a step.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7VMTaJ9XePzc8fjmBBFfs
…nces

Review of 5488dd8 (Codex) found, all fixed here:
- The line-based lane lint was bypassable (`lane_capture x true;
  "${LANE[@]}" ...`, a command substitution, any backgrounded call that
  discards its output) and also refused harmless forms. It is replaced by an
  allowlist with no shell parsing. Only the reviewed blocks may name the lane
  array: #210 L1-L3, plus OC Setup, S1 and S6a. Literals never may, and
  splitting the name with a backslash-newline does not hide it.
- Permissive TOML shapes changed meaning: `historical = "false"` was truthy,
  `stdout = "ok"` became two lines, empty parts built an empty script, and a
  mixed literal/selection part ignored its selector. The schema is now strict.
- LF was checked only on input. Escaped CR in literals or stdout is now
  refused.
- Indented fences were invisible, four-backtick examples exposed their inner
  blocks, and a closer with a suffix closed the block. A CommonMark-style
  scanner fixes all three, and headings inside fences are ignored.
- The UNPREPARED refusal sentinel was a false placeholder hit. Only
  assignments (`=UNREVIEWED`, `=UNPREPARED`) count now.
- `check` is strict unless --template.
- Selected fences must be bash. Declared stdout is bounded to 65,536 bytes.
  Output is built in a sibling directory and renamed into place.

Labels stay a spelling check, documented as such, not proof of fresh paths.

Refs #186

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7VMTaJ9XePzc8fjmBBFfs
@sushiHex
sushiHex marked this pull request as ready for review October 16, 2026 02:59
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-16T05:17:04.854929Z 2961af0 Manual request
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 97843e8d12

ℹ️ 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 thread scripts/m8_procedure_package.py Resolved
Comment thread scripts/m8_procedure_package.py Resolved
Comment thread scripts/m8_procedure_package.py Resolved
Comment thread scripts/m8_procedure_package.py Resolved
…im OUT

Connector review of 97843e8 found these, all fixed:
- Quoted placeholder assignments (RUN_ID="UNREVIEWED") passed the check.
- Malformed sources (sources = [], a non-string path, a source named self)
  raised a traceback instead of a refusal.
- An empty literal part was silently accepted.
- On POSIX the final rename could replace an empty OUT that appeared
  meanwhile. OUT is now claimed with an exclusive mkdir, files are created
  with x mode, and MANIFEST.sha256 is written last, so a package without a
  manifest is incomplete.

Refs #186

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7VMTaJ9XePzc8fjmBBFfs
@sushiHex

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 148aacef14

ℹ️ 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 thread scripts/m8_procedure_package.py Resolved
Comment thread scripts/m8_procedure_package.py Resolved
Comment thread scripts/m8_procedure_package.py Resolved
Comment thread scripts/m8_procedure_package.py Resolved
…labels

Connector review of 148aace found these, all fixed:
- The allowlist matched by basename, so a pinned copy at fake/<name> passed.
  Only a bare sibling path of the procedure document can now be an
  allowlisted reviewed source.
- steps = 1 and a non-string source selector raised tracebacks. They are
  now refused.
- A label split by a line continuation (q\<newline>11) escaped the label
  check. Labels are now matched after joining continued lines.

Refs #186

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7VMTaJ9XePzc8fjmBBFfs
@sushiHex

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d39f8f144a

ℹ️ 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 thread scripts/m8_procedure_package.py Resolved
Comment thread scripts/m8_procedure_package.py Resolved
Comment thread scripts/m8_procedure_package.py Resolved
…uble labels

Connector review of d39f8f1 found these, all fixed:
- Placeholders were checked on unjoined text, so RUN_ID=UNRE\<newline>VIEWED
  slipped through.
- An empty selected bash fence produced a zero-byte step.
- A label declared both current and historical was silently current.

Refs #186

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7VMTaJ9XePzc8fjmBBFfs
@sushiHex

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 13d0f09d65

ℹ️ 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 thread scripts/m8_procedure_package.py Resolved
Comment thread scripts/m8_procedure_package.py Resolved
…s exact

Connector review of 13d0f09 found these, both fixed:
- Shell escaping and concatenation ($'X', UNRE\VIEWED, "UNRE""VIEWED")
  still hid a placeholder. Quotes, backslashes and $ are now removed before
  matching, and UNREVIEWED anywhere, or UNPREPARED anywhere but the
  UNPREPARED.bundle sentinel, is refused.
- Literal parts lost extra trailing newlines. Their bytes are now kept
  exactly, and only a missing final newline is supplied.

Refs #186

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7VMTaJ9XePzc8fjmBBFfs
@sushiHex

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8df8e21093

ℹ️ 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 thread scripts/m8_procedure_package.py Resolved
Comment thread scripts/m8_procedure_package.py Resolved
Comment thread scripts/m8_procedure_package.py Resolved
Connector review of 8df8e21:
- UNPREPARED.bundle.old passed as the sentinel. Only the complete
  UNPREPARED.bundle token is exempt now. Fixed.
- q'1'1 hid a stale label. Labels and placeholders now share one
  shell-normalized text, with continuations joined and quotes, backslashes
  and $ removed. Fixed.
- ANSI-C hex escapes are recorded as a design choice, not handled. The lints
  catch honest composition mistakes in reviewed documents; deliberate
  obfuscation is the review's job, not a shell interpreter's.

Refs #186

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7VMTaJ9XePzc8fjmBBFfs
@sushiHex

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2961af00f3

ℹ️ 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 thread scripts/m8_procedure_package.py Resolved
@sushiHex
sushiHex merged commit 8fbfc9a into main Oct 16, 2026
21 checks passed
@sushiHex
sushiHex deleted the feat/m8-procedure-packager branch October 16, 2026 23:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant