Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions .agents/policy-selector-install.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,22 @@
"install_relpath": ".agents/skills/repo-policy-selector",
"installed_bundle_release": {
"bundle_name": "repo-policy-selector",
"bundle_version": "0.1.22",
"bundle_version": "0.1.26",
"policy_library": {
"catalog_path": "policy-library/catalog.yaml",
"content_sha256": "03d4cba5d1aaad7ca2805b847dd69083ebf4193b8812693ee7ea8d9079f56b42",
"content_sha256": "1129e37be16efbf571954f80d06ea7115eb8f244acbd327003abe37e2dadaa96",
"relative_root": "policy-library",
"schema_path": "policy-library/SCHEMA.md"
},
"release_ref": "v0.1.22",
"release_ref": "v0.1.26",
"schema_version": 1,
"source_commit": "12a7f9fef466522e99be44d980c44a4ff056f540",
"source_ref": "12a7f9fef466522e99be44d980c44a4ff056f540",
"source_commit": "ead42f7d6932fedc9dea83111b234f954a6afa4d",
"source_ref": "ead42f7d6932fedc9dea83111b234f954a6afa4d",
"source_repo_root": "/home/ecochran76/workspace.local/agent-policies",
"source_tree_state": "clean-ref"
},
"installed_policy_root": "/home/ecochran76/workspace.local/dev-browser-policy-adoption/.agents/skills/repo-policy-selector/policy-library",
"installed_selector_root": "/home/ecochran76/workspace.local/dev-browser-policy-adoption/.agents/skills/repo-policy-selector",
"selector_root": "/home/ecochran76/.agents/skills/repo-policy-selector",
"installed_policy_root": "/home/ecochran76/workspace.local/dev-browser-skill-hygiene/.agents/skills/repo-policy-selector/policy-library",
"installed_selector_root": "/home/ecochran76/workspace.local/dev-browser-skill-hygiene/.agents/skills/repo-policy-selector",
"selector_root": "/tmp/dev-browser-policy-upgrade-v0126/repo-policy-selector",
"source_type": "local-path"
}
24 changes: 19 additions & 5 deletions .agents/skills/repo-policy-selector/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,16 +38,21 @@ Select the right reusable policy bundle for a repository, then adapt it into rep
and unused baseline entries. Use `--force` only for pre-adoption assessment;
active baselines never apply to full or forced audits.
10. If the repo adopts `goal-execution-governance`, run `scripts/audit_planning_contract.py --goal-only` and require concrete local bounds, execute-by-default continuation, action-specific approval gates, local replan before escalation, at-most-one risk-triggered drift-discovery pass, closed-world verification when review occurs, and minimal material-checkpoint fields.
11. If the repo adopts `active-lane-coordination`, refresh remote-tracking refs through its normal fetch policy and run `scripts/audit_active_lanes.py` with an explicit default ref. Prefer `--catalog-only` when the catalog is the complete authorized population; use repeated exact `--branch` selectors for bounded unregistered-lane discovery and reserve `--branch-prefix` for explicit broader surveys. Treat missing, unequal, or contradictory custody as a fail-closed planning input, not as permission for the auditor to mutate Git.
12. Validate that the recommended profile and modules exist in the installed library bundle before drafting changes.
13. Read the referenced policy modules from this policy library before drafting changes.
14. Decide whether the repo needs:
11. If the repo adopts `active-lane-coordination`, refresh remote-tracking refs through its normal fetch policy and run `scripts/audit_active_lanes.py` with an explicit default ref. Prefer `--catalog-only` when the catalog is the complete authorized population; use repeated exact `--branch` selectors for bounded unregistered-lane discovery and reserve `--branch-prefix` for explicit broader surveys. Treat missing, unequal, or contradictory custody as a fail-closed planning input, not as permission for the auditor to mutate Git. When `work-item-traceability` is adopted, migrate lane locators before setting catalog `work_item_tracking: required`.
12. If the repo adopts `forge-issue-reporting`, require an explicit target
registry and run `scripts/preflight_forge_issue.py` before any proposed
provider mutation. Treat its output as read-only capability and
configuration evidence, not write authority. Validate normalized labels
against exact provider labels and keep label creation separate.
13. Validate that the recommended profile and modules exist in the installed library bundle before drafting changes.
14. Read the referenced policy modules from this policy library before drafting changes.
15. Decide whether the repo needs:
- a starter profile with minimal edits
- a profile plus module overrides
- a missing-modules patch when the repo already partially or mostly matches the selected profile
- a migration-first adoption because plans, notes, or memories are cluttered
- a custom composition because no single profile fits cleanly
15. Draft the repo-local policy patch or recommendation, keeping the adopted policy in `docs/dev/policies/` and using `AGENTS.md` as the wire-in entrypoint.
16. Draft the repo-local policy patch or recommendation, keeping the adopted policy in `docs/dev/policies/` and using `AGENTS.md` as the wire-in entrypoint.

