harmonize · diff
git:20261104.d5f4777 to git:20261104.42ab9cf
5 added, 5 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: harmonize
description: |-
Harmonize documentation, policies, and workflows across Dom’s projects.
disable-model-invocation: true
metadata:
internal: true
---
# Repository Harmonization
Run a change-oriented consistency pass by default. An explicit review or comparison request remains read-only. When the resolved scope includes agent documentation, follow `agent-documentation` and its [repository independence contract](../../../skills/.domfiles-agent-documentation/references/repository-independence.md) for requirement selection, local ownership, shared wording, and new repository setup. Apply the global **Explicit user direction** policy to task-specific changes to this workflow.
## Resolve Repositories
- **Scope:** Use Git repositories within the explicitly supplied project scope or location, defaulting to repository roots in immediate child directories of `~/Projects`, including hidden directories, plus the SSH project paths declared in [`ssh_connections` in the Zed settings](../../../home/.config/zed/settings.json). Default local discovery does not recurse into those child directories. Use the named concept, policy, or documentation family. Without a narrower content scope, compare project-authored agent documentation expressing shared policies, workflows, or terminology. Start from Git-tracked files and exclude agent task artifacts, generated files, managed files, third-party files, untracked files, and vendored files unless explicitly included. An authorized setup pass may create the necessary instruction surfaces.
- **Eligibility:** By default, discover repositories with tracked project-authored agent documentation and at least one configured Git remote pointing to `porada/*` or `standard-config/*`. A tracked `AGENTS.md` isn’t required. An explicitly selected repository may participate before it has agent documentation or a remote. Present the complete candidate list with stable repository numbers and distinguish source-only baselines from destinations. An explicit user selection confirms its stated role and covered effects. Ask before further inventory, comparison, or mutation only when the repository set or any repository’s role remains unconfirmed. Don’t create files merely to satisfy discovery criteria.
- **Remote environment:** Assume in-scope SSH locations use domfiles with the same global agent instructions, globally installed skills, and managed command entrypoints as the local environment. This assumption doesn’t establish remote access or matching host capabilities, and it doesn’t replace destination repository instructions.
- **Remote discovery:** For SSH projects within scope, confirm access to each configured project path with a bounded, read-only, non-interactive check through established SSH authentication before including it as a candidate. List inaccessible paths separately as unverified, with their access errors, before repository confirmation. Identify accessible candidates by their configured nickname, host, and project path, and apply the same eligibility and confirmation rules.
- **Checkout boundary:** Preserve explicitly supplied checkout paths, including linked worktrees, rather than substituting a primary worktree. For directory-based discovery, don’t expand through linked worktree registrations or inventory duplicate checkouts of one repository. When discovery finds multiple checkouts of one repository without an explicit selection, ask which to use during repository confirmation.
- - **Inventory gate:** Before editing, complete these read-only checks in every confirmed repository: inventory the selected documentation family, check the working state, and assess whether mutation is feasible. Read every applicable `AGENTS.md` and repository-specific authority model. Identify existing owners, supported client entrypoints, and any necessary new surfaces without expanding into a general repository audit.
+ - **Inventory gate:** Before editing a destination, inventory its selected documentation family, check its working state and mutation feasibility, and read every applicable `AGENTS.md` and repository-specific authority model. Inspect the confirmed sources and related destinations needed to establish that change’s validity. Identify existing owners, supported client entrypoints, and any necessary new surfaces without expanding into a general repository audit. An unavailable destination may remain uninventoried and deferred when the planned changes are independently valid under **Atomicity**. A required source or cross-repository dependency must still be checked before its dependent changes.
- **Baseline:** Use the explicitly selected baseline. Otherwise propose domfiles as the source-only baseline and obtain confirmation before inspecting it unless that role is already confirmed. A baseline doesn’t have to be a destination. Source-only confirmation permits bounded read-only comparison, not mutation. Apply the same checkout and access boundaries to it. Its global policies and authoring tools are source material, not prerequisites for destination collaborators.
## Compare Requirements
- **Candidates:** Classify corresponding items using the shared wording rules below. When a confirmed baseline expresses an item that a destination lacks, treat that item as a candidate only when it may supply a required output property, not merely because the maintainer uses it. Treat an item the baseline doesn’t express as a consistency candidate only when at least two in-scope surfaces express the same observable meaning and role. Preserve intentionally different requirements. Ambiguous policy and general quality defects remain outside scope unless the named family explicitly includes them. Inspect implementation and tests only as bounded evidence needed to establish observable meaning.
- **Canonical form and placement:** Use the [shared wording rules](../../../skills/.domfiles-agent-documentation/references/repository-independence.md#align-shared-wording) to select and reproduce equivalent formulations. Outside agent documentation, retain the applicable domain’s semantic owner and distribution model. Don’t resolve an unsettled acceptance requirement by silently copying the baseline or hoisting it into the maintainer’s global instructions.
## Establish Repository Documentation
When the user requests setup or connection of a new repository, use the same confirmed repository set and baseline rather than requiring a preliminary documentation migration. Follow the repository independence contract to select the minimum local instruction surfaces and supported client bridges.
Connection means selecting the repository and its authoring baseline for this pass. Future passes rediscover its project-authored surfaces through the same eligibility rules. Do not add a repository registry, synchronization manifest, generator, or runtime dependency on domfiles merely to record that relationship. An explicit future selection can include a repository outside default discovery.
## Apply and Validate
- - **Edit matrix:** Before mutation, record one complete repository-and-file matrix identifying each requirement’s canonical source, local destination, proposed change or creation, and any permission or access requirement. Keep unresolved choices and intentional variants distinct from approved edits. A review-only pass records findings rather than applying the matrix.
- - **Atomicity:** By default, apply each family of semantically equivalent items across every required safely writable repository as one coordinated unit. If a required destination is unavailable or has overlapping work, leave that family unchanged everywhere and report the limitation. When the user expressly authorizes a partial pass, apply it only to the named safely writable targets and report the remaining alignment gap. Don’t overwrite overlapping work.
- - **Coordination and boundaries:** When a repository is unavailable to its required tools or protected-path workflow, relay its edit pass to an agent running there or stop before mutation. Follow every repository’s instructions, disclosure boundary, concurrent work policy, protected-path workflow, and validation requirements. Don’t transfer private facts or secret-bearing values between repositories.
- - **Validation and report:** Use `agent-documentation`’s validation workflow, including repository independence checks, for affected agent documentation. For other selected families, use the applicable domain checks and `git diff --check`. Re-read the complete compared family and confirm that every semantically equivalent item uses the canonical formulation. Report the source and destination roles, changed repositories, canonical ownership, intentional variants, unresolved decisions, and material verification limits. Distinguish source-based checks from live client behavior. Don’t report discrepancies already resolved by the pass.
+ - **Edit matrix:** Before mutation, record one repository-and-file matrix complete for the destinations being changed and the sources or related destinations needed for their validity. Identify each requirement’s canonical source, local destination, proposed change or creation, and any permission or access requirement. List deferred destinations with their reason and pending scope without inventing uninspected file details. Keep unresolved choices and intentional variants distinct from approved edits. A review-only pass records findings rather than applying the matrix.
+ - **Atomicity:** Apply each family across authorized, safely writable destinations when those changes remain independently valid. Defer unavailable destinations or those with overlapping work, and report the remaining alignment gaps without requiring separate approval for that partial pass. Use a coordinated family-wide change only when partial adoption would violate an accepted cross-repository contract or leave a destination incorrect. In that case, leave the dependent family unchanged until all required destinations can be updated safely or the user authorizes a different outcome. Preserve complete local invariants and don’t overwrite overlapping work.
+ - **Coordination and boundaries:** When a repository is unavailable to its required tools or protected-path workflow, relay its edit pass to an agent running there or defer its edits under **Atomicity**. Follow every repository’s instructions, disclosure boundary, concurrent work policy, protected-path workflow, and validation requirements. Don’t transfer private facts or secret-bearing values between repositories.
+ - **Validation and report:** Use `agent-documentation`’s validation workflow, including repository independence checks, for affected agent documentation. For other selected families, use the applicable domain checks and `git diff --check`. Re-read the complete compared family available within the authorized scope. Verify canonical correspondence across applied destinations and identify deferred destinations and remaining alignment gaps, without claiming complete alignment for a partial pass. Report the source and destination roles, changed repositories, canonical ownership, intentional variants, unresolved decisions, and material verification limits. Distinguish source-based checks from live client behavior. Don’t report discrepancies already resolved by the pass.