Skip to content

MULTI-REPOSITORY-SCOPE-STANDARD.adoc

Latest commit

 

History

History
109 lines (83 loc) · 4.94 KB

MULTI-REPOSITORY-SCOPE-STANDARD.adoc

File metadata and controls

109 lines (83 loc) · 4.94 KB
Raw

Multi-Repository Scope Standard

Table of Contents

Status: Draft for review.

Purpose

This standard defines how a human or automated agent declares the repositories covered by a task spanning multiple Git repositories. It separates three things that are often conflated:

  • a standard states how work is to be done;

  • an estate declaration identifies a maintained collection of repositories;

  • a task scope authorizes a bounded operation on a subset of that collection.

A repository being listed in an estate, visible to a bot, or governed by a standard does not by itself authorize changes to it.

Normative language

The terms MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY express requirements in their ordinary standards sense.

Scope declaration requirements

Every multi-repository task MUST identify:

  1. the requested operation and its purpose;

  2. the estate declaration(s) used to resolve repository membership, with a revision, digest, or other reproducible version where available;

  3. the exact target set, or a deterministic selector and its resolved target list before writes;

  4. allowed actions, such as read, report, propose, or write;

  5. explicit exclusions and any repositories whose status cannot be established;

  6. the human authority for approval and the route for reporting results.

A task targeting repositories across multiple organizations MUST name each organization or estate separately. In the Hyperpolymath context, the two relevant estates are hyperpolymath and metadatastician; a request to cover "both estates" MUST name both. Neither estate is implied by the other. The word "all" is not a sufficient scope expression unless it is expanded to a concrete, reviewable set before any write.

Membership and identity

Repository identity MUST use the canonical hosting service and owner/name (for GitHub, github.com/OWNER/REPOSITORY). Local checkout paths, directory names, old names, and Git remote strings are hints, not canonical identity. Renames MUST be resolved before deduplication or reporting.

Estate membership MUST have a source and an observation time or revision. A census, dashboard, board, or search result can inform membership but MUST NOT silently be treated as a complete authoritative inventory. Membership records SHOULD distinguish at least: live, archived, deleted/unavailable, third-party/vendor, renamed/redirected, and unknown/unmeasured. Unknown status is reported as unknown, never silently converted to included or excluded.

Permissions and execution

The default agent authority is read and report. An agent MUST NOT infer write permission from a standard, estate membership, prior task, repository access, or successful authentication.

Before a batch write, the agent MUST present (or otherwise obtain human approval for) the resolved repository list, proposed changes, exclusions, and rollback or recovery approach. Approval MUST cover the listed repositories and action; material scope changes require renewed approval. An explicit task MAY authorize writes without a separate prompt when it already names the targets and action.

Agents MUST use a dry run or proposal phase where practicable, operate on one repository at a time or in bounded batches, and record per-repository outcomes. A failure or permission gap in one repository MUST NOT be represented as success for the estate. Partial completion MUST be reported as partial.

Agents MUST NOT:

  • expand scope by guessing that similarly named repositories belong to the set;

  • write to archived, deleted, vendor, or unknown-status repositories unless explicitly authorized;

  • change repository settings, protections, secrets, permissions, or governance merely because code changes were authorized;

  • conceal skipped targets, errors, or uncertainty in aggregate totals.

Reporting

A multi-repository result SHOULD include the scope source and revision, time of observation, resolved canonical target list, action attempted, per-target outcome, skipped targets with reasons, and any remaining uncertainty. Reports MUST distinguish not checked, checked and clean, changed, failed, and not applicable.

Minimal machine-readable declaration

The companion docs/repo-scope.example.toml is an illustrative template, not a live inventory or grant of authority. Copy it into a task or orchestration context, replace placeholders, and resolve selectors to an explicit target list before writes. Keep secrets and credentials out of scope declarations.

Adoption and limits

This document is a draft proposal for repository-set and task-scope handling. It does not define GitHub permissions, discover every repository in an organization, or make an agent’s tooling safe by itself. Each adopting project must identify its authoritative membership source and human approval authority. A validator can check declaration shape; only the responsible human can decide whether the target set and proposed action are appropriate.