Add Manifest-Driven Verbatim Tree Propagation

[ptr727]

Summary

Add a manifest-driven carry engine for wholesale hub content. Use the generated .github/skills/ tree as its first consumer.

The engine must copy declared content from a fetched ProjectTemplate checkout into a registered downstream worktree. It must also detect missing, modified, and extra downstream content.

Root Cause

GitHub Copilot code review reads skills from the pull request head branch. It cannot see skills installed on a maintainer's host or stored only in another repository.

ProjectTemplate keeps .agents/skills/ as its only hand-authored skill source. scripts/build_dist.py generates the complete .github/skills/ and Claude plugin distributions. Downstream repositories still need the GitHub distribution inside their own trees.

The fleet already declares carried files, applicability, and fidelity in spec/files.json. A generic tree carry extends that model without creating a skills-only propagation mechanism.

Architecture

Keep these responsibilities separate:

• scripts/build_dist.py transforms canonical skill sources into provider distributions inside ProjectTemplate.
• scripts/skills_install.py installs hub skills for local agents on a host.
• A new hub-hosted carry tool copies declared artifacts into downstream repository worktrees.
• spec/audit.py measures downstream fidelity against promoted hub main.
• Standup and resync decide when the carry tool applies changes.

The data flow is:

.agents/skills/
 |
 +-- build_dist.py --> .github/skills/
 | |
 | +-- carry tool --> downstream .github/skills/
 |
 +-- skills_install.py --> host-global agent installations

Manifest Model

Extend the fleet file specification with a whole-tree declaration. The final field names may follow the existing schema conventions, but the declaration must express this intent:

{
 "source": ".github/skills",
 "target": ".github/skills",
 "fidelity": "verbatim-tree",
 "appliesTo": "*",
 "include": ["**/*"],
 "prune": true
}

The model must support future wholesale hub content without embedding skill-specific behavior in the engine.

verbatim-tree means:

• Every included source file exists at the corresponding target path.
• File bytes match after only the normalization explicitly allowed by the fidelity model.
• No undeclared file or directory exists under a prune: true target.
• A source addition becomes required downstream.
• A retired source path is removed downstream.
• The target root exists even when the resolved source inventory is empty.

Reject overlapping declarations whose ownership or prune boundaries conflict.

Carry Tool Interface

Provide read-only and mutating modes from a hub checkout. The exact script name may follow repository naming conventions.

python3 scripts/carry.py check PhotoCleaner --target /path/to/worktree
python3 scripts/carry.py apply PhotoCleaner --target /path/to/worktree

check must report:

• The hub commit used as canonical input.
• The resolved repository name, types, and applicable declarations.
• Missing target files and directories.
• Modified target files.
• Extra paths inside pruned targets.
• Source and target digests for each declared tree.
• An unreadable or unsafe state as undecided or failed, never clean.

apply must print every path it creates, replaces, or removes. It must finish by running the same comparison used by check.

Write Safety

Before applying changes, the tool must:

1. Confirm it runs from a ProjectTemplate checkout fetched immediately before use.
2. Resolve the named repository through registry/repos.json.
3. Confirm the target origin matches the registry entry.
4. Confirm the target is not ProjectTemplate itself unless a declaration explicitly permits that case.
5. Confirm the target is an isolated feature-branch worktree based on the correct development branch.
6. Refuse unrelated target changes instead of overwriting or bundling them.
7. Resolve every source and target beneath its declared root before writing.
8. Reject symlinks in either tree rather than following them.
9. Restrict deletion to extra paths under an applicable prune: true target.
10. Preserve unrelated files outside declared target roots.

Use recoverable operations where practical. Never turn a failed read or comparison into an empty inventory.

Skills as the First Consumer

Carry the complete generated .github/skills/ distribution initially. Do not maintain a second manual allowlist.

Before fleet rollout, verify that every skill is safe when discovered downstream:

• Hub-context-only skills clearly prevent activation from the wrong context.
• Skills do not assume .agents/skills/ exists downstream.
• Sibling skill routing uses skill names or distribution-relative language.
• Bundled references and scripts travel with their parent skill.
• References to repository rules resolve through carried repository documents.
• Commands that require ProjectTemplate explicitly say to run from a separate hub checkout.

