singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
singularity-forge/docs/dev/generated-artifact-policy.md
Mikael Hugo 55e7dd0e02 fix: clean generated harness residue
2026-05-05 15:04:34 +02:00

1.3 KiB
Raw Blame History

Generated Artifact Policy

SF keeps operational generated artifacts out of the project root unless a human explicitly promotes them into durable project documentation.

Default Locations

  • .sf/ stores SF-local operational state, generated harness notes, scaffold manifests, runtime caches, locks, and temporary agent files.
  • docs/plans/, docs/specs/, and docs/adr/ store promoted, reviewed, durable project artifacts.
  • Root files such as AGENTS.md, ARCHITECTURE.md, and .siftignore are allowed only when they are part of the versioned scaffold contract.

Harness

Generated harness material belongs under .sf/harness/.

Top-level harness/ is not created by SF by default. If a project intentionally owns a top-level harness, SF leaves it alone unless the files still carry pending sf-doc markers proving they are old SF-generated residue.

Doctor Cleanup

/sf doctor --fix may remove root-level generated residue only when all of the following are true:

  • the file is under a legacy SF-generated path such as harness/specs/;
  • the file has an sf-doc marker;
  • the marker template matches the file path;
  • the marker state is pending;
  • the current body hash still matches the marker hash.

Anything edited, completed, unmarked, or project-owned is reported conservatively or left untouched.