Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
22 changes: 12 additions & 10 deletions .machine_readable/descriptiles/STATE.a2ml
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@
[metadata]
project = "scaffoldia"
version = "0.1.0"
last-updated = "2026-07-21"
last-updated = "2026-11-15"
status = "active" # active | paused | archived

[project-context]
name = "scaffoldia"
purpose = "Full-featured repository designer for the RSR estate: composes spine@pin x variant pack x features x profile into new repos, and retrofits existing ones (owner mandate 2026-07-07: composer + retrofit from day one). Sits above rsr-template-repo (`just init`, basic) in the scaffolding stack; consumes variant contracts (VARIANT.a2ml, ADR-0002 in rsr-template-repo) as data."
purpose = "Full-featured repository designer for the RSR estate: composes spine@pin x archetype/pack x features x capability profile into new repos and retrofits existing ones. Must consume the spine current deed-based archetype, variant, provenance and mint-answer contracts (rsr-template-repo ADR-0002/0003, partly superseded 2026-10-06); cannot invent a second format."
completion-percentage = 5

[position]
Expand All @@ -23,30 +23,32 @@ maturity = "experimental" # experimental | alpha | beta | production | lts
[route-to-mvp]
milestones = [
{ name = "Phase 0: RSR shell extracted from reposystem (2026-06-26), identity + hygiene", completion = 90 },
{ name = "Phase 1: composer design ADR (compose spine@pin x pack x features x profile)", completion = 0 },
{ name = "Phase 2: consume VARIANT.a2ml contracts as pack definitions (julia = first pack)", completion = 0 },
{ name = "Phase 1: proposed composer design ADR; decision and review outstanding", completion = 0 },
{ name = "Phase 2: parse spine praxis deeds, repo deed clauses, overlays and capability profile; julia-library first", completion = 0 },
{ name = "Phase 3: retrofit engine (pack-diff against existing repos)", completion = 0 },
{ name = "Phase 4: template-maintenance sync loop (regenerate rsr-*-template-repo family until cut-off)", completion = 0 },
]

[blockers-and-issues]
issues = [
"Composer design ADR pending — MUST explicitly weigh the dormant GitLab-lineage implementation (developer-ecosystem/scaffoldia: Haskell CLI + Nickel builder), not ignore it; fork resolved 2026-07-21: this repo is canonical, engine dormant, registry harvested (machine-readable-design/harvested-registry/)",
"Composer ADR-0002 proposed, not accepted: must compare dormant Haskell/Nickel, Rust core, and ABI/FFI options against working evidence; canonical repo is here, historical registry harvested as untrusted source data",
"Current source tree has no core composer, mint planner, retrofit engine or working cross-language ABI; CI and local validators contain stale template assumptions",
"Current canonical contract is deed-based; old VARIANT.a2ml / ARCHETYPE.a2ml references are superseded in part by rsr-template-repo ADR-0002/0003 (2026-10-06)",
"repo-batcher absorption (reposystem#56 V->Zig port) undecided — revisit after composer v0.1",
]

[critical-next-actions]
actions = [
"Author composer design ADR (consume VARIANT.a2ml/ARCHETYPE.a2ml; weigh dormant Haskell+Nickel engine; two distribution paths stay coherent)",
"Define pack format derived from the spine contracts (rsr-template-repo archetypes/ per ADR-0003 + rsr-julia-library-template-repo VARIANT.a2ml = references; harvested-registry entries = input data)",
"Decide src/ pillar implementation approach (current Idris2+Zig ABI seam is inherited scaffold)",
"Review ADR-0002 against current standards and spine; select engine via working spike without creating a competing contract schema",
"Implement pinned-source and deed/archetype readers, deterministic plan and dry-run, then mint and retrofit using one planner",
"Reconcile validation/CI failures; prove any retained Idris2-Zig ABI using real linked symbol and behaviour tests, or retire unused seam",
]

[fork-resolution]
# Two scaffoldia codebases existed with no recorded relationship. Resolved
# 2026-07-21 (see machine-readable-design/harvested-registry/README.adoc):
decision = "this repo = canonical design surface + consumer of spine contracts; developer-ecosystem/scaffoldia (GitLab lineage, implemented Haskell CLI + Nickel builder) = dormant engine, registry harvested as data, no parallel development"
profile-axis = "resolved: profile = capability set per standards template-capability-gates.toml (preset or direct list), i.e. what rsr-profile.a2ml declares (ADR-0003)"
profile-axis = "capability set from metadatastician/standards .machine_readable/template-capability-gates.toml; written as (rsr-profile) in the repository deed by current spine repo-init"

[maintenance-status]
last-run-utc = "never"
Expand All @@ -57,4 +59,4 @@ open-failures = 0

