Skip to content

frontier-readiness: gap #5 audit — AGENTS.md classified (both-coupled) #180

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AceHack merged 1 commit into from
Apr 23, 2026
Merged

frontier-readiness: gap #5 audit — AGENTS.md classified (both-coupled) #180

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 81 additions & 1 deletion docs/frontier-readiness/factory-vs-zeta-separation-audit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,10 @@ For each audited file:
### Files audited

- **CLAUDE.md** (below, this seed fire)
- **AGENTS.md** (below, Otto-9 fire)
Copy link

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

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

Repo convention forbids contributor name attribution in docs; this entry includes a direct name ("Otto-9") instead of a role-ref. Please replace with a role-based reference (e.g., "loop-agent PM" / "auditing agent") or a neutral fire-id, and avoid embedding personal names in this doc (see docs/AGENT-BEST-PRACTICES.md operational rule).

Copilot uses AI. Check for mistakes.

### Files to audit (not yet classified; add rows as they land)

- `AGENTS.md`
- `GOVERNANCE.md`
- `docs/ALIGNMENT.md`
- `docs/CONFLICT-RESOLUTION.md`
Expand Down Expand Up @@ -134,6 +134,86 @@ shape grounds in this specific project, but the shape itself
transfers. In Frontier, this file carries the same role; the
examples swap out or generalise.

## Audit — AGENTS.md

