Module scaffold 

Scaffold writes — decided new, decided init, decided quickstart, decided migrate metadata (PORT-CONTRACT.d/16).

Ports of src/rac/core/idgen.py (generate_id), src/rac/core/ templates.py (load_template), src/asdecided/services/init.py (init_repository, load_repository_config, write_mcp_configs via src/asdecided/services/profiles.py), src/asdecided/services/create.py (create_artifact), src/asdecided/services/quickstart.py (quickstart), and src/asdecided/services/migrate.py (migrate_metadata).

The packaged template bodies are embedded verbatim from rust/decided-engine/assets/templates/, vendored byte-identical copies of the Python package files — a unit test below pins that identity, because the written artifact must be byte-identical to what the oracle writes.

Minted ids are wall-clock + CSPRNG derived (the oracle has no external seam); the parity harness masks them (mask-ids) on stdout AND captured file bytes, so this module uses the real clock and /dev/urandom.

Structs

CreatedArtifact

Result of one artifact creation (bytes_written is in the oracle’s dataclass but deliberately absent from its JSON, so it is not carried).

FileMigration

Migration outcome for one Markdown file.

InitResult

Outcome of one decided init run (stable JSON contract, ADR-007).

MigrationReport

Repository-level migration result (stable JSON contract, ADR-007).

QuickstartResult

Outcome of one decided quickstart run.

RepositoryConfig

A discovered repository identity configuration.

Enums

ScaffoldError

The scaffold failure contract, message-shaped like the oracle’s exception str(). Exit-code routing lives with each command handler, because the SAME error class maps to different exits per command (OutputPathExists is usage exit 2 under new but a refusal exit 1 under quickstart — measured).

Constants

ID_ALPHABET

Crockford base32: no I, L, O, U (visually ambiguous).

MCP_JSON

The AsDecided MCP server wiring, identical for Claude Code (.mcp.json) and Cursor (.cursor/mcp.json).

STATUS_ALREADY_CANONICAL

STATUS_MIGRATED

Stable per-file statuses (part of the JSON contract, ADR-007).

STATUS_SKIPPED_UNKNOWN

Functions

create_artifact

create_artifact(artifact_type, output_path) — write one new artifact with assigned identity. The path is taken literally: no slug derivation, no directory creation, never overwrite.

generate_id

generate_id(repository_key) — <KEY>- + 8-char millisecond-timestamp segment + 4-char random segment, Crockford base32.

init_repository

init_repository(directory, key, ticketing, profile, org_endpoint) — establish (or confirm) the identity namespace. ticketing and profile arrive argparse-choice-validated; both apply only on a FRESH init. org_endpoint (ADR-117) is an explicit operator action and applies on fresh AND already-initialized repositories alike.

load_repository_config

load_repository_config(start_dir) — the nearest .decided/config.yaml at or above the RESOLVED start_dir, read strictly, or None.

load_template

load_template(artifact_type) — the canonical body, or TemplateNotFound for an unregistered type. TemplateResourceMissing (a broken Python installation) has no Rust equivalent: embedded resources cannot be absent from a linked binary.

migrate_metadata

migrate_metadata(directory, dry_run, recursive) — prepend the canonical envelope to every recognized artifact without frontmatter, body bytes untouched. ANY frontmatter presence — valid, malformed, or unterminated — is already-canonical (validation owns broken envelopes); documents that do not classify are skipped-unknown.

quickstart

quickstart(directory, key, artifact_type) — validate the type first, refuse a non-empty corpus BEFORE any write, establish identity, then scaffold <dir>/decisions/<type>s/first-<type>.md.

render_frontmatter

render_frontmatter(artifact_id, artifact_type) — canonical generated envelope, stable key order (v0.7.11 contract).