## Required references

Expand Down Expand Up @@ -81,6 +86,8 @@ python scripts/audit_active_lanes.py --repo-root /path/to/repo --default-ref ref
python scripts/audit_active_lanes.py --repo-root /path/to/repo --default-ref refs/remotes/origin/main --catalog-only --json
python scripts/audit_active_lanes.py --repo-root /path/to/repo --default-ref refs/remotes/origin/main --branch feature/lane-a --branch fix/lane-b --json
python scripts/audit_active_lanes.py --repo-root /path/to/repo --default-ref refs/heads/main --catalog-path docs/dev/active-lanes.yaml --plans-dir docs/dev/plans
python scripts/preflight_forge_issue.py --registry /path/to/repo/docs/dev/forge-issue-targets.json --target <target-id> --action create --label intent/defect --idempotency-key <stable-key>
python scripts/preflight_forge_issue.py --registry /path/to/repo/docs/dev/forge-issue-targets.json --target <target-id> --action create --idempotency-key <stable-key> --snapshot /path/to/provider-snapshot.json
```

## Guardrails
Expand All @@ -94,4 +101,11 @@ python scripts/audit_active_lanes.py --repo-root /path/to/repo --default-ref ref
- Downstream install should support a one-shot path that copies a pinned selector bundle into the target repo from either a reviewed git ref or a local bundle path and can draft the initial local policy set immediately.
- Released selector bundles should carry a deterministic `release-manifest.json` next to the bundled `policy-library/`.
- `audit_active_lanes.py` is read-only. It never fetches or performs Git, catalog, plan, worktree, branch, or remote mutations; a clean report never grants integration or cleanup authority.
- `preflight_forge_issue.py` is read-only. It may authenticate and query an
explicitly registered GitHub or GitLab target, but it never creates or
mutates issues, labels, assignments, milestones, projects, boards, or work
items. A clean result never grants mutation authority.
- Preflight JSON always reports `operator_authority_verified: false` and
`mutation_authorized: false`; the caller must establish those gates outside
the read-only tool for the exact requested action.
- Treat the policy library as a source library, not the runtime source of truth for the target repo.
132 changes: 117 additions & 15 deletions .agents/skills/repo-policy-selector/policy-library/SCHEMA.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,30 +119,42 @@ optional outside repositories with concurrent projects, branches, or worktrees.
The catalog uses `schema_version: 1` and a `lanes` list. Every lane requires:

```yaml
- id: P42
objective: Carrier reconciliation
plan: docs/dev/plans/0042-YYYY-MM-DD-carrier-reconciliation.md
plan_ref: refs/heads/feature/p42-carrier-reconciliation
branch: feature/p42-carrier-reconciliation
target: main
plan_state: OPEN
custody_state: ACTIVE_WORKTREE
checkpoint: <full-commit-sha>
remote_ref: refs/remotes/origin/feature/p42-carrier-reconciliation
integration: merge
dependencies: []
overlaps: []
updated_at: YYYY-MM-DD
schema_version: 1
work_item_tracking: required
lanes:
- id: P42
objective: Carrier reconciliation
work_items: [owner/repo#42]
plan: docs/dev/plans/0042-YYYY-MM-DD-carrier-reconciliation.md
plan_ref: refs/heads/feature/p42-carrier-reconciliation
branch: feature/p42-carrier-reconciliation
target: main
plan_state: OPEN
custody_state: ACTIVE_WORKTREE
checkpoint: <full-commit-sha>
remote_ref: refs/remotes/origin/feature/p42-carrier-reconciliation
integration: merge
dependencies: []
overlaps: []
updated_at: YYYY-MM-DD
```

Optional fields include `reconciled_overlaps`, `validation_status`,
`work_item_tracking` is optional and accepts `optional` or `required`; omitted
catalogs behave as `optional` for backward compatibility. When it is
`required`, every lane needs a non-empty inline `work_items` list. Locators are
opaque, compact, non-secret identifiers; the auditor validates shape and
presence without querying a provider.

Optional fields include `work_items`, `reconciled_overlaps`, `validation_status`,
`validation_ref`, `integration_receipt`, `archive_ref`, `archive_remote_ref`,
`blocker`, and `disposition`. Lists use inline YAML form in schema version 1 so
the bundled dependency-free auditor can parse them deterministically.

Rules:

- lane ids and branch ownership are unique
- `work_item_tracking: required` makes a non-empty `work_items` list mandatory
for every lane
- plan states are `PLANNED`, `OPEN`, `BLOCKED`, `CLOSED`, or `CANCELLED`
- custody states are `ACTIVE_WORKTREE`, `PAUSED_REF`, `INTEGRATION_READY`,
`INTEGRATED`, `ARCHIVED`, or `DISCARD_APPROVED`
Expand All @@ -164,6 +176,96 @@ Rules:
`remote_ahead_of_local`, or `local_remote_diverged` when both tips exist but
are unequal

## Forge Issue Target Contract

Repos that adopt `forge-issue-reporting` should keep an explicit, non-secret
target registry at `docs/dev/forge-issue-targets.json` or a documented
equivalent. JSON is the canonical interchange format for the dependency-free
preflight; another source format may be used only when it deterministically
renders the same object.

The registry uses `schema_version: 1` and a `targets` list:

```json
{
"schema_version": 1,
"targets": [
{
"id": "odollo-github",
"forge": "github",
"host": "github.com",
"repository": "example/odollo",
"relationship": "owned",
"allowed_actions": ["read", "create", "comment", "apply_labels", "close"],
"security_route": "private_vulnerability_reporting",
"label_map": {
"intent/defect": {"provider_label": "bug"},
"priority/high": {"provider_label": "priority: high"}
}
},
{
"id": "litscout-gitlab",
"forge": "gitlab",
"host": "gitlab.example.com",
"repository": "research/tools/litscout",
"relationship": "permissioned",
"allowed_actions": ["read", "create", "comment", "apply_labels"],
"security_route": "confidential_issue",
"label_map": {
"intent/defect": {"provider_label": "type::bug"}
}
}
]
}
```

Required target fields are `id`, `forge`, `host`, `repository`,
`relationship`, `allowed_actions`, `security_route`, and `label_map`.

Rules:

- target ids are unique and stable
- `forge` is `github` or `gitlab`
- `host` is explicit even for GitHub.com or GitLab.com
- GitHub repositories use `OWNER/REPO`; GitLab repositories allow
`GROUP/SUBGROUP/PROJECT`
- `relationship` is `owned` or `permissioned`; it expresses intended operating
scope and is not current provider-permission evidence
- allowed actions come from `read`, `create`, `comment`, `edit`,
`apply_labels`, `create_labels`, `assign`, `milestone`, `planning`, `close`,
`reopen`, and `transfer`
- normalized label keys are repo-local intent vocabulary; each maps to one
exact existing provider label
- applying labels and creating labels are separate actions; missing mapped
labels fail preflight and are not created during issue creation
- security routes are `private_vulnerability_reporting`, `security_policy`,
`private_contact`, `confidential_issue`, or `none`; `none` cannot authorize a
security report
- registries contain no credentials, tokens, vulnerability details, private
customer data, or inferred lists of every accessible repository
- registry membership, provider role, and operator authority remain separate
gates

The read-only preflight snapshot schema is intentionally small:

```json
{
"forge": "github",
"host": "github.com",
"repository": "example/odollo",
"authenticated_actor": "reporter-login",
"effective_role": "TRIAGE",
"issues_enabled": true,
"archived": false,
"available_labels": ["bug", "priority: high"],
"duplicate_candidates": []
}
```

Snapshots are evidence inputs for deterministic validation, not reusable
proof of current live capability. Live mutations require a fresh provider
readback.

## Module Contract

Modules live under `modules/*.md`.
Expand Down
21 changes: 21 additions & 0 deletions .agents/skills/repo-policy-selector/policy-library/catalog.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,21 @@ modules:
- id: active-lane-coordination
path: modules/active-lane-coordination.md
tags: [git, planning, worktrees, coordination]
- id: work-item-traceability
path: modules/work-item-traceability.md
tags: [issues, planning, traceability, flow, governance]
- id: collaborative-development-workflow
path: modules/collaborative-development-workflow.md
tags: [collaboration, contributors, pull-requests, git, deployment]
- id: forge-issue-reporting
path: modules/forge-issue-reporting.md
tags: [issues, github, gitlab, reporting, governance]
- id: github-issue-operations
path: modules/github-issue-operations.md
tags: [github, issues, labels, permissions, security]
- id: gitlab-issue-operations
path: modules/gitlab-issue-operations.md
tags: [gitlab, glab, issues, labels, permissions]
- id: commit-history-discipline
path: modules/commit-history-discipline.md
tags: [git, commits, history, review]
Expand Down Expand Up @@ -80,6 +95,9 @@ modules:
- id: subagent-workflow-optimization
path: modules/subagent-workflow-optimization.md
tags: [agents, delegation, subagents, optimization]
- id: model-selection-and-calibration
path: modules/model-selection-and-calibration.md
tags: [agents, models, calibration, allocation, evaluation]
- id: subagent-runtime-governance
path: modules/subagent-runtime-governance.md
tags: [agents, subagents, runtime, governance]
Expand Down Expand Up @@ -125,6 +143,9 @@ modules:
- id: tenant-isolation-and-operator-state
path: modules/tenant-isolation-and-operator-state.md
tags: [tenant, runtime, isolation, operations]
- id: development-runtime-isolation
path: modules/development-runtime-isolation.md
tags: [runtime, development, isolation, environments, safety]
- id: fieldwork-productization
path: modules/fieldwork-productization.md
tags: [fieldwork, productization, operations, migration]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,37 @@ tags:
- Use this contract in repositories where several projects, agents, branches, or worktrees may remain active at once. Keep lighter repositories on proportional planning and Git policy without requiring a lane catalog.
- Keep a compact machine-readable active-lane catalog on the canonical default branch, normally `docs/dev/active-lanes.yaml`. A documented equivalent path is allowed.
- Treat the catalog as a discovery projection. A roadmap owns priority, a branch-local plan owns execution detail, a runbook owns chronological history, review tooling owns review state, and Git refs plus receipts prove custody and integration.
- Give each lane one stable id and one branch owner. Record its objective, plan path and source ref, branch, target, plan state, custody state, published checkpoint, remote ref, integration method, dependencies, overlaps, reconciliation date, and any blocker or disposition.
- Give each lane one stable id and one branch owner. Record its objective, work-item locators when work-item tracking is adopted, plan path and source ref, branch, target, plan state, custody state, published checkpoint, remote ref, integration method, dependencies, overlaps, reconciliation date, and any blocker or disposition.
- Give each substantive lane one accountable execution owner. When several lanes
depend on shared schemas, roadmaps, catalogs, or other integration surfaces,
name one coordination owner for those surfaces instead of allowing every lane
to edit them independently. A person or session may fill more than one role
when the portfolio is small and the ownership remains unambiguous.
- Keep plan outcome state separate from Git custody state. Use a small plan vocabulary such as `PLANNED`, `OPEN`, `BLOCKED`, `CLOSED`, and `CANCELLED`, and a custody vocabulary such as `ACTIVE_WORKTREE`, `PAUSED_REF`, `INTEGRATION_READY`, `INTEGRATED`, `ARCHIVED`, and `DISCARD_APPROVED`.
- Keep detailed plans with their topic branches. Expose deterministic metadata for lane, state, branch, target, integration method, dependencies, overlaps, and base or checkpoint evidence so an auditor can read it from an explicit ref without checkout.
- Do not put absolute worktree paths, ephemeral agent identifiers, secrets, tenant data, or private runtime details in the shared catalog. Derive local worktree locations during reconciliation.
- Keep work-item locators tool-neutral and non-secret, for example a repository
issue number, a cross-repository `owner/repo#number`, or a stable governed
backlog identifier. Do not copy issue bodies or provider state into the lane
catalog.
- Reconcile the catalog against current worktrees, bounded local and remote refs, branch-local plan metadata, checkpoint SHAs, target ancestry, receipts, dependencies, and overlap before planning, handoff, integration, or cleanup decisions. Prefer catalog-only discovery when the catalog is the complete authorized population; use exact repeated branch selectors for bounded unregistered-lane discovery. Prefix discovery is an explicit broader survey and should not be the default in repositories with large historical branch namespaces.
- For active worktree custody, classify equal, local-ahead, remote-ahead, and diverged local/remote tips explicitly. Local-ahead, remote-ahead, and diverged state fail closed until the lane owner reconciles and publishes the intended checkpoint.
- Treat worktree presence as workstation-local evidence. When a cataloged
`ACTIVE_WORKTREE` lane has no local branch or checkout but its exact remote
ref and checkpoint agree, classify it as healthy remote-active custody;
require a local checkout only when evaluating local worktree claims.
- Fetching is a caller-controlled operation. A lane auditor must remain read-only and must not fetch, merge, rebase, push, delete refs, remove worktrees, edit plans, or infer authority from a clean report.
- Register normal work before parallel execution begins. An urgent lane may start first only when delay creates greater risk; register and publish its first recoverable checkpoint at the earliest safe boundary.
- After existing catalogs are migrated, enable required work-item validation so
every substantive active lane has at least one non-empty locator. Treat the
catalog link as traceability only; current tracker state still comes from the
governed tracker.
- Do not silently resolve catalog conflicts. Duplicate lane ids, two lanes claiming one branch, missing custody, stale checkpoints, active local/remote mismatch, plan/catalog drift, and unresolved overlaps fail closed until reconciled.
- Keep the catalog current through the repository's protected-default-branch workflow. A lane branch may propose its own registration, but it is not globally discoverable until that projection lands on the configured default ref.
- Reconcile worktree lifecycle with lane state. An integrated, archived, paused,
or handed-off branch does not justify an indefinitely registered checkout;
close an unneeded clean worktree after custody is verified and update the lane
projection without erasing the branch's disposition.

## Adoption Notes

Expand Down
Loading
Loading