Lw Sync Repo

LLM Wiki Sync From Repo

Keep a wiki live from source-repo changes.

Required reads

1. .llm-wiki/profile.json
2. Active profile markdown
3. .llm-wiki/manifest.json
4. Repo change input provided by the user, if any

If the active profile is not repo-backed, stop and say that repo sync is not defined for the current profile.

Source-of-truth location

The canonical repo location comes from the active profile's machine-usable block:

repo_sync:
  enabled: true
  repo_path: raw/upstream
  repo_remote: origin
  default_branch: main
  provider: github
  repo_slug: owner/repo

This means:

• the source repo location is project-specific
• it should live in the workspace-local profile, not in the shared skill
• relative repo_path values should be resolved relative to the wiki workspace root
• recommended workspace-local mirror: raw/upstream/ (created by lw-clone-repo or bootstrap --repo-url). Older workspaces may still use a sibling path such as ../source-repo.
• raw/repo/ is not the live checkout; it holds staged repo file artifacts for compile (see lw-ingest / this skill’s staging step).

Repo resolution order

Resolve the repo target in this order:

1. if the user explicitly passes a repo path, use it as an override
2. otherwise use repo_sync.repo_path from the active profile
3. if the path is relative, resolve it relative to the wiki workspace root
4. verify the resolved path exists and is a git repository
5. resolve repo_remote, default_branch, provider, and repo_slug from the active profile
6. if any of these are absent, fall back conservatively to repo-local discovery where possible

Validation checks:

• repo path exists
• .git/ exists or git rev-parse --show-toplevel succeeds in that path
• the configured remote exists, or origin exists when used as fallback
• the configured default branch exists locally or remotely after fetch

If validation fails, stop and report exactly which repo binding field is missing or invalid.

Repo access and auth detection

The repo-backed wiki workflow must support both:

• local git inspection
• richer GitHub metadata when available

Preferred detection order:

1. local git access is the baseline and should always be attempted first
2. if provider: github, check whether gh is installed and authenticated
3. if gh is unavailable, continue with git-only inspection
4. if curl/token-based GitHub API access exists, it may be used, but it should improve awareness rather than become required for correctness

Recommended checks:

git --version
git -C "$REPO_PATH" rev-parse --show-toplevel
git -C "$REPO_PATH" remote get-url "$REPO_REMOTE"

gh --version 2>/dev/null || true
gh auth status 2>/dev/null || true

Interpretation:

• if local git works, repo sync can still proceed in git-only mode
• if gh auth status works, GitHub PR/metadata awareness can be added
• if GitHub metadata is unavailable, mark the report as git-only

Step-by-step procedure

1. Resolve repo binding and repo-change input

Determine the workspace root first. Then resolve repo_path using the repo resolution order above.

The repo-change input may be one of:

• repo path
• changed file list
• commit hash
• commit range
• PR summary
• release note with changed paths
• no explicit input, meaning inspect the delta between last_compiled_sha and current default-branch head

Normalize the input into one of these concrete forms:

• changed file list
• commit range
• single commit
• provider-backed PR/change summary plus changed files

2. Fetch upstream state safely

Do not mutate the source repo beyond read-only refresh operations. Use fetch, not merge or pull.

Recommended commands:

git -C "$REPO_PATH" fetch "$REPO_REMOTE" --prune
git -C "$REPO_PATH" rev-parse "$REPO_REMOTE/$DEFAULT_BRANCH"
git -C "$REPO_PATH" rev-parse HEAD

If last_compiled_sha exists in .llm-wiki/manifest.json, compare it to the latest default-branch head.

Recommended commands:

git -C "$REPO_PATH" diff --name-only "$LAST_COMPILED_SHA..$REPO_REMOTE/$DEFAULT_BRANCH"
git -C "$REPO_PATH" log --oneline "$LAST_COMPILED_SHA..$REPO_REMOTE/$DEFAULT_BRANCH"

If no last_compiled_sha exists yet:

• treat the run as an initial repo inspection
• use watched paths and authority buckets to keep the first staging pass conservative

3. Gather provider metadata when available

If provider: github and repo_slug is defined, attempt GitHub-aware inspection only as an enhancement.

Preferred path:

gh auth status
gh api "repos/$REPO_SLUG"
gh api "repos/$REPO_SLUG/pulls?state=open&per_page=20"

Use provider metadata for:

• open PR awareness
• clearer change summaries
• optional mapping of merged PRs to commit ranges

If provider access fails:

• retry transient failures a small number of times
• then continue with git-only inspection
• clearly mark the report as git-only

Do not fail the whole repo-sync operation merely because GitHub metadata is unavailable.

4. Normalize changed files or change units

Normalize the inspection into a concrete list of changed files or change units.

Typical commands:

git -C "$REPO_PATH" diff --name-only "$BASE_SHA..$TARGET_SHA"
git -C "$REPO_PATH" diff --stat "$BASE_SHA..$TARGET_SHA"
git -C "$REPO_PATH" show --name-only --stat "$COMMIT_SHA"

For PR-backed awareness, capture:

• PR number/title
• base/head refs
• changed files
• merge status when available

5. Classify each changed item using profile rules

For each changed file or change unit, determine:

• source kind
• authority level
• likely truth category, such as:
  • runtime behavior
  • config/manifest truth
  • maintained reference guidance
  • flow behavior
  • legacy documentation
  • product/brochure framing

Use the active profile's watched paths, authority buckets, and authority ranking whenever possible.

Recommended rule:

• if a file matches no watched path, keep it in the report but classify it conservatively as lower-confidence impact unless there is clear evidence otherwise

6. Map likely affected wiki pages

Using the active profile's impact map, predict likely affected wiki page types or concrete pages. Keep the candidate list conservative and targeted.

Examples:

• config/manifests → services, editions, maps, comparisons, queries
• flow changes → flows, comparisons, queries
• runtime file changes → service pages, concepts, maps
• security docs → security pages and high-level query/comparison pages

7. Stage the repo changes

Stage each change via lw-ingest behavior into:

• raw/repo/ for direct repo files
• raw/changes/ for diffs, commit ranges, PR summaries, release notes

When staging direct repo files, preserve enough path context to map back to the source repo. When staging change summaries, include:

• repo path
• remote
• default branch
• base SHA
• target SHA
• provider-backed or git-only mode

Update .llm-wiki/manifest.json with:

• last_checked_at
• last_seen_default_branch_sha
• last_repo_summary
• pending_changes
• any staged artifact registrations

Do not mutate wiki/ directly in this skill.

8. Decide what should happen next

Based on the authority and breadth of change, recommend or trigger:

• /lw-compile when there are real wiki impacts
• /lw-lint when changes are structural, broad, or high-authority
• /lw-reflect when changes are cross-cutting or likely to create synthesis/contradiction opportunities

Recommended boundary:

• lw-sync-repo inspects, classifies, stages, and updates manifest state
• orchestrator/operator decides whether to continue into compile/lint/reflect immediately

9. Print a repo-sync summary

Return:

• resolved repo path
• remote and default branch used
• provider mode used: provider-backed or git-only
• changed items reviewed
• authority classifications
• staged raw artifacts created
• likely affected wiki pages
• next recommended lifecycle steps

Hard rules

• do not assume every repo change deserves a customer-facing wiki change
• prioritize maintained truth sources over noisy or weaker sources
• if impact is ambiguous, preserve contradiction-friendly handling instead of forcing a clean story
• do not skip staging and manifest registration
• do not mutate the source repo beyond read-only inspection operations such as fetch
• do not let missing GitHub metadata block git-based inspection when the local repo is available