[ecosystem]
part-of = ["RSR Framework", "scaffolding stack (standards -> rsr-template-repo -> scaffoldia)"]
depends-on = ["rsr-template-repo", "standards"]
depends-on = ["hyperpolymath/rsr-template-repo", "metadatastician/standards"]
29 changes: 18 additions & 11 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -15,25 +15,30 @@ repositories, and retrofits existing ones.

[NOTE]
====
*Status: design phase.* This repository currently carries the RSR substrate
(governance, CI, machine-readable metadata) and the design surface for the
composer; the composition engine itself is not built yet. See
`.machine_readable/descriptiles/STATE.a2ml` for the honest state.
*Status: design phase; composition and retrofit are not implemented.* The
inherited RSR governance, CI and Idris2/Zig interface scaffold are not a
working repository designer. The present architecture and blockers are tracked
in `docs/architecture/TOPOLOGY.adoc`, `docs/status/ROADMAP.adoc`, and
`.machine_readable/descriptiles/STATE.a2ml`. The composer design is a
*proposal*, not an accepted engine decision (ADR-0002).
====

== What this is

Scaffoldia is the top layer of the estate's scaffolding stack:

standards → rsr-template-repo → scaffoldia → (designed/retrofitted repos)
metadatastician/standards → rsr-template-repo → scaffoldia → (designed/retrofitted repos)

