aria-knowledge

/audit-share — Batch-Review Personal Knowledge for Team Sharing

Walk personal knowledge files and IDEAS-BACKLOG.md entries; recommend a target _project-knowledge/ destination per item; present a batch summary; let the user approve, modify, or skip.

Step 0: Resolve Config

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

• knowledge_folder — required
• projects_enabled — required (must be true)
• projects_list — required (parsed into tag→path map)
• projects_shared_knowledge — required (comma-separated tag list; non-empty list of tags from projects_list); each tag in the list is a project enabled for shared knowledge
• author_tag — required (non-empty); fall back to deriving from git config user.name (first 2 chars of first + first 2 chars of last) if missing

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

If projects_shared_knowledge is empty/missing (or the legacy literal true): "Shared knowledge has no projects enabled. Run /setup and pick which projects to enable in the 'Which projects do you want to enable shared knowledge for?' prompt."

If projects_enabled: false or projects_list empty: "Shared knowledge requires the project tier. Run /setup to enable projects and configure your project list."

If author_tag is missing AND no derivable git user.name: "Author tag is required. Set author_tag in ~/.claude/aria-knowledge.local.md (e.g., init) or configure git config user.name."

Step 1: Scan Candidates

Walk these directories under {knowledge_folder}/:

• insights/
• decisions/
• approaches/
• rules/
• projects/<tag>/ for each tag in projects_shared_knowledge (the per-project opt-in list — projects not in this list stay personal-tier and are skipped here)

Plus IDEAS-BACKLOG.md entries from each project root:

• For each tag in projects_shared_knowledge, resolve to project root via ~/Projects/<path> (where <path> is the corresponding projects_list value).
• Probe <project-root>/_project-knowledge/IDEAS-BACKLOG.md first (post-feature location).
• Fall back to <project-root>/IDEAS-BACKLOG.md (pre-feature location, will trigger Step 7 migration on first execute).
• Parse the file by ### YYYY-MM-DD — {title} headers; treat each section as a candidate "entry."

Skip candidates when:

• File frontmatter contains a shared: array with an entry whose path matches the proposed target. (Already shared; no action needed.)
• File type is feedback or references (out of scope per design Q10 — feedback memories tend to be personal preferences; references are pointers to external systems that may not apply uniformly to teammates).

Step 2: Suggest Action Per Candidate

For each candidate, determine:

1. Project tag(s) — derived from any of three sources, unioned (matches /index Phase 4 Decision #9 path-derived convention so audit-share and /index see the same tag set):
2. Path-derived: if file path is under {knowledge_folder}/projects/<tag>/, that <tag> is implicit (even if not in YAML frontmatter).
3. Frontmatter project: field if present (split on , for multi-value).
4. Frontmatter tags: array: any tag matching a project in projects_shared_knowledge is treated as a share signal. A file tagged [architecture, cs, ss] with cs,ss in projects_shared_knowledge produces TWO share recommendations (one to cs, one to ss) — multi-tag files generate one recommendation per matching project, with independent destinations.
5. The literal value cross (in any source) marks the file as cross-cutting within its product group, not as cross-PROJECT-GROUP. Cross-PROJECT-GROUP relevance is naturally expressed by multi-tag (e.g., [cs, ss] = relevant to both cs and ss product groups) and is handled by the multi-tag fan-out above, not by cross.
6. Recommended action (per recommendation produced in step 1):
7. Tag is cross → recommend share-to-cross (will need user to pick destination repo at execute time, since cross items can land in any repo's cross/ subfolder; cross destinations may be any tag from projects_shared_knowledge).
8. Tag matches a tag in projects_shared_knowledge → recommend share-to-{project}.
9. Tag exists in projects_list but is NOT in projects_shared_knowledge → recommend skip with reason "project not enabled for shared knowledge (use /setup to enable)".
10. Otherwise (no tag detected, or tag not in projects_list) → recommend skip.
11. Target path — compute as follows. Multi-repo projects (those with a projects_groups entry) require sub-repo selection because the projects_list path resolves to a container, not a git repo:
12. Single-repo project (no projects_groups[tag] entry):
13. Repo-scoped: <project-root>/_project-knowledge/<YYYY-MM-DD>-<author_tag>-<slug>.md
14. Cross-stack: <destination-repo-root>/_project-knowledge/cross/<YYYY-MM-DD>-<author_tag>-<slug>.md
15. Multi-repo project (projects_groups[tag] is set, listing role:sub-repo pairs like backend: foo-backend, web: foo-web, mobile: foo-mobile):
16. Run role-detection heuristic on file content + frontmatter tags:
17. backend keywords: django, flask, fastapi, server-side, api, endpoint, jwt, oauth, auth, idor, impersonation, sql, database, migration, model, view, serializer, drf, rest, graphql resolver
18. web keywords: nextjs, next.js, react, frontend, client-side, app router, spa, redux, rtk, rtk-query, css, tailwind, ui component, hook, page, route component
19. mobile keywords: ios, android, react native, expo, swift, kotlin, swiftui, jetpack
20. Plus any custom roles defined in projects_groups[tag] — match keywords from the role name itself plus inferable tokens.
21. Score = count of matching keywords per role (case-insensitive whole-word match against body + tags).
22. Single dominant role (one role's score is ≥2× the next, AND ≥3 hits): recommend that role's sub-repo, repo-scoped destination.
23. Multiple roles tied or all low scores: recommend cross-stack → primary sub-repo's _project-knowledge/cross/.
24. Primary sub-repo = first role declared in projects_groups[tag] (declaration order, NOT alphabetical), OR an explicit primary: field if user has added one to the group entry. For example, given webapp: { backend: api-server, web: web-client, mobile: mobile-app }, primary is api-server.
25. Multi-repo paths:
26. Repo-scoped (dominant role detected): <project-root>/<role-sub-repo>/_project-knowledge/<YYYY-MM-DD>-<author_tag>-<slug>.md
27. Cross-stack (no dominant role): <project-root>/<primary-sub-repo>/_project-knowledge/cross/<YYYY-MM-DD>-<author_tag>-<slug>.md
28. Common to both shapes:
29. Date is today (the share date), not the original capture date.
30. Author is author_tag from config.
31. Slug is derived from the source filename (strip date prefix and extension) or from frontmatter title:.
32. Collision handling: if the target path already exists, append -2, -3, etc. to the slug until unique.
33. IDEAS-BACKLOG.md entries are special-cased: each entry promotes by appending to the project's IDEAS-BACKLOG.md, not by creating a new file. Path resolution mirrors step 3's single-vs-multi-repo logic — single-repo: <project-root>/_project-knowledge/IDEAS-BACKLOG.md; multi-repo: <project-root>/<primary-sub-repo>/_project-knowledge/IDEAS-BACKLOG.md (always primary, since IDEAS-BACKLOG entries are project-wide queue items not per-role). Cross-cutting ideas append to cross/IDEAS-BACKLOG.md instead.
34. Public-repo flag — for each unique target sub-repo (not container), run gh repo view --json visibility 2>/dev/null (cache result for the session). If visibility is PUBLIC, mark target as needing sanitization warn-prompt at execute time. If gh is unavailable, skip the chec