Maintain Project Repo

Maintain Project Repo

Purpose

Install one repo-owned F# script runtime behind a small just interface. The runtime owns repository validation, shared-asset synchronization, canonical documentation, and bounded protected-main release operations.

Required Interface

Run repository work through just. Documentation has exactly two public commands and both always process README.md, CONTRIBUTING.md, AGENTS.md, and ROADMAP.md as one transaction:

just docs-check
just docs-apply

The remaining managed commands are:

just repo-validate
just repo-sync
just repo-release-prepare <version>
just repo-release-inspect <version>
just repo-release-advance <version>

Never add per-document recipes, direct operator-facing script commands, Python or shell implementations, compatibility wrappers, or alternate documentation modes.

Installation Workflow

1. Confirm the target is the repository root and select generic or xcode-workspace explicitly.
2. Use scripts/maintain-project-repo.fsx from this skill for install, refresh, or report-only.
3. Install the fixed manifest under scripts/repo-maintenance/, the managed Just import, and the GitHub validation workflow.
4. Install or refresh the four documentation contracts and templates.
5. Run the full documentation transaction: apply for install/refresh and check for report-only.
6. Run the target repository's just repo-validate after mutation.

The installer preserves repo-owned files outside the managed manifest. It does not infer profiles, accept project-local schemas, or expose skip-docs behavior.

Documentation Contract

The four document-owner skills provide fixed JSON contracts and Markdown templates. maintain-project-docs.fsx loads all four in a fixed order, audits responsibility boundaries, plans every change before writing, applies writes atomically, and verifies the result. Apply is idempotent.

Customization is intentionally narrow: repositories supply their substantive project content inside the canonical sections. They cannot customize document names, required headings, aliases, ordering, status vocabulary, normalization, or fix policy.

Managed Layout

scripts/repo-maintenance/
  maintain-project-docs.fsx
  repo-maintenance.fsx
  repo-maintenance.just
  managed-assets.json
  docs/
  validations/
  syncing/
  version-bump.fsx             # optional repo-owned release hook
.github/workflows/
  validate-repo-maintenance.yml

Ordered validation and synchronization hooks are .fsx files. The runtime discovers them lexically and invokes them through dotnet fsi. Hook filenames and arguments are the extension boundary; there is no persistent policy file.

Validation and Synchronization

• just repo-validate verifies the managed manifest and Just import, then runs every root-owned validation hook.
• just repo-sync runs every root-owned synchronization hook and then validates.
• CI calls just repo-validate; it does not duplicate repository policy.
• End-to-end tests live only at the target repository root. Do not install or retain nested test suites inside skills or managed directories.

Release Workflow

Use the standard protected-main path only when the user asks to release:

1. repo-release-prepare validates, performs the repo-owned version bump, checks release notes, commits the release branch, pushes it, and creates or updates its PR.
2. repo-release-inspect checks the saved branch, commit, PR, checks, reviews, comments, base branch, and tag identities without polling.
3. repo-release-advance repeats identity checks, merges only when every gate passes, updates the owning main worktree, tags, pushes, creates the GitHub release, and performs branch accounting.

Prerelease SemVer tags create GitHub prereleases. Checked-in notes under docs/releases/ are preferred. Never delete branches, worktrees, refs, or release state until every unmerged branch is explicitly accounted for.

Guards

• Treat repository-skills 10.0.2 as the migration baseline; do not copy behavior from an earlier installed version.
• Stop when a managed target is not a regular file or when both legacy and canonical toolkit roots exist.
• Stop on unsupported profiles, operations, hook extensions, release states, or document contract violations.
• Do not write repository-local Git defaults.
• Do not add Python, shell, YAML customization, per-file documentation commands, nested tests, or transitional duplicate paths.

References

• references/document-boundaries.md
• references/repo-maintenance-layout.md
• references/release-modes.md
• references/pre-commit-vs-ci.md
• references/automation-prompts.md
• references/project-docs-maintenance-automation-prompts.md

Script Inventory

• scripts/maintain-project-repo.fsx
• scripts/maintain-project-docs.fsx