`standards` defines the RSR canon; `rsr-template-repo` operationalises it as a
GitHub template with a basic `just init` scaffolder; *scaffoldia* is the
full-featured designer that treats variation as data. It consumes each variant
template's *variant contract* (`VARIANT.a2ml` — parent pin + declared path
divergences; see ADR-0002 in rsr-template-repo and the reference
implementation in `rsr-julia-library-template-repo`) so that GitHub's
"Use this template" path and the composed path can never silently diverge.
template's current *deed contracts*: archetype `*_praxis.deed` files,
overlays and the `(variant)`, `(provenance)`, `(rsr-profile)` and
`(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.
Comment on lines +37 to +41

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 👍 / 👎.


Mandated scope (owner, 2026-07-07): *composer + retrofit from day one* — the
same pack-diff machinery that composes new repos re-synchronises existing
Expand All @@ -55,8 +60,10 @@ just validate # structure + metadata checks (RSR shape)
in a2ml, so tools and agents can read the project's state and boundaries.
* *AI gatekeeper protocol* — `0-AI-MANIFEST.a2ml` is the universal entry point that
tells an AI agent how to work in this repo before it touches anything.
* *Typed ABI/FFI seam* — `src/interface/Abi/` (Idris2 type + layout proofs) over
`src/interface/ffi/` (Zig implementation), with generated C headers.
* *Inherited ABI/FFI scaffold* — `src/interface/Abi/` (Idris2) and
`src/interface/ffi/` (Zig). Their symbol names, return codes and pointer
semantics currently disagree; compilation of each side does *not* establish
cross-language conformance. Do not use the seam for composition yet.
* *CI/CD* — GitHub Actions for quality, security (CodeQL, Scorecard, secret
scanning), multi-forge mirroring, and RSR anti-pattern enforcement.
* *Supply-chain & reproducibility* — container layering (stapeln), Nix/Guix shells,
Expand Down
111 changes: 91 additions & 20 deletions docs/architecture/TOPOLOGY.adoc
Original file line number Diff line number Diff line change
@@ -1,36 +1,107 @@
// SPDX-License-Identifier: CC-BY-SA-4.0
// Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
// Last updated: 2026-04-04
= Architecture Topology
= Scaffoldia Architecture Topology
:toc:
:sectnums:

== System Overview
== Verified baseline (2026-11-15)

RSR (Rhodium Standard Repository) template provides the canonical scaffold for all hyperpolymath projects, with integrated CI/CD, documentation, and service discovery patterns.
Inspection base: `hyperpolymath/scaffoldia` main commit
`84e13a6e8b41e12026f2a5cbbd97fb91fc3fa849`.
This describes observed source, not a completed runtime.
`.machine_readable/descriptiles/STATE.a2ml` records 5% completion and design phase.

== Component Overview
== Ownership boundaries

[cols="1,1,2", options="header"]
[cols="1,2,3",options="header"]
|===
| Component | Language | Purpose
| Layer | Repository | Authority / output

| dogfood-gate workflow | YAML | Quality checks (CRG, security, linting)
| eclexiaiser-validate job | YAML | Resource cost awareness scoring
| Groove discovery | JSON | Service endpoint registration
| Canon | `metadatastician/standards` | RSR criteria, format rules, template-capability-gates.toml, scaffold lifecycle
| Spine | `hyperpolymath/rsr-template-repo` | `repo-init`, pinned base tree, `archetypes/<name>/<name>_praxis.deed`, overlays, lock fragments, deed clauses
| Composer | `hyperpolymath/scaffoldia` | Future deterministic composition, dry-run mint and retrofit plans, apply and reconciliation receipts
| Oracle | `hyperpolymath/hypatia` | Conformance scoring; Scaffoldia must not redefine scoring
| Sustain | `hyperpolymath/gitbot-fleet` and `hyperpolymath/reposystem` | Audit-first corrective campaigns and owner-gated application
|===

== Data Flow
The normative lifecycle is `metadatastician/standards/0-canon/rsr/SCAFFOLD-LIFECYCLE.adoc`
and the spine's accepted ADR-0002/0003. The upstream ADRs were amended
2026-10-06: standalone `VARIANT.a2ml` and `ARCHETYPE.a2ml` files are
superseded by `*_chora.deed` clauses and archetype `*_praxis.deed`.
Scaffoldia consumes these schemas; it does not fork their definitions.

== Present repository components (not a composer)

[cols="2,3,2",options="header"]
|===
| Path | Present code/data | Status

| `src/core`, `src/contracts`, `src/bridges`, `src/definitions`, `src/errors` | AI manifests/READMEs only | No composition engine
| `machine-readable-design/harvested-registry` | Seven legacy Nickel registry inputs | Data only; not live packs
| `src/interface/Abi/` | Generic Idris2 foreign declarations and type/layout model | Not matched to Zig exports
| `src/interface/ffi/` | Zig exported scaffold functions and unit/integration tests | No composer operations; Zig-side tests only
| `verification/proofs/` | Example/skeleton proof artifacts | No linked composer assurance
| `tests/` | Shell E2E, aspect, workflow tests | No actual mint/retrofit acceptance test
| `.github/workflows/` | 25 YAML workflows, actions.lock | Multiple pre-existing CI failures
| `.machine_readable/`, `build/`, `Justfile` | RSR substrate and task recipes | Some checks refer to removed/moved paths
|===

The `developer-ecosystem/scaffoldia` historical Haskell CLI + Nickel
builder is dormant, not an alternate implementation authority. Its CLI
`init` and `build` paths do not invoke the actual composer; the registry
is suitable for reviewed harvesting only.

== Required operational seams (proposed)

[source,text]
----
[Code Push] → [GitHub Actions] → [hypatia scan] → [eclexiaiser validate] → [Results]
Canon (version + gates) ------.
Spine (pin + deeds + overlays) +--> validated SourceSnapshot
Identity + capability request -' |
CompositionPlan
/ deterministic / dry-run
/ \
Mint adapter Retrofit adapter
\ /
Reconciliation/ExecutionReceipt
|
provenance + Hypatia + fleet proposal
----

== Integration Points
* 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.
Comment on lines +70 to +73

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 👍 / 👎.

* Apply: sandboxed file staging, no remote mutation by default; authorisation
required for real repository modification and all forge configuration.
* Reconcile: compare pinned base, current child, and desired child; preserve
unrelated user edits; report conflicts rather than overwrite.
* Observe: test/build/hypatia/drift evidence and outcome receipts. A skipped
or absent check cannot be reported as passing.

These are interfaces to implement, not capabilities claimed present.

== ABI/FFI blocker

`src/interface/Abi/Foreign.idr` imports C symbols `rsr_init`,
`rsr_free`, `rsr_process`; Zig exports `scaffoldia_init`,
`scaffoldia_free`, `scaffoldia_process`. Their result semantics differ.
The Idris2 platform model is a simplified 64-bit template, including
inapplicable generalisations. The Zig integration tests import Zig directly;
they do not link Idris2 calls through the C ABI. The interface is therefore
not verified and must not be called 'proven' before an end-to-end link test.
ADR-0002 leaves retention/retirement of this optional seam open.

* *Upstream*: Hypatia (neurosymbolic CI/CD), eclexiaiser (resource scoring)
* *Downstream*: All RSR-based repositories (500+ instances)
== Existing CI debt (observed on base commit)

== Deployment
* Well-known enforcement ignores existing `www/.well-known/security.txt`.
* Workflow linter's first-line SPDX check rejects managed lockfile headers,
then its literal SHA-only rule conflicts with actions.lock's tag-to-SHA map.
* Static analysis gate produced startup_failure; investigate workflow
permissions, allowlist and pinned reusable workflows separately.
* Some reusables still refer to `hyperpolymath/standards` while the live
canon is `metadatastician/standards`.
* The `e2e.yml` job invokes a script requiring Idris2 and Zig without
explicit toolchain provisioning.

* Container: Stapeln Six ecosystem
* CI/CD: GitHub Actions → Hypatia scan → eclexiaiser-validate (6 scorecard dimensions) → Mirror
* Service Discovery: Groove protocol (.well-known/groove/manifest.json)
Do not suppress failures to create a green summary. Fix at the owning layer
and verify the first real passing and deliberately failing checks.
Loading
Loading