singularity-forge/docs/dev/ADR-022-scaffold-profiles.md

ADR-022: Scaffold Profiles

Status: Proposed Date: 2026-05-12 Deciders: Mikael Hugo Extends: ADR-021 — Versioned Documents and Upgrade Path

Context

ADR-021 introduced a per-file state machine (pending / editing / completed), version markers, drift detection, and an automatic upgrade pipeline for the SCAFFOLD_FILES template set. That set is a single flat list tuned for a code-app shaped repo.

When SF is bootstrapped into a non-code-shaped repo — infra, ops, GitOps, documentation-only — it writes ~60–70 % of templates that don't apply. Files like docs/FRONTEND.md, docs/DESIGN.md, and docs/PRODUCT_SENSE.md have no meaning in a Kubernetes config repo. They sit at state=pending forever, polluting the agent's scaffold context and producing spurious upgradable findings in /sf doctor on every run.

SF is being adopted in non-code repos. Each new repo type that doesn't fit the app profile creates the same friction without a general solution.

Decision

Introduce a profile system for scaffold file sets. A profile is a named subset of SCAFFOLD_FILES describing which templates apply to a given repo shape. Add a disabled state to the ADR-021 state machine for templates that are explicitly out-of-scope for the active profile.

1. Built-in profiles

Defined in scaffold-constants.js:

Profile	Included templates	Typical repo shape
app	Full SCAFFOLD_FILES list	Product or CLI with UI, tests, frontend
library	app minus docs/FRONTEND.md, docs/PRODUCT_SENSE.md, docs/DESIGN.md	Library, SDK, CLI tool without UI
infra	AGENTS.md, ARCHITECTURE.md, .siftignore, docs/SECURITY.md, docs/RELIABILITY.md, docs/records/, .sf/PRINCIPLES.md, .sf/STYLE.md, .sf/NON-GOALS.md, .sf/harness/	GitOps, Kubernetes, Flux, Helm, Terraform
docs	AGENTS.md, .sf/STYLE.md	Pure documentation repo
minimal	.siftignore, AGENTS.md	Any repo; smallest footprint

app is the default (preserves existing behaviour for code repos).

Profiles are expressed as sets of template paths from SCAFFOLD_FILES. The PROFILES object maps profile names to Set<string>. A file not in the active profile is treated as if it were absent from SCAFFOLD_FILES for all scaffold operations.

2. disabled state (4th ADR-021 state)

A new state alongside pending / editing / completed:

State	Definition	SF action on drift
disabled	Template does not apply to this repo. Written by migrate command or manually.	Never created. Never modified. Treated as out-of-scope.

The marker format is unchanged:

<!-- sf-doc: version=2.75.x template=docs/FRONTEND.md state=disabled hash=sha256:… -->

disabled is valid in VALID_STATES. Any existing code path that calls parseMarker on a disabled file will parse it correctly (not fall through to untracked).

State derivation (extends ADR-021 §1 table)

Marker?	state field	Body hash = marker.hash?	→ State
yes	disabled	any	disabled
(existing ADR-021 rows)	…	…	…

What disabled means for drift detection

• Files with state=disabled → disabled drift bucket. Never missing, upgradable, or editing-drift.
• Files not in the active profile that don't exist on disk → skipped entirely. Not reported as missing. SF does not write them.
• /sf doctor does not count disabled files as actionable. The doctor finding counts only missing + upgradable + editing-drift.

3. Profile storage

Profile is stored in .sf/scaffold-manifest.json under a new profile field. Added additively — no schemaVersion bump (a bump would wipe existing applied records on first upgrade).

{
  "schemaVersion": 1,
  "profile": "infra",
  "applied": [ … ]
}

readScaffoldManifest returns profile: parsed.profile ?? null. recordScaffoldApply preserves the profile field on every write (prior implementation stripped all fields beyond schemaVersion + applied).

4. Profile auto-detection

detectRepoProfile(basePath) returns the best-fit built-in profile for a repo it has never seen before. Runs once on first scaffold; result stored in manifest.

Detection logic (uses repo-profiler.js / detectStacks() as signal source):

Signal	→ Profile
kustomization.yaml, flux-system/, Chart.yaml, or helmrelease.yaml at root	infra
flake.nix / shell.nix (nix stack) with no package.json	infra
package.json with UI framework dep (next, vite, remix, sveltekit, @sveltejs/kit, nuxt)	app
package.json without UI framework dep	library
Cargo.toml, go.mod, or pyproject.toml	library
No source files, only .md docs	docs
No matching signals	app (default)

Signals are evaluated top-to-bottom; first match wins. The manifest profile field overrides auto-detection on all subsequent runs (explicit beats inferred).

ensureAgenticDocsScaffold reads the active profile from the manifest (or auto-detects it on first run) and filters SCAFFOLD_FILES to only those paths in the active profile before writing any files.

