reconcile

Reconcile Skill (Stage 5)

This skill compares what each project says about itself (via .gt/memory/semantic.json) against what the ecosystem assumes, producing an alignment report and checkpoint.

When to Use

Use this skill when:

• A plugin ships a new version
• A new project is added to the ecosystem
• Quality gates or schemas change across plugins
• Steering questions are resolved and decisions recorded
• Prior reconcile is stale (check .checkpoint.json timestamp)

Output Structure

project/
└── scopecraft/
    ├── ALIGNMENT_REPORT.md   # Human-readable findings
    ├── PERSPECTIVES.md        # Side-by-side project self-reports
    └── .checkpoint.json       # Machine-readable state for recovery

Output templates: templates/ | Checkpoint schema: checkpoint-schema.json

Ecosystem Configuration

The reconcile skill reads project locations from ~/.lisa/ecosystem.json.

Schema: ecosystem-config-v2

{
  "$schema": "ecosystem-config-v2",
  "name": "ecosystem-name",
  "projects": [
    {
      "name": "project-name",
      "path": "~/github/org/repo",
      "remote": "https://github.com/org/repo",
      "role": "role-description",
      "active": true,
      "notes": "optional context"
    }
  ],
  "updated": "YYYY-MM-DD"
}

New in v2: The remote field (optional) specifies the git remote URL. When present, reconcile can locate projects even if cloned to non-standard paths by matching git remote get-url origin. The path field remains the primary lookup; remote is a fallback for project identification and portability.

Backward compatibility: ecosystem-config-v1 (without remote field) is still fully supported. Reconcile will not fail on v1 configs.

Path handling: All paths use ~/ for portability. Expand tildes to absolute paths before file access. Example: ~/github/auge2u/lisa3 becomes /Users/<user>/github/auge2u/lisa3.

Standalone Mode

When ~/.lisa/ecosystem.json is missing or contains only one project, reconcile runs in standalone mode:

• Reports on the single project only (current directory)
• Reads local .gt/memory/semantic.json and scopecraft/ artifacts
• Produces a simplified ALIGNMENT_REPORT.md (no cross-project comparison)
• Checkpoint records single-project state for context recovery
• Prints informational message: "Running in standalone mode (1 project). Add projects to ~/.lisa/ecosystem.json for ecosystem reconciliation."

Reconciliation Procedure

Step 0: Check for Incremental Mode

If a prior checkpoint exists (scopecraft/.checkpoint.json):

1. Read each project's last known git commit hash from checkpoint.projects.<name>.git_hash
2. For each active project with a known path, check current git rev-parse HEAD
3. If the hash matches, the project is unchanged -- skip re-scanning its semantic.json (use cached state from checkpoint)
4. If the hash differs or is missing, mark as changed -- perform full scan
5. If --force flag is set (or user explicitly requests full re-scan), skip this optimization and scan everything

This makes reconcile faster for large ecosystems where most projects haven't changed.

Step 1: Load Ecosystem Config

1. Read ~/.lisa/ecosystem.json
2. Validate it has projects array with at least 1 entry
3. Expand all ~ paths to absolute paths
4. Note which projects are active: true
5. For each project with a remote field, if the path doesn't exist, try to locate the repo by scanning common clone directories for a matching git remote get-url origin

If ~/.lisa/ecosystem.json is missing:

• If the current directory has .gt/memory/semantic.json, run in standalone mode (see above)
• Otherwise, stop and instruct user to create the config. Provide the schema above.

Step 2: Gather Semantic Memory

For each active project:

1. Check if <project.path> exists locally
2. If local: read <project.path>/.gt/memory/semantic.json
3. If not local: try GitHub API as fallback (e.g. gh api repos/<org>/<repo>/contents/.gt/memory/semantic.json)
4. If neither works: record project as status: "not-found" and continue

Handle different schemas gracefully:

• Lisa and Carlos use semantic-memory-v1 schema with ecosystem_role, integration_points, non_goals
• Conductor (and other gastown projects) may use https://gastown.dev/schemas/semantic-memory.json without ecosystem fields
• Extract common fields regardless of schema: project.name, project.type, project.primary_language, tech_stack
• Flag schema differences as a finding (not an error)

