FS.GG.Drivers 0.109.0

FS.GG.Drivers

The .github-authored driver skill bytes (scope: driver) as one versioned package.

.github authors a product-materialized skill class (ADR-0054) — a skill that runs inside a scaffolded product tree, not in .github itself. The first is work-roadmap (ADR-0053/#1224). This package is how those bytes reach a scaffold.

Why a package

fsgg-sdd scaffold runs on an offline inner loop, and generic SDD is contractually barred from embedding any cross-repo path or source (FS.GG.SDD/CLAUDE.md, scaffold FR-002/SC-005). So the SDD CLI cannot reach into .github at scaffold time. Instead:

1. .github publishes the driver bytes + driver-skill-manifest.json as this versioned package (ADR-0054 §Byte-transport, resolving #1300).
2. FS.GG.SDD.Cli pins it and restores it at CLI build/publish time — online.
3. At scaffold time — offline — the CLI materializes the driver into the product tree's skill roots from the bytes it already carries, verifying each against the manifest sha256 (ADR-0014).

This is the ADR-0062 FS.GG.Kit pattern, one consumer over (SDD CLI → scaffolds, not Renovate → framework repos), and the delivery substrate ADR-0063 directs owner-authored skills onto.

What it ships

drivers/driver-skill-manifest.json     the delivered set + whole-directory manifests
drivers/skills/<id>/<relative-path>    every file for each `scope: driver` row (e.g. work-roadmap)
workspace/workspace-files.json         closed manifest of repository-root routine delivery files
workspace/files/<path>                 exact owner bytes at their repository-relative destinations
build/FS.GG.Drivers.props              a consumer handle: $(FsggDriversContentDir) → the content root

Only scope: driver rows carry bytes. A scope: operator row (ADR-0057, e.g. drive-board) is .github-authored but materialized nowhere, so it is listed in the manifest (the emitter's single output) but its bytes are deliberately not delivered — its materializes-when: false gates it out of every tree.

Consuming it

There is no consumer materialize target in this package, by design: the materialize is the SDD CLI's, at scaffold time. build/FS.GG.Drivers.props exposes $(FsggDriversContentDir) so the CLI's build can locate the packed bytes; the CLI reads driver-skill-manifest.json, and for each row whose materializes-when holds, lays the complete skills/<id>/ directory into the scaffold's skill roots and verifies its file set, bytes, and executable modes against the recorded sha256. See ADR-0063 for the materializer design.

The same props file exposes $(FsggDriversWorkspaceContentDir) for the repository-root payload. Its manifest is generated from workspace-inventory.json at pack time, directly from the owner files. It records a sorted, closed set of destination paths, raw SHA-256 values, and executable bits. A receiver must validate the complete set before writing, preserve existing files on any collision, and then materialize files/<path> at that exact repository-relative path.

Deriving, not restating

The delivered set lives in exactly one authored place — registry/driver-skill-manifest.json, emitted by scripts/generate-driver-manifest from the authored SKILL.md bodies (ADR-0058). stage-drivers.py reads that manifest at pack time and stages exactly its scope: driver rows; a driver added or retired needs no edit to this package. verify-package.sh proves the packed set derives from the manifest, packs every driver member, and fails loud on a byte that does not match its recorded sha256.

Atlas guidance adoption

The driver payload carries the Atlas skill/helper, its authored references/root-guidance.md, and the historical seed. The existing workspace transport carries .fsgg/atlas.json, the optional .fsgg/owner-guidance.json descriptor, and .fsgg/atlas-guidance.md. The fragment is staged directly from the authored reference; the helper reads that same reference rather than maintaining another prose copy.

The descriptor uses fsgg.owner-guidance/1 and declares an atlas block for the claude and codex agent IDs. Its required paths identify the policy and both skill-root copies of the Atlas skill, helper and reference. A compatible generic SDD receiver verifies those selected owner bytes before merging the fragment into the root agent files. Existing / markers keep the manual and automatic routes aligned. The descriptor contains no executable hook and changes no workspace-manifest version.

Check agreement from the receiving repository root with python3 .agents/skills/atlas/scripts/atlas.py guidance --root . --check. An authorized manual update omits --check and preserves instructions outside the marked blocks. A compatible receiver activates during ordinary scaffold, reports drift through read-only doctor, and repairs retained blocks through confirmed upgrade. These are receiver obligations, not proof supplied by staging: producer publication, compatible receiver publication and exact installed fresh/retained readback remain separate acceptance outcomes. Older receivers retain their existing behavior, and knowledgePolicy alone does not activate guidance.

Owner workflow entrypoints such as work-roadmap route investigation through Atlas. Preserve the generic SDD product Knowledge API and its records: Atlas stores curated project knowledge with citations, while a packaged seed is historical knowledge and grants no current operational authority.