The carried .github/copilot-instructions.md must name only skill paths present in the same downstream head tree.

Standup, Resync, and Audit Integration

• Standup applies required tree declarations when establishing a repository baseline.
• Resync runs check, reads every modified-file diff, and applies the carry in procedure order.
• Audit classifies an absent tree as missing baseline and a stale tree as drift.
• Audit compares downstream ground-truth branches against fetched hub main.
• Retired tree content is removed only through the declaration's explicit prune authority.
• The registry and applicability model decide which repositories receive each tree.

Do not use the carried-instruction-file overwrite guard for a fully owned verbatim-tree. Apply an equivalent local-addition safeguard by reporting every extra path before pruning it.

CI and Freshness

Separate integrity from fleet freshness.

A required downstream pull request check may verify that the carried tree matches its recorded hub source commit. This proves the tree was not hand-modified.

Do not make unrelated downstream pull requests compare against the moving tip of hub main. A new hub commit must not break every open downstream pull request.

Use one or more of these mechanisms for freshness:

• A scheduled or manually dispatched conformance check against current hub main.
• Fleet audit from ProjectTemplate.
• Propagation pull requests opened when promoted carried content changes.

If a source stamp is used, it must identify the hub repository and exact commit. A stamp is evidence of provenance, not proof that the commit is current.

Required Tests

Test the carry engine against temporary hub and downstream trees. Cover at least:

• A clean verbatim tree.
• A missing target root.
• A missing file.
• A modified same-size file.
• An extra file and extra directory under a pruned target.
• A source addition.
• A retired source path.
• An empty source inventory whose target root must exist.
• A source or target symlink.
• A target outside the repository root.
• An overlapping or conflicting declaration.
• An inapplicable declaration selected by repository type.
• A mismatched target origin or registry identity.
• A dirty target carrying unrelated changes.
• A failed source read that must not appear clean.
• Idempotent apply followed by a clean check.
• Preservation of unrelated paths outside the declared target.

Add an integration fixture proving that every skill path named by downstream Copilot instructions exists in the resolved carried tree.

Acceptance Criteria

• .agents/skills/ remains the only hand-authored skill source.
• ProjectTemplate generates the complete .github/skills/ distribution.
• A generic manifest declaration owns the downstream .github/skills/ tree.
• The carry tool provides deterministic check and apply modes.
• Standup and resync use the carry tool rather than manual copying.
• Audit detects absent, stale, modified, and extra downstream skill content.
• Retiring a canonical skill removes it through explicit prune semantics.
• Downstream repositories contain every skill path their Copilot bootstrap names.
• Host-global skill installation continues unchanged.
• Required CI checks prove integrity without depending on moving hub main.
• A scheduled, audit, or propagation path reports fleet freshness.
• Documentation identifies the canonical source, generated artifacts, carried destinations, and ownership boundaries.

Relationship to #793 and PR #799

#793 defines the review behavior and output contract. PR #799 generates the complete Copilot-facing skill distribution in ProjectTemplate.

This issue owns the generic downstream carry mechanism and its first rollout for .github/skills/.

[ptr727]

Live evidence from PR #799 review 4955381803:

• Copilot read the pull request's .github/copilot-instructions.md well enough to describe the new review skill and marker in its overview.
• It did not load or attribute .agents/skills/code-review/SKILL.md.
• The review footer explicitly offered to create .github/skills/code-review/SKILL.md, which confirms the effective discovery gap this issue describes.

Use this review as the first reproduction artifact when selecting and testing the generated Copilot-facing destination.

[ptr727]

PR #799 implements the hub-side distribution mechanism at ced266c:

• .agents/skills/ remains the only hand-authored source.
• scripts/build_dist.py generates the complete skill set into both .github/skills/ and .claude-plugin/fleet-skills/skills/.
• build_dist.py --check compares both generated trees to the canonical source and rejects missing roots, missing or modified content, orphan skill directories, and stray root files.
• The Copilot bootstrap points to .github/skills/code-review/SKILL.md.

This issue remains open for downstream distribution after PR #799 merges. The downstream procedure must carry the generated .github/skills/ tree appropriate to each repository without creating a second hand-authored source.

[ptr727]

Resolved by squash merge 56be5ce in PR #804.