Imported from alvis/.agents (plugins/specification/skills/sync-spec/SKILL.md). Install upstream with npx skills add alvis/.agents --skill sync-spec. Copyright stays with the author.

Sync Spec

Safely coordinate three copies of a Notion-backed specification: an immutable recorded base, the work-local authored copy, and a fresh remote staging pull. specification:sync-notion owns transport. specification:mdc owns the MDC body grammar; another dialect uses an explicitly selected body_author for semantic body changes. Detect changes by comparing the specification content directly (byte-for-byte, or via git diff), disregarding only the volatile Notion last_edited_time line for semantic equality. Approvals bind to the approved specification content, not to any hash.

Boundaries

• materialize obtains a fresh remote view, then creates or refreshes only the requested page tree under .state/works/<work-id>/spec/ when the base/local/remote decision permits it.
• complete is a publication gate. It reconciles the authored copy with a fresh remote view, verifies stage-specific approval, delegates guarded transport, verification-pulls, refreshes the work-local materialization and immutable receipt, and reports dependent work that needs revalidation.
• External specifications never derive version-controlled specification files. In PRs and tracked documents, cite their canonical external URL only—never .state, a mirror, an absolute path, or file://.
• Only the main agent writes the external authority, .state/**, root README.md, or docs/**. Subagents return proposals and evidence.
• Never derive or rename an MDC filename. Select files by stable ref: and the transport relationship report.
• Never call notion-sync directly, treat the selected mirror as an authoring surface, overwrite a fixed receipt, or infer that cached mirror bytes are the latest remote bytes.
• Never treat a metadata-only edit (only the volatile last_edited_time line differs) as a contract change, and never approve, plan, or review against content you have not compared directly against the recorded base.

Inputs

• Required: Notion URL or page id.
• Optional: work id, exact --mirror=<path>, mode (default materialize), lowercase capability slug, and a verified creation receipt for an explicitly created new page.
• Required for every Notion operation: an explicit absolute --transport-profile=<file>, or an active-state destination mapping that names one absolute profile file, its last verified exact-byte SHA-256, and logical profile name. The mapping selects a file only; sync-notion revalidates its current bytes/executable on every invocation. Never infer a profile path from a logical name, mirror, workspace, or origin receipt.
• Required for completion that applies authored content: explicit --body-author=<plugin:skill> in canonical capability form. Materialization that only preserves pulled bytes may omit it. Resolve the selector once, never infer a default, and require every nested call plus existing creation/materialization receipt to match it exactly.
• Completion only: --stage=specification|implementation is required. Specification stage requires explicit specification approval of the final specification content. Implementation stage requires a clean implementation review that was performed against that exact final content, confirmed by direct comparison.
• Prerequisites: injected Essential state contract, resolved active work, the strict destination/team profile required by sync-notion, and NOTION_TOKEN.

Workflow

1. Read the absolute injected state.md contract before artifact writes. If unavailable, stop artifact writes and report the missing contract. A direct main-agent run follows Essential's work-stream establishment lifecycle: preserve an explicit user --work-id override; otherwise treat resolver matches as candidates, reuse one only when its charter owns the requested outcome, select a collision-free identity when none does, and rerun the resolver with that identity. On work_id_required, select contextually and rerun without asking the user to approve an identifier. A delegated run receives the resolved id/root or returns the resolver payload to the main agent without writing. Resolve:
   • work_spec_root = <active>/.state/works/<work-id>/spec;
   • mirror_root from explicit input, active state, or an immutable receipt;
   • transport_profile_file from explicit input or the exact validated active-state mapping described above;
   • body_author from the explicit argument only when this chain may apply authored body bytes, with selection_source: explicit_argument (or delegated_caller when already bound by the parent);
   • receipt_root = <work-dir>/artifacts/spec-sync;
   • immutable receipts at materializations/<base-id>.json and base snapshots at bases/<base-id>/, where <base-id> is a stable identifier derived from the full accepted byte set of the base — all per-unit identities and their revisions together (sanitized for filesystem use) — never the root page's observed revision alone, which collides when a child page or layout changes while the root revision is unchanged and would let a later materialization overwrite or compare against a stale base. Every receipt is JSON with these required top-level fields: base_id equal to its filename stem, canonical_url, a non-empty observed_external_revisions string map, UTC created_at, and a non-empty lexically sorted content_manifest. Each manifest entry is exactly the work-relative POSIX path, lowercase SHA-256 sha256, and integer bytes for one regular file. The manifest enumerates every file in both bases/<base-id>/ and spec/; both trees must match it byte-for-byte and contain no symlinks. Record the selected body-author identity when applicable. A matching path or base_id without this complete byte proof is invalid evidence. Validate body_author against canonical <plugin>:<skill> identity and retain it separately from the transport profile. A missing or changed selector before semantic body mutation returns status: refused, next_action: select_body_author; it is never transport_unverified. Creation, materialization, completion, and derivation receipts record the selected capability and selection source when present; nested calls compare them before authoring. goal.md alone points to the accepted base, local copy, and current receipt; the main agent owns that update. state.md records sync status and links to goal.md without restating anchors. Require the real work/mirror targets to be ignored and untracked in their owning VCS workspaces; otherwise return requires_ignore with the exact ignore file. Require the mapped logical name to equal the selected profile's name and pass the absolute file explicitly to every transport call. A missing, ambiguous, moved, or changed mapping returns transport_unverified; never fall back to PATH or a conventional file location.
2. Normalize the Notion id only for identity comparison and require 32 hex characters after dash removal. Resolve the selected recursive page set by returned ref:/relationship data, never filename shape. Load references/concurrent-edit-matrix.md. Reject malformed/ambiguous carriers and duplicate identities/paths/logical unit ids. Use the three-copy rules for every later decision.
3. Before either mode decides anything, invoke Skill(sync-notion) in notion-to-local mode with the exact mirror root and --transport-profile=<transport_profile_file> into a unique remote staging directory. Verify full requested coverage, stable identity, and revision evidence. Store the exact pulled bytes and observed revision as immutable evidence for later direct comparison. Do not refresh the selected mirror or work copy yet.
4. In materialize mode, compare the current authored tree L and fresh remote staging R with immutable base B. Report operational status separately from classification and next_action. Before declaring metadata_only, compare every unit directly and require identical carrier kind, stable identity, logical id, path, and semantic content; only observed_revision and the uniquely allowed last_edited_time line may differ. A stable-identity, logical-id, or carrier-kind shift is invalid evidence and returns status: refused, classification: invalid_evidence, and next_action: repair_evidence. A verified path/layout rename with identities intact is structural_change, invalidates dependent evidence, and is never metadata-only:
   • absent L/B establishes the first base by atomic staging and promotion and returns status: success, classification: initial, and next_action: none;
   • absent B with existing L returns status: refused, classification: baseline_required, and next_action: establish_baseline, and preserves L, except that a verified new-page creation receipt may establish the initial base only when it preserves pre-create L, proves creation authorization and the stable identity/parent transition, and records post-create approval plus exact verification evidence for R; atomically promote that verified R as initial L/B;
   • clean L plus unchanged R returns status: success, classification: unchanged, and next_action: none;
   • semantic B/L/R equality with a remote-only metadata change that passes the structured-unit restriction above (only the last_edited_time line and observed revision differ) returns status: success, classification: metadata_only, and next_action: none, atomically refreshes the exact remote bytes and revision, and creates a new immutable base/receipt without invalidating approval, plan, code, or review;
   • clean L plus a remote structural change atomically promotes the fully staged/verified R tree, creates a new base/receipt, and returns status: success, classification: structural_change, and next_action: revalidate; it invalidates approval, plan, code, and review even when the content is otherwise equal;
   • clean L plus changed R atomically refreshes L/mirror, creates a new base/receipt, and returns status: success, classification: remote_only, and next_action: revalidate when plan, review, or implementation evidence exists;
   • dirty L plus unchanged R returns status: success, classification: local_only, and next_action: none, and preserves L;
   • dirty L plus a semantic or structural remote change returns status: success, classification: materialization_conflict, and next_action: resolve_conflict, preserves every canonical byte, and reports B/L/R paths and manifest differences. Stage and verify the complete selected tree before any atomic promotion; retain rollback bytes until both promoted manifests verify.
5. In complete mode, require a valid stage and compare B/L/R before canonical writes. Missing B is status: refused, classification: baseline_required, and next_action: establish_baseline; unchanged and converged content need no push; local-only content may proceed through its content-approval stage gate; remote-only or structural change is status: success with next_action: revalidate and no push; concurrent content requires an explicit three-way merge. Workers may return conflict packets/proposals only. The main agent/user owns choices, and Keep Both requires explicit approval of the synthesized final content. Any Skip leaves that pair's local, mirror, and remote bytes untouched and forbids a push. A concurrent relationship at stage=implementation returns status: success, classification: concurrent, and next_action: specification_reconciliation with B/L/R evidence and proposals; it must not apply or push merged content at implementation stage. The source owner must author the selected merge, complete it through stage=specification, verification-pull it, establish a new immutable base/receipt, and materialize that base before any plan or implementation resumes.
6. Freeze each selected pair's final proposal. For stage=specification, require explicit specification approval of the exact final specification content. For stage=implementation, require the clean implementation review to have been performed against that exact final content. Any semantic edit after the gate invalidates it; a declared metadata-only refresh (only the last_edited_time line differs) does not, but must refresh the exact base evidence. Apply approved authored changes only to a staged mirror copy through the exact capability bound as body_author. Pass only the approved staged body and exact path, and require the selector to match the parent and receipt.
7. Immediately before each outbound operation, use Skill(sync-notion) to re-fetch/re-diff the exact remote revision and content, passing the same exact --transport-profile file and mirror root. Abort and restart on any content or revision change, so the base/revision evidence can be refreshed. Require the pinned transport to prove conditional-update support and record that condition. If a valid profile declares it unavailable, propagate status: refused, preserve the observed B/L/R classification, set next_action: provide_conditional_transport, and leave Notion plus canonical L/mirror bytes unchanged. A malformed, mismatched, moved, or unproven profile remains transport_unverified. Push only a fully resolved pair, then perform an independent verification pull.
8. Only after verified identity/content may canonical L/mirror state advance. Create a new immutable base directory and receipt keyed by <base-id>; never rewrite an earlier base or receipt. A partial remote write is partial with exact recovery evidence, not success. Atomically refresh spec/, record the observed revision and exact content in the base-id-keyed receipt, and return a main-agent reconciliation delta for goal.md. Do not create or update version-controlled specification files; the external authority remains the canonical contract.
9. Enumerate locally registered Git worktrees and jj workspaces. For readable open work on the same source id whose recorded content changed, keep status: success, set next_action: revalidate, and return workspace/work/ state paths; list external anchors and unknown/remote dependents separately. Never edit another main agent's state.
10. Return every final path created or materially rewritten as generated_files. Each writer follows essential:references/output-manifest.md for work Markdown it creates or rewrites. The main agent applies the goal.md/state.md reconciliation delta.

Verification

• B is immutable, L is the authored copy, and R came from a fresh staging pull.
• The recorded base stores stable identities, the observed revision, and the full accepted bytes; comparison was performed directly against those bytes.
• Existing local bytes changed only in an allowed matrix row; conflict, baseline_required, remote-only, and skipped outcomes did not push.
• The approval/review was performed against the final specification content, and the immediate remote recheck matched the exact comparison revision and content.
• Every successful publication has a verification pull, refreshed spec/, and a new base/receipt keyed by <base-id>; no fixed materialization.json was overwritten and no version-controlled specification derivation was produced.
• Opaque body content and Notion transport stayed with their selected owners; every semantic mutation used the exact recorded body_author.

Completion

skill: sync-spec
status: success|partial|refused|requires_ignore|transport_unverified
classification: initial|unchanged|metadata_only|local_only|remote_only|structural_change|converged|concurrent|baseline_required|materialization_conflict|invalid_evidence|not_applicable
next_action: none|revalidate|establish_baseline|resolve_conflict|specification_reconciliation|recover_partial|repair_evidence|provide_conditional_transport|select_body_author
mode: materialize|complete
stage: specification|implementation|null
work_id: '<id>'
transport_profile: {logical_name: '', profile_file: '<absolute destination-local path>', profile_file_sha256: '', verification: verified|transport_unverified}
body_author: {capability_id: '<plugin>:<skill>|null', selection_source: explicit_argument|delegated_caller|null, verification: matched|not_required|refused}
outputs:
  transport_mirror: '<absolute selected path or null>'
  work_spec_root: '<absolute active-workspace path>'
  base_snapshot: '<absolute immutable path or null>'
  materialization_receipt: '<absolute base-id-keyed path or null>'
  notion_root: {id: '<32hex>', path: '<notion-sync-owned path>'}
  comparison:
    classification: initial|unchanged|metadata_only|local_only|remote_only|structural_change|converged|concurrent|baseline_required|materialization_conflict|invalid_evidence|not_applicable
    base: {revision: ''}
    local: {revision: ''}
    remote: {revision: ''}
    base_id: '<stable base identifier or empty>'
  publication: {approved: false, reviewed_spec_matches_final: false, remote_rechecked: false, required_capability: conditional_update|conditional_create|null, conditional_write: false, pushed: false, verified: false}
  reconciliation: {required: false, reason: null, conflict_packet_paths: [], invalidated: []}
  provenance: {path: '', embedded_output_paths: [], self_hash_external: ''}
  revalidation: {local_registered: [], external_receipt_anchors: [], unknown_or_remote_dependents: []}
generated_files: []
issues: []

Use these deterministic top-level mappings: missing base → status: refused, classification: baseline_required, next_action: establish_baseline; dirty materialization with remote semantic/structural change → status: success, classification: materialization_conflict, next_action: resolve_conflict; implementation-stage concurrent change → status: success, classification: concurrent, next_action: specification_reconciliation; remote-only semantic/structural change or a success that invalidates dependents → status: success, matching classification, next_action: revalidate; ambiguous/partial remote mutation → status: partial, next_action: recover_partial; policy/precondition failure → status: refused, classification: invalid_evidence|not_applicable, and next_action: repair_evidence when repairable. Verified absence of the conditional capability required for publication → status: refused, preserve the observed B/L/R classification, and next_action: provide_conditional_transport, with no remote or canonical-local mutation. An absent or mismatched transport profile/mapping propagates transport_unverified; missing mirror ignore coverage propagates requires_ignore. A missing or changed body-author selector before semantic mutation returns status: refused, preserves the observed classification, and sets next_action: select_body_author without changing body or transport bytes.