/ase-sync-reconcile

name: ase-sync-reconcile
argument-hint: "[--help|-h] [--bidirectional|-b] [--operation|-o <op>[,...]] [--dry|-d] [--target|-t <target>[,...]] [--source|-s <source>[,...]] [<hint>]"
description: >
    Reconcile one set of artifact kinds (the target) to reflect the
    current state of another set of artifact kinds (the source), while
    optionally honoring a filtering hint. Use when the user wants to
    "reconcile", "sync", "align", or "update" artifacts like SPEC,
    CODE, DOCS, TASK, INFR, or OTHR against each other.
user-invocable: true
disable-model-invocation: false
effort: xhigh

@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md

<purpose name="ase-sync-reconcile"> Reconcile Artifact Set to Artifact Set </purpose>

<expand name="getopt" arg1="ase-sync-reconcile" arg2="--bidirectional|-b --operation|-o=(all|add|update|remove)... --dry|-d --target|-t=CODE,DOCS,INFR,OTHR --source|-s=AUTO"> $ARGUMENTS </expand>

<objective> *Reconcile* the *target* artifact kinds to *reflect* the *current state* of the *source* artifact kinds, by reading the source artifacts and aligning the target artifacts accordingly: <hint><getopt-arguments/></hint>. </objective>

@${CLAUDE_SKILL_DIR}/../../meta/ase-format-meta.md @${CLAUDE_SKILL_DIR}/../../meta/ase-format-spec.md @${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md @${CLAUDE_SKILL_DIR}/../../meta/ase-tenets.md

Procedure ---------

<flow>

1. <step id="STEP 1: Determine Target and Source">

1. The recognized artifact kinds are the six tokens `TASK`, `SPEC`, `CODE`, `DOCS`, `INFR`, and `OTHR`. Parse <getopt-option-target/> as the comma-separated <target/> kind list and <getopt-option-source/> as the comma-separated <source/> kind list. Upper-case and trim every parsed kind token. Do not output anything.

2. <if condition="<target/> is empty">

Only output the following <template/> and then immediately *STOP* processing the entire current skill:

<template> ⧉ **ASE**: ☻ skill: **ase-sync-reconcile**, ▶ ERROR: empty target artifact list </template>

</if>

3. <if condition="<source/> is equal 'AUTO'">

Set <source/> to the six recognized kinds `TASK,SPEC,CODE,DOCS,INFR,OTHR` *minus* all kinds present in <target/>. Do not output anything.

</if>

4. If any token in <target/> or <source/> is *not* one of the six recognized kinds, only output the following <template/> (with <kind/> set to the first offending token) and then immediately *STOP* processing the entire current skill:

<template> ⧉ **ASE**: ☻ skill: **ase-sync-reconcile**, ▶ ERROR: unknown or unsupported artifact kind: **<kind/>** </template>

5. <if condition="<getopt-option-bidirectional/> is not 'true'">

Remove from <source/> any kind that is also present in <target/> (a kind is never its own source).

<if condition="<source/> is empty">

Only output the following <template/> and then immediately *STOP* processing the entire current skill:

<template> ⧉ **ASE**: ☻ skill: **ase-sync-reconcile**, ▶ ERROR: empty source -- nothing to update from </template>

</if>

</if>

6. Treat <getopt-option-operation/> as a comma-separated list of *operation tokens*. The getopt parser validates only the *first* token, so you *MUST* validate each remaining token yourself against the allowed set `all`, `add`, `update`, `remove`. If any token is *not* in this set, bind <token/> to that offending token, then only output the following <template/> and then immediately *STOP* processing the entire current skill:

<template> ⧉ **ASE**: ☻ skill: **ase-sync-reconcile**, ▶ ERROR: invalid `--operation` token: **<token/>** </template>

Set <operations/> to `add,update,remove` if `all` is in <getopt-option-operation/>, or to the given tokens otherwise. Do not output anything.

7. Report the resolved target, source, and operations with the following <template/>:

<template> <ase-tpl-bullet-signal/> **TARGET**: <target/> <ase-tpl-bullet-normal/> **SOURCE**: <source/> <ase-tpl-bullet-normal/> **OPERATIONS**: <operations/> </template>

</step>

2. <step id="STEP 2: Resolve and Read Artifacts">

1. Do not output anything in this STEP 2.

2. For all kinds in the union of <target/> and <source/>, call the `ase_artifact_list(kind: [ ... ])` tool of the `ase` MCP server *once*, passing the lower-cased `kind` tokens, and read the returned `artifacts` array of `{ kind, files }` objects to obtain the project-relative file list per kind.

3. <if condition="<hint/> is not empty">

Honor the filtering <hint/> to reduce the source and/or target artifacts and/or the aspects of those artifacts you should take into account.

</if>

4. Read all (optionally filtered) source and target artifacts previously resolved and build a precise understanding of the *current state* they represent.

</step>

3. <step id="STEP 3: Update Artifacts">

1. Internalize and honor the artifact-format conventions:

• the artifact-set meta information (`ase-format-meta.md`),
• the `SPEC` format, i.e. the SpecBook models and formats plus

the SpecBook schema configuration of the project (`ase-format-spec.md`),

• the `TASK` format (`ase-format-task.md`).

Whenever a target artifact belongs to one of these kinds, the update *MUST* keep it conformant to the corresponding format (headings, structure, identifiers, references, and the `Modified:`