Skip to content

docs(architecture): reconcile Scaffoldia with deed-era contracts and M0 acceptance gates - #68

Merged
hyperpolymath merged 1 commit into
mainfrom
audit/contract-reconciliation-20261115
Nov 15, 2026
Merged

hyperpolymath merged 1 commit into
mainfrom
audit/contract-reconciliation-20261115

Conversation

@hyperpolymath

Copy link
Copy Markdown
Owner

Scope

Read-only architectural reconciliation; no composer implementation, licensing changes, or merge claim.

  • Update README and STATE to recognize the current *_chora.deed clauses and archetype *_praxis.deed contracts from the spine (legacy standalone VARIANT.a2ml / ARCHETYPE.a2ml were superseded in part on 2026-10-06).
  • Replace outdated template TOPOLOGY with the observed Scaffoldia system/ownership map and unimplemented interface inventory.
  • Replace generic ROADMAP with corrective P0 and measured M0 acceptance gates for deterministic mint and retrofit.
  • Add proposed, not accepted, composer ADR comparing the historical Haskell/Nickel CLI, a Rust planning core, and whether Idris2/Zig is actually needed.

Baseline

Main 84e13a6e8b41e12026f2a5cbbd97fb91fc3fa849 inspected on 2026-11-15.
The repo's own STATE.a2ml still reports design phase and 5% completion. No core composer, mint planner or retrofit engine exists on this PR.

Known issues / separate corrective work

  • validate-rsr references obsolete licensing/ paths, validate-state prints invalid without failing, and the AI-install check expects absent template material.
  • Well-known workflow checks the wrong path for www/.well-known/security.txt.
  • Workflow linter assumes SPDX must be first even when gh actions-lock's managed preamble is first; its literal SHA-only check conflicts with the existing attested actions.lock structure.
  • E2E toolchain provisioning, ABI symbol/return mismatch, old reusable caller paths, and startup failures still require scoped implementation fixes.

Review requirements

  • Confirm normative source: metadatastician/standards and the live hyperpolymath/rsr-template-repo.
  • Review the ADR's engine-selection criteria before coding the composer.
  • Run checks on latest head; investigate failures rather than treating a green-only subset as completion.
  • No merging or readiness promotion without current passing required checks and resolved substantive review threads.

Record the observed design-phase baseline, current ownership boundaries,
composer/retrofit acceptance gates, and proposed engine ADR without
claiming implementation or CI success.
@coderabbitai

coderabbitai Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Caution

Review failed

The pull request is closed.

Summary

Summary by CodeRabbit

  • Documentation
    • Updated project status and roadmap information to distinguish existing capabilities from proposed work, including that composition, retrofit and related planning workflows are not yet implemented.
    • Added a proposed architecture covering repository composition and retrofit, with requirements for deterministic planning, dry-run execution, owner approval and validation.
    • Clarified current contract boundaries, integration constraints and release milestones, including the evidence required before completion.

The changes replace project status and topology descriptions and add a proposed composer architecture decision record. They document the current scaffold, proposed composition and retrofit capabilities, engine evaluation criteria, safety rules, acceptance evidence, and staged roadmap.

Changes: Scaffoldia architecture and roadmap

Layer / File(s) Summary
Verified baseline and current status
.machine_readable/descriptiles/STATE.a2ml, README.adoc, docs/architecture/TOPOLOGY.adoc
The documents describe the current scaffold, deed-based contracts, repository components, and identified limitations. They state that composition and retrofit are not implemented.
Proposed composer design
docs/decisions/0002-scaffoldia-composer-architecture.adoc
The proposed ADR defines composition and retrofit flows, interfaces, safety invariants, engine-selection criteria, and first-slice acceptance evidence.
Status tracking and staged delivery
.machine_readable/descriptiles/STATE.a2ml, docs/status/ROADMAP.adoc
The state checkpoint and roadmap record outstanding decisions, proposed milestones, acceptance requirements, and non-goals.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Other

Merge Risk: Low · up to b4934

This change only updates documentation and adds a proposed design record; no composer code ships. Before the ADR is accepted, reconcile its provenance-file contract with the accepted lifecycle document and specify how apply rechecks the target before writing. Merging the docs now carries little risk.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@sonarqubecloud

Copy link
Copy Markdown

@hyperpolymath
hyperpolymath marked this pull request as ready for review November 15, 2026 15:08
@hyperpolymath
hyperpolymath enabled auto-merge (squash) November 15, 2026 15:08
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-15T15:12:48.205845Z b493424 Draft marked ready
🔒 Security Review ✅ Completed 2026-11-15T15:11:04.473071Z b493424 Draft marked ready
ℹ️ 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.

@hyperpolymath
hyperpolymath enabled auto-merge (squash) November 15, 2026 15:08
@hyperpolymath
hyperpolymath merged commit 0f1ddbf into main Nov 15, 2026
19 of 20 checks passed
@hyperpolymath
hyperpolymath deleted the audit/contract-reconciliation-20261115 branch November 15, 2026 15:10

@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: b4934249ee

ℹ️ 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 README.adoc
Comment on lines +37 to +41
`(mint-answers)` clauses of a repository `*_chora.deed`. Earlier standalone
`VARIANT.a2ml`/`ARCHETYPE.a2ml` descriptions were superseded in part by
rsr-template-repo ADR-0002/0003 on 2026-10-06. Both the template mint and
Scaffoldia must use the same upstream contract semantics, with replayable
mint answers and drift checks; no parallel schema.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Update the canonical AI manifest for deed contracts

When an agent follows the repository's root entry point, 0-AI-MANIFEST.a2ml:12 still says that Scaffoldia consumes VARIANT.a2ml contracts. That directly conflicts with this new statement that those standalone contracts are superseded and no parallel schema is permitted, so automated implementation work can continue targeting the obsolete input format; update the root manifest as part of this reconciliation.

Useful? React with 👍 / 👎.

Comment thread docs/status/ROADMAP.adoc
Comment on lines +33 to +36
* [ ] Implement dry-run mint with actual Julia-library archetype (first
vertical slice) and an independently demonstrated Rust-CLI archetype.
* [ ] Implement dry-run three-way retrofit against pinned parent; preserve
unrelated changes and stop on conflicts.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Add an apply phase to M0

If M0 is implemented literally, both adapters stop at dry-run, but the ADR's M0 acceptance requires a minted repository to build, replay without drift, and exercise application idempotence. Those checks require materializing and applying a plan, so the milestone can currently be marked complete without satisfying its own acceptance evidence; include approved local staging/application for mint and retrofit in M0.

Useful? React with 👍 / 👎.

Comment on lines +70 to +73
* Ingest: pinned canon/spine snapshots, exact deed contracts and overlays;
reject unknown capability, unpinned inputs and invalid paths.
* Plan: deterministic ordering; detect duplicate and overlapping path claims;
emit explicit conflicts; never silent last-writer-wins.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Permit contract-declared overlay replacements

When an archetype or feature overlay intentionally replaces a path supplied by the spine, this rule classifies that expected overlap as a conflict, even though overlays are listed as required inputs to composition. Without an explicit precedence or replacement-authorization rule, the planner cannot apply ordinary overlays without violating the architecture; reserve conflicts for undeclared competing claims and define how deed-authorized overlay replacements are represented.

Useful? React with 👍 / 👎.

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.

2 participants