index

/index — Knowledge Index Builder

Scan all promoted knowledge files, normalize tags, detect issues, and regenerate {knowledge_folder}/index.md.

Step 0: Resolve Config

Read ~/.claude/aria-knowledge.local.md and extract:

• knowledge_folder — base path for all operations
• freeform_promotion_threshold — minimum file count before suggesting promotion (default: 3)
• staleness_threshold_months — months before a file is flagged stale (default: 6)
• projects_enabled — default false; controls whether project tier is scanned and indexed
• projects_list — default empty; comma-separated tag:path pairs; only relevant if projects_enabled: true
• projects_promotion_threshold — default 2; minimum projects sharing a similar pattern to surface as a cross-project promotion candidate
• projects_shared_knowledge — default empty; comma-separated list of project tags enabled for shared knowledge. When non-empty, scan each listed project's _project-knowledge/ folder for team-shared knowledge. Tags not in this list are skipped (their _project-knowledge/ folders, if any exist on disk, are NOT indexed).

If the config file doesn't exist, stop: "aria-knowledge is not configured. Run /setup to get started."

Step 1: Scan Promoted Folders

Scan these directories for .md files (excluding directory README stubs that only contain a few lines of boilerplate):

• {knowledge_folder}/approaches/
• {knowledge_folder}/decisions/
• {knowledge_folder}/guides/ (recursive — includes subdirectories)
• {knowledge_folder}/references/ (recursive — includes sources/ and other subdirectories)

Do NOT scan: archive/, intake/, rules/, top-level logs/*.md (audit-log files like config-audit-log.md, knowledge-audit-log.md, hook-debug.log), or root-level files (README.md, LOCAL.md, OVERVIEW.md, index.md).

Carve-out for review reports: the two subfolders logs/prospect/ and logs/retrospect/ ARE scanned as a separate "reviews tier" — see the dedicated sub-step below. Review reports use the same frontmatter scanning convention as cross-project files (tags, Last updated, first heading).

For each .md file found:

1. Read the file
2. Extract YAML frontmatter (content between --- markers at the top of the file)
3. From frontmatter, extract:
4. tags: — array of tags (e.g., tags: [api, pagination, django]). If missing, record as untagged.
5. Last updated: — date string (YYYY-MM-DD). If missing, record as unknown.
6. semantic-hints: — array of free-form phrases (e.g., semantic-hints: [cursor pagination, keyset pagination]). Optional; if missing, treat as empty list. Added 2.16.0.
7. Extract the first # heading as the file's description
8. Store: {path, tags[], hints[], description, last_updated, source: "cross-project"}

Report: "Scanned N files in approaches/, decisions/, guides/, references/."

Reviews tier scan (always run if either review subfolder exists)

After the cross-project scan, scan logs/prospect/ and logs/retrospect/ for review reports written by the /prospect and /retrospect skills.

For each .md file found in either subfolder:

1. Read the file
2. Extract YAML frontmatter — review reports have a richer schema than cross-project files. Pull:
3. tags: — array of tags. Always includes prospect or retrospect plus the scope keyword. If missing (legacy reports written before the structured-frontmatter format), record as untagged and emit a soft warning (one-line) suggesting the file be re-run or hand-tagged.
4. Last updated: — fall back to date: if Last updated: is absent (review reports use date: for the report-creation date).
5. type: — prospect or retrospect. Used to bucket the file under "Retrospects" or "Prospects" in the ## Review Index section of index.md (see Step 9).
6. scope: — the scope keyword (e.g., release, deployment, commit, plan).
7. tickets: — for cross-reference enrichment (consumed by /context).
8. Extract the first # heading as the file's description (typically "/prospect — <goal>" or "/retrospect — <goal>").
9. Store: {path, tags[], description, last_updated, source: "review", review_type: <prospect|retrospect>, scope: <keyword>, tickets: [...]}

Report: "Scanned R review reports across logs/prospect/ and logs/retrospect/ (P prospect, Q retrospect)."

If neither subfolder exists yet on disk, skip this sub-step silently (first run before any /prospect or /retrospect has been invoked).

Project tier scan (only if projects_enabled: true and projects_list is non-empty)

After the cross-project scan, scan the project tier:

For each tag:path pair in projects_list:

1. Glob {knowledge_folder}/projects/{tag}/**/*.md recursively
2. Exclude projects/{tag}/README.md (per-project navigation, not knowledge content)
3. Exclude projects/README.md (the projects/ tier README, plugin-managed)
4. For each file found, perform the same frontmatter extraction as above.
5. Path-derived tag union (Decision #9): automatically add {tag} to the file's tag set even if not in YAML frontmatter. The union of YAML tags + path tag is what gets indexed. This means project files don't have to manually include the project tag in their frontmatter.
6. Store: {path, tags[], description, last_updated, source: "project-specific", project: tag}

Report: "Scanned M files across N project subdirectories: [project tags]."

If projects_enabled: false or projects_list is empty, skip this sub-step entirely. Project tier files (if any exist on disk) won't be indexed.

Team-shared scan (only if projects_shared_knowledge list is non-empty)

After the project tier scan, scan each enabled project's _project-knowledge/ folder. Only projects whose tags appear in projects_shared_knowledge are scanned — non-listed projects are skipped, even if their _project-knowledge/ folders exist on disk.

For each tag in projects_shared_knowledge (parsed as comma-separated list):

1. Resolve the project root: look up the tag in projects_list to get its path, then resolve to ~/Projects/<path>. If the tag is not present in projects_list, log a warning and skip (config inconsistency — /setup validation should catch this, but defensive).
2. Determine scan locations based on whether the tag has a projects_groups entry (multi-repo project):
3. Single-repo project (no projects_groups[tag]): scan <project-root>/_project-knowledge/ directly.
4. Multi-repo project (projects_groups[tag] is set): the project-root is a container, not a repo. Iterate the role:sub-repo pairs in projects_groups[tag] (preserving declaration order), and for EACH sub-repo, scan <project-root>/<sub-repo>/_project-knowledge/. Skip sub-repos whose path doesn't exist on disk (sub-repo not yet cloned).
5. For each scan location determined in step 2, probe for _project-knowledge/. If the folder doesn't exist, skip that location (no team-shared knowledge yet there). Continue to next location (don't bail on the whole tag — sibling sub-repos may have content).
6. Glob <scan-location>/_project-knowledge/**/*.md recursively.
7. Exclude <scan-location>/_project-knowledge/README.md (auto-generated convention explainer, not knowledge content).
8. For each file found, perform frontmatter extraction as in the cross-project scan above.
9. Path-derived metadata:
10. If the file path is at <scan-location>/_project-knowledge/*.md (top level), categorize as team-shared with project: <tag> (always the parent project tag from projects_shared_knowledge, NOT the sub-repo name — sub-repo identity is captured in the absolute path stored in step 9).
11. If the file path is under <scan-location>/_project-knowledge/cross/*.md, categorize as team-shared-cross with project: cross.
12. The path-derived project tag is added to the file's tag set even if not in YAML frontmatter (same Decision #9 pattern as project tier).
13. **IDEAS