Step 3: Read Existing Ecosystem State

If running from ecosystem root:

1. Read scopecraft/ALIGNMENT_REPORT.md if it exists (prior findings)
2. Read scopecraft/.checkpoint.json if it exists (prior state)
3. Note the prior reconcile version and timestamp for change tracking

Step 4: Compare Perspectives

For each pair of projects, check:

Check	What to compare
Role conflicts	Do any two projects claim the same role or write to the same outputs?
Interface agreements	Does what project A says it writes match what project B says it reads?
Tech stack drift	Are shared dependencies on compatible versions?
Constraint violations	Does any project violate another's stated constraints or non-goals?
Capability gaps	Are expected capabilities (from design docs) missing from self-reports?
Schema divergence	Do projects use different semantic.json schemas? What fields are missing?
Stale assumptions	Are any assumptions from prior reconcile now outdated?

Classify each finding as:

• Alignment — Both projects agree
• Misalignment — Projects contradict each other (assign severity: HIGH/MEDIUM/LOW)
• Gap — Expected information is missing

Step 5: Validate Gate Configs

For each project that has quality gates:

1. Check if gates.yaml exists (declarative) or gates are hardcoded
2. Compare gate definitions across plugins — look for:
   • Same gate name, different criteria
   • Missing gates that another plugin expects
   • Format inconsistencies (declarative vs hardcoded)
3. Record gate config misalignments

Step 6: Generate Outputs

ALIGNMENT_REPORT.md

# Ecosystem Alignment Report

**Generated:** YYYY-MM-DD (reconcile vX.Y.Z)
**Previous reconcile:** YYYY-MM-DD vX.Y.Z (or "none")
**Ecosystem root:** <repo name>
**Projects:** <list with status>

---

## Summary

| Status | Count | Change from previous |
|--------|-------|----------------------|
| Aligned | N | +/- N |
| Misaligned | N | +/- N |
| Gaps | N | +/- N |

**Overall assessment:** <2-3 sentence summary>

---

## Changes Since vX.Y.Z
<!-- Only if prior checkpoint exists -->

| Item | Previous | Current | Impact |
|------|----------|---------|--------|

---

## Alignments (What's Working)

### A1: <title>
<description of what both projects agree on>

<!-- Repeat for each alignment -->

---

## Misalignments (Need Resolution)

### M1: <title> (PRIORITY: HIGH/MEDIUM/LOW)
**<Project A>'s view:** ...
**<Project B>'s view:** ...

**Impact:** ...
**Resolution:** ...
**Status:** new/unchanged/worsened

<!-- Repeat for each misalignment -->

---

## Gaps (Missing Information)

### G1: <title>
<what's missing and why it matters>

---

## Steering Questions

| # | Question | Decision or Options |
|---|----------|---------------------|

---

## Next Actions

| Priority | Action | Owner | Blocks |
|----------|--------|-------|--------|

PERSPECTIVES.md

# Ecosystem Perspectives

**Generated:** YYYY-MM-DD (reconcile vX.Y.Z)
**Projects scanned:** N attempted, N found

---

## Project Status Matrix

| Field | Project A | Project B | ... |
|-------|-----------|-----------|-----|
| Status | found/not-found | ... | |
| Version | X.Y.Z | ... | |
| Schema | semantic-memory-v1 | ... | |
<!-- Key fields from each semantic.json -->

---

## <Project Name> Self-Report

**Source:** <path to semantic.json>

| Attribute | Value |
|-----------|-------|
<!-- Extracted fields -->

**Reads from:** ...
**Writes to:** ...
**Does not own:** ...

<!-- Repeat for each project -->

---

## Ecosystem Role Comparison

| Responsibility | Project A | Project B | Conflict? |
|----------------|-----------|-----------|-----------|

---

## Interface Agreement Check

| Interface | Project A says | Project B says | Match? |
|-----------|---------------|----------------|--------|

---

## Schema Divergence Note
<!-- Only if schemas differ across projects -->

.checkpoint.json

Formal JSON Schema: checkpoint-schema.json

