| name | anti-legacy:semantic-join |
| description | Analyze and map inter-repository dependencies when multiple codebases are modernization sources. Scans routes and client requests, identifies dangling external links, and validates contract matches. Use when: "joining repositories", "mapping multi-repo interfaces", "verifying inter-app dependencies".
|
anti-legacy:semantic-join
This skill orchestrates Phase 1B (Semantic Repository Join). It matches HTTP and API endpoints across multiple imported legacy repositories, detects dangling calls, and resolves integration questions in-band with the user.
Step 1: Run the Semantic Join analysis
Run the boundary analyzer tool:
python3 .anti-legacy/run.py semantic_join
This generates:
.anti-legacy/requirements/semantic_join_graph.json: A dependency topology map.
.anti-legacy/requirements/semantic_join_report.md: A validation checklist of matched and unmatched API interfaces.
Step 2: Handle Dangling Calls (Integration Gaps)
If the report contains dangling client calls, resolve each one in-band with the user before advancing.
For each dangling call, present this single_choice question to the user directly in the conversation and capture their answer:
- Question id:
GAP-{calling_service}-{dest_path_slug}
- Prompt: "We detected a call from service '{calling_service}' to '{dest_path}' which does not map to any defined endpoints in other imported repos. Is this call an external third-party API or a missing repository?"
- Options (
single_choice):
- Third-Party External API
- Missing Repository (Need to Import)
- Deprecated Code (Can Delete)
Record the user's chosen option against its question id (e.g. in semantic_join_report.md or your working notes) so Step 3 can assert that every dangling call has an in-band answer.
Based on the user's answer:
- Third-Party External API: Document the contract as a mocked external boundary in
nfrs.md.
- Missing Repository: Prompt the user to import the missing Git URL via the dashboard.
- Deprecated Code: Mark the client code section to be stripped out during Swarm translation.
Step 3: Done-Gate — verify the join is real before recording GATE_1B
Before recording the gate or advancing, assert that the semantic join actually completed:
semantic_join_report.md exists and is non-empty, AND every dangling call surfaced in
Step 2 has an in-band answer recorded against its question id. If this assertion fails,
do NOT run manifest.py gate and do NOT run advance — surface the specific gap (missing
report, or the still-unanswered dangling-call question ids) to the user and stop. The
gate record and advance below are CONDITIONAL on this assertion passing.
Confirm the report exists and is non-empty:
python3 -c "
import os, sys
report = os.path.join('.anti-legacy', 'requirements', 'semantic_join_report.md')
if not (os.path.isfile(report) and os.path.getsize(report) > 0):
sys.stderr.write('GATE_1B done-gate FAILED: semantic_join_report.md missing or empty\n')
sys.exit(1)
sys.exit(0)
"
Then verify in-band that every dangling call listed in the report has a recorded answer
(one of the three single_choice options) against its GAP-... question id. If any
dangling call is still unanswered, do NOT proceed — return to Step 2, resolve it with the
user, and re-run this done-gate.
Step 4: Register the evidence artifact, then record the GATE_1B_SEMANTIC_JOIN decision
The gate's --opinion passed guard content-verifies every cited evidence id: each id
must be a registered artifact, its status must not be failed/pending, the file
must exist on disk, and its recorded checksum must match the file. A bare filename like
semantic_join_report.md is NOT a registered artifact id and will hard-fail the gate.
So FIRST register the real report (produced in Step 1) as the artifact id
semantic-join-report. Register it only after the done-gate above passes, so the file
exists and a live checksum is captured:
python3 .anti-legacy/run.py manifest register semantic-join-report \
--path requirements/semantic_join_report.md \
--format markdown \
--produced-by anti-legacy:semantic-join \
--status final
Then record the gate approval, citing the registered id semantic-join-report:
python3 .anti-legacy/run.py manifest gate GATE_1B_SEMANTIC_JOIN \
--opinion passed \
--evaluator "Architect" \
--rationale "All inter-repository endpoints mapped and dangling boundaries clarified by the user." \
--evidence "semantic-join-report"
Step 5: Advance Phase
Only after the done-gate passed and the gate is recorded:
python3 .anti-legacy/run.py manifest advance semantic-join