5. sf scaffold migrate --profile <name> [--prune]

Manual command for repos already bootstrapped under the wrong profile.

sf scaffold migrate --profile infra [--prune]

Algorithm:

1. Read existing markers + manifest. Validate target profile name.
2. Re-enable step — for each file IN the target profile with state=disabled on disk:
   • If bodyHash(body) === marker.hash (no user edits since disable): re-stamp state=pending.
   • If hash diverged (user edited the disabled file): warn, leave disabled.
3. Disable step — for each file NOT in the target profile:
   • Compute bodyHash(body) from on-disk content.
   • If state=pending AND bodyHash(body) === marker.hash (no user edits): re-stamp state=disabled.
   • If state=pending AND hash diverged: treat as editing-drift — warn, leave alone. (User has edits; SF will not silently disable them.)
   • If state=editing or state=completed: warn, leave alone.
   • If --prune AND state=pending AND bodyHash(body) === marker.hash: delete the file. The same hash guard applies — prune never deletes user-edited files.
4. Update scaffold-manifest.json profile field to target profile.
5. Run drift-aware sync for files in the new profile (applies missing and upgradable items).

Migrate is idempotent: running it twice produces the same result.

6. Profile precedence

Multiple sources may specify a profile. Precedence (highest first):

1. PREFERENCES.md frontmatter — sf_profile: infra (Phase 5; explicit user override, per-repo, committed to git)
2. Manifest profile field — set by migrate or first-run auto-detection (per-repo runtime, gitignored)
3. Auto-detection — detectRepoProfile(basePath) result (fallback)

This rule is defined now so Phase 5 (custom profiles) has a clear contract.

7. Custom profiles (Phase 5)

Future work. Custom profiles extend built-ins:

# ~/.sf/profiles/monorepo.yaml
extends: library
add:
  - docs/DESIGN.md
remove:
  - docs/exec-plans/active/index.md

Resolved at profile load time. Phase 5 must document how PREFERENCES.md frontmatter references a custom profile name (precedence rule §6 already establishes where they fit).

Implementation Phases

Phase	Scope	Constraint
1	PROFILES constant; disabled in VALID_STATES; manifest profile field round-trip fix	Must ship atomically with Phases 2 and 4
2	Profile-aware detectScaffoldDrift; disabled bucket; profile-filtered migrateLegacyScaffold; update 3 unlisted callers; doc-checker.js fix	Must ship atomically with Phases 1 and 4
3	detectRepoProfile; profile-filtered ensureAgenticDocsScaffold	Depends on Phases 1 + 2
4	sf scaffold migrate --profile <name> [--prune] command	Must ship atomically with Phases 1 and 2
5	Custom profiles (~/.sf/profiles/*.yaml); PREFERENCES.md frontmatter	Depends on Phase 4

Phases 1 + 2 + 4 must ship in the same release. The disabled state is not parseable by parseMarker until Phase 1 lands; any code that stamps disabled before Phase 1 ships causes affected files to fall into the untracked bucket and be silently re-rendered on the next ensureAgenticDocsScaffold call.

Consequences

Becomes possible

• SF can be bootstrapped into any repo shape without laying down irrelevant templates.
• Existing over-scaffolded repos can be cleaned up with a single migrate command.
• Profile auto-detection removes the need for explicit sf new-project --profile infra flags in the common case.
• disabled state is a clean per-file escape hatch without forking the profile.

Becomes harder

• Profile set and SCAFFOLD_FILES must stay in sync; a template added to SCAFFOLD_FILES needs explicit placement in every affected built-in profile.
• detectRepoProfile heuristics will misclassify hybrid repos (a repo with both package.json and kustomization.yaml). Fallback is app; migrate exists for correction.

Failure modes

Failure	Behaviour
Unknown profile name in manifest	Fall back to app; log warning.
detectRepoProfile misclassifies repo	User runs sf scaffold migrate --profile <correct>. One-time correction.
Hash divergence on a disabled file during migrate	Warn; leave alone. User must manually resolve or mark completed.
Manifest profile field missing (pre-ADR-022 manifest)	null → fall back to auto-detection on next scaffold run.

Alternatives Considered

Alternative	Why rejected
Per-file applicable: false flag in SCAFFOLD_FILES	Static; can't adapt to different repo shapes without forking the array.
Delete out-of-profile files on migrate	Destructive for editing/completed files; disabled with --prune for pending is safer and reversible.
Auto-migrate on every startup	Surprising; migrate is an explicit user action that changes profile context. Auto-detection for first scaffold only.
Single minimal profile as the new default	Breaks existing repos; app as default preserves current behaviour.

References

• ADR-021 — Versioned Documents and Upgrade Path (§1 state machine, §3 manifest, §4 drift detection, §7 legacy migration — all extended here)
• src/resources/extensions/sf/repo-profiler.js — detectStacks() signal source for detectRepoProfile