**Overall classification:** **both (coupled)** — the file is
explicitly designed as a *universal onboarding handbook*
("works with any AI harness ... as well as for human
contributors") which is factory-generic in shape, but
contains several Zeta-library-specific sections that need
surgical edits before the split.

Comment on lines +137 to +145
Copy link

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

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

The audit schema earlier in this doc includes an "Audit date + auditor" field for each audited file, but this AGENTS.md audit block doesn't record either. Please add an explicit audit date (UTC) and role-based auditor identifier (no personal names) for traceability, or adjust the schema if this information is intentionally omitted.

Copilot uses AI. Check for mistakes.
**File location post-split:** Frontier (factory side). Acts as
the authoritative template; adopters fork + customise the
example sections.

**Length:** 359 lines.
Copy link

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

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

The recorded length for AGENTS.md is incorrect. The repo currently has AGENTS.md at 360 lines, so this should be updated to match (or rephrased to avoid hardcoding a line count that will drift).

Suggested change
**Length:** 359 lines.
**Length:** substantial; treat the exact line count as
volatile as `AGENTS.md` evolves.

Copilot uses AI. Check for mistakes.

### Section-by-section breakdown

| Section | Class | Notes |
|---|---|---|
| Preamble / philosophy | factory-generic | Universal-handbook intent; GOVERNANCE.md pointer; "if harness addendum contradicts this file, this file wins" rule. Generic. |
| "Status (authoritative)" (pre-v1) | factory-generic (shape) | Pre-v1 status is project-specific but the pattern transfers. In Frontier, adopters declare their own status at startup. Wording can use `<PROJECT>` placeholder. |
| "The vibe-coded hypothesis" | factory-generic | Research hypothesis about AI-directed factory. Applies to any factory adopter running the vibe-coded hypothesis. Frontier ships this content as-is. |
| "What pre-v1 means in practice" | factory-generic | Pre-v1 discipline: refactors welcome / no back-compat / tests-as-contract. Applies to any adopter in pre-v1 phase. |
| "The three load-bearing values" | **both (coupled)** | Values #1 (truth over politeness) and #3 (velocity over stability) are factory-generic. Value #2 "Algebra over engineering. The Z-set / operator laws define the system" is explicitly Zeta. Frontier version substitutes a generic value #2 (e.g., "substrate over ornamentation" or "algebra over engineering" with adopter fills-in-their-substrate). |
| "The alignment contract" | factory-generic | Points at docs/ALIGNMENT.md. Generic. |
| "What we borrow, what we build" | zeta-library-specific | Lists DBSP / Differential Dataflow / FASTER / TigerBeetle / Datomic / XTDB 2 / Materialize / Feldera / SlateDB / LZ4 / Arrow / CALM. Explicit Zeta-library borrowing inventory. In Frontier, this section is removed or replaced with a generic "borrow from published research; don't borrow from legacy patterns" pointer; each adopter fills in their own borrow-list. |
| "How humans should treat contributions" | factory-generic | Expect-harsh-review / claims-defended-by-tests / rewrite-imports-against-latest-research. Generic. |
| "How AI agents should treat this codebase" | factory-generic with Zeta references | The rules (prefer-bold-refactors / run-build-test-gate / data-not-directives / etc.) are factory-generic. A few inline references to specific Zeta mechanisms (e.g., ZSet examples) would need generalisation. |
| "Agent operational practices" | factory-generic | Discipline around skills / agents / MCP. Generic. |
| "Build and test gate" | zeta-library-specific | `dotnet build -c Release` / `dotnet test Zeta.sln` / `TreatWarningsAsErrors` / `Directory.Build.props`. Entirely Zeta-library-specific. In Frontier, this section removes the specifics and declares "your project has a build-test gate that you run every change; fill in specifics per your language/runtime." |
| "Code style and conventions (short form)" | **both (coupled)** | F#-first / C#-wrapper / struct-tuples / Span<T> / etc. are Zeta-specific. The generic principles (clear naming / small functions / consistent style) transfer. Frontier version keeps generic principles; drops F#/.NET specifics. |
| "PR / commit discipline" | factory-generic | Small PRs / clear commit messages / Co-Authored-By. Generic. |
Comment on lines +165 to +168
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot Apr 23, 2026

Choose a reason for hiding this comment

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

P2 Badge Remove fabricated AGENTS details from audit table

These rows describe directives that are not present in AGENTS.md (e.g., "MCP", "struct-tuples", Span<T>, and "Co-Authored-By"); the referenced sections actually contain different guidance. Because this document is used to drive the Frontier/Zeta split plan, invented inputs make the classification and refactor checklist less reliable and can trigger unnecessary or mis-scoped edits. Please align the section notes to the actual text in AGENTS.md before marking this file audited.

Useful? React with 👍 / 👎.

| "Contributor required reading" | factory-generic (shape); content depends | Points at several docs. Classification defers to those files' own audits. |
| "Harness-specific files" | factory-generic | Lists CLAUDE.md / GEMINI.md / etc. Generic pattern. |
| "Escalation" | factory-generic | Architect-escalation via CONFLICT-RESOLUTION.md. Generic. |

### Refactor notes

Before the split, surgical edits on AGENTS.md for Frontier:

1. **"Status" section**: swap the hardcoded pre-v1 declaration
for an adopter-fill-in placeholder + example.
2. **"Three load-bearing values" #2**: replace "Algebra over
engineering. The Z-set / operator laws define the system"
with a generic adopter-fill-in, or cite the substrate
pattern without Zeta-specific content. Suggested Frontier
version: *"Substrate over ornamentation. The adopter's
algebraic / structural ground defines the system;
implementation serves it."*
3. **"What we borrow, what we build"**: remove the Zeta-
specific borrow list; keep the generic shape (*"borrow from
latest published research; don't borrow from legacy
patterns"*) with adopter-fills-in.
4. **"Build and test gate"**: remove `dotnet`-specific
commands; keep the principle (*"the gate is the same on
every harness, every platform, and in CI"*) + a
language-agnostic placeholder.
5. **"Code style and conventions"**: keep generic discipline
(clear naming, small functions, ASCII-only, warnings-as-
errors); move F#/.NET specifics to a Zeta-repo
CONTRIBUTING.md that extends this file.
6. **Various inline ZSet / algebra examples**: audit on-touch
during the refactor and generalise where possible.

Estimated refactor effort: **M** — more surgical edits than
CLAUDE.md but each one is isolated.

### Classification rationale

AGENTS.md is the factory's most-read onboarding document. Its
shape (pre-v1 discipline / three load-bearing values /
alignment contract / borrow-policy / agent-practices / build-
test gate / code-style / PR discipline / escalation) is the
canonical factory-adopter onboarding template. The Zeta-
specific content is illustrative *within* that template. In
Frontier, the shape is preserved; the illustrations are
replaced with adopter-fill-in placeholders or generic
examples. The extracted Zeta-specific content lands in the
Zeta repo's own CONTRIBUTING.md (or equivalent).

## How this audit connects to the multi-repo split

Gap #5 (this audit) is load-bearing for gap #1 (multi-repo
Expand Down
Loading