{
  "$schema": "reconcile-checkpoint-v1",
  "reconcile": {
    "timestamp": "ISO-8601",
    "version": "X.Y.Z",
    "previous_version": "X.Y.Z or null",
    "ecosystem_root": "repo-name",
    "method": "lisa reconcile skill (Stage 5)"
  },
  "projects": {
    "<name>": {
      "path": "~/...",
      "status": "found|not-found",
      "source": "local filesystem|GitHub API",
      "semantic_json": {
        "exists": true,
        "version": "X.Y.Z",
        "schema": "schema-identifier",
        "last_scan": "ISO-8601",
        "project_name": "name",
        "role": "role"
      },
      "scopecraft": {
        "exists": true,
        "files": ["..."],
        "level": "project|ecosystem"
      },
      "alignment": "aligned|mostly-aligned|divergent|not-found"
    }
  },
  "alignment_summary": {
    "total_projects": 0,
    "found": 0,
    "missing": 0,
    "aligned": 0,
    "mostly_aligned": 0,
    "divergent": 0,
    "alignments": 0,
    "misalignments": 0,
    "gaps": 0
  },
  "misalignments": [
    {
      "id": "M1",
      "severity": "high|medium|low",
      "description": "...",
      "affects": ["project-names"],
      "resolution": "...",
      "status": "new|unchanged|worsened|resolved"
    }
  ],
  "resolved": [],
  "decisions": {
    "resolved_date": "YYYY-MM-DD",
    "steering_questions": [],
    "open_questions": []
  },
  "next_reconcile_triggers": []
}

Schema Tolerance

External projects (e.g., Conductor) may produce their own reconcile checkpoints with different field names. When reading external checkpoints during reconcile, extract common fields regardless of schema:

• misalignments / remaining_misalignments — treat as equivalent
• steering_questions / steering_questions_resolved + open_queries — extract both
• Different severity scales or status enums — normalize to Lisa's convention

The reconcile-checkpoint-v1 schema (see checkpoint-schema.json) is canonical for Lisa's own checkpoints. External formats are tolerated as input, not required to conform.

Error Handling

Error	Response
~/.lisa/ecosystem.json missing	If local .gt/memory/semantic.json exists, run in standalone mode. Otherwise, stop and print schema for user.
~/.lisa/ecosystem.json has only 1 project	Run in standalone mode with informational message.
Project path doesn't exist locally	Check remote field if present; try GitHub API; record as "source": "GitHub API" or "not-found"
semantic.json missing for a project	Record semantic_json.exists: false, continue with other projects. Do not crash.
semantic.json malformed	Record error in checkpoint, skip project's comparison. Do not crash.
Different schema than expected	Extract common fields, flag divergence as a finding (not an error)
No prior checkpoint	First reconcile -- skip "Changes Since" section and incremental check
Fewer than 2 projects reachable	Warn but still produce report (standalone comparison against own state)
Git not available	Skip git hash check, skip remote lookup, fall back to path-only
Ecosystem partner not installed	Informational message: "Carlos not found -- Lisa works standalone. Install Carlos for specialist analysis." Do not error.

Quality Gates

Reconcile quality gates are defined in gates.yaml (9 gates, automated via validate.py --stage reconcile):

Gate	Check	Severity
config_loaded	Checkpoint confirms ecosystem config was loaded	blocker
projects_found	2+ projects found in checkpoint	blocker
alignment_report_exists	ALIGNMENT_REPORT.md generated	blocker
perspectives_exists	PERSPECTIVES.md generated	blocker
checkpoint_valid	.checkpoint.json is valid JSON	blocker
checkpoint_schema	Checkpoint has reconcile-checkpoint-v1 schema	blocker
report_has_summary	Report has Summary section	blocker
report_has_misalignments	Report has Misalignments section	warning
changes_tracked	Prior version tracked in checkpoint	warning

Next Steps

After reconcile completes:

• Run validate.py --stage reconcile to verify outputs
• Review ALIGNMENT_REPORT.md for action items
• Address HIGH priority misalignments first
• Re-run reconcile after significant changes (see next_reconcile_triggers in checkpoint)