qwen-base 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/README.md +183 -0
  2. package/bin/install.js +227 -0
  3. package/package.json +42 -0
  4. package/src/commands/audit-claude-md.md +44 -0
  5. package/src/commands/audit-claude.md +45 -0
  6. package/src/commands/audit.md +33 -0
  7. package/src/commands/carl-hygiene.md +33 -0
  8. package/src/commands/groom.md +35 -0
  9. package/src/commands/history.md +27 -0
  10. package/src/commands/orientation/tasks/deep-why.md +132 -0
  11. package/src/commands/orientation/tasks/elevator-pitch.md +115 -0
  12. package/src/commands/orientation/tasks/initiatives.md +98 -0
  13. package/src/commands/orientation/tasks/key-values.md +130 -0
  14. package/src/commands/orientation/tasks/new-orientation.md +162 -0
  15. package/src/commands/orientation/tasks/north-star.md +97 -0
  16. package/src/commands/orientation/tasks/project-mapping.md +103 -0
  17. package/src/commands/orientation/tasks/reorientation.md +96 -0
  18. package/src/commands/orientation/tasks/surface-vision.md +113 -0
  19. package/src/commands/orientation/tasks/task-seeding.md +93 -0
  20. package/src/commands/orientation/templates/operator-json.md +88 -0
  21. package/src/commands/orientation.md +87 -0
  22. package/src/commands/pulse.md +33 -0
  23. package/src/commands/scaffold.md +33 -0
  24. package/src/commands/status.md +28 -0
  25. package/src/commands/surface-convert.md +35 -0
  26. package/src/commands/surface-create.md +34 -0
  27. package/src/commands/surface-list.md +27 -0
  28. package/src/commands/weekly-domain.md +34 -0
  29. package/src/commands/weekly.md +39 -0
  30. package/src/framework/context/base-principles.md +69 -0
  31. package/src/framework/frameworks/audit-strategies.md +53 -0
  32. package/src/framework/frameworks/claude-config-alignment.md +256 -0
  33. package/src/framework/frameworks/claudemd-strategy.md +158 -0
  34. package/src/framework/frameworks/satellite-registration.md +44 -0
  35. package/src/framework/tasks/audit-claude-md.md +171 -0
  36. package/src/framework/tasks/audit-claude.md +330 -0
  37. package/src/framework/tasks/audit.md +64 -0
  38. package/src/framework/tasks/carl-hygiene.md +142 -0
  39. package/src/framework/tasks/groom.md +157 -0
  40. package/src/framework/tasks/history.md +34 -0
  41. package/src/framework/tasks/pulse.md +83 -0
  42. package/src/framework/tasks/scaffold.md +389 -0
  43. package/src/framework/tasks/status.md +35 -0
  44. package/src/framework/tasks/surface-convert.md +143 -0
  45. package/src/framework/tasks/surface-create.md +184 -0
  46. package/src/framework/tasks/surface-list.md +42 -0
  47. package/src/framework/tasks/weekly-domain-create.md +173 -0
  48. package/src/framework/tasks/weekly.md +347 -0
  49. package/src/framework/templates/claudemd-template.md +102 -0
  50. package/src/framework/templates/workspace-json.md +96 -0
  51. package/src/framework/utils/scan-claude-dirs.py +549 -0
  52. package/src/hooks/_template.py +130 -0
  53. package/src/hooks/active-hook.py +178 -0
  54. package/src/hooks/apex-insights.py +169 -0
  55. package/src/hooks/backlog-hook.py +115 -0
  56. package/src/hooks/base-pulse-check.py +216 -0
  57. package/src/hooks/operator.py +53 -0
  58. package/src/hooks/psmm-injector.py +67 -0
  59. package/src/hooks/satellite-detection.py +320 -0
  60. package/src/packages/base-mcp/index.js +119 -0
  61. package/src/packages/base-mcp/package.json +10 -0
  62. package/src/packages/base-mcp/tools/entities.js +228 -0
  63. package/src/packages/base-mcp/tools/operator.js +106 -0
  64. package/src/packages/base-mcp/tools/projects.js +324 -0
  65. package/src/packages/base-mcp/tools/psmm.js +206 -0
  66. package/src/packages/base-mcp/tools/satellite.js +243 -0
  67. package/src/packages/base-mcp/tools/state.js +201 -0
  68. package/src/packages/base-mcp/tools/validate.js +121 -0
  69. package/src/skill/base.md +110 -0
  70. package/src/templates/operator.json +66 -0
  71. package/src/templates/workspace.json +76 -0
@@ -0,0 +1,33 @@
1
+ ---
2
+ name: base:pulse
3
+ description: Daily workspace health briefing
4
+ allowed-tools: [Read, Glob, Grep, Bash]
5
+ ---
6
+
7
+ <objective>
8
+ Workspace health briefing — drift score, stale areas, overdue grooming, quick status.
9
+
10
+ **When to use:** Session start, "what's the state of my workspace", daily check-in.
11
+ </objective>
12
+
13
+ <execution_context>
14
+ @{~/.qwen/commands/qwen-base/tasks/pulse.md}
15
+ @{~/.qwen/commands/qwen-base/context/base-principles.md}
16
+ </execution_context>
17
+
18
+ <context>
19
+ $ARGUMENTS
20
+
21
+ @.base/workspace.json
22
+ @.base/data/state.json
23
+ </context>
24
+
25
+ <process>
26
+ Follow task: @{~/.qwen/commands/qwen-base/tasks/pulse.md}
27
+ </process>
28
+
29
+ <success_criteria>
30
+ - [ ] Drift score calculated and displayed
31
+ - [ ] Stale areas identified
32
+ - [ ] Groom cadence checked
33
+ </success_criteria>
@@ -0,0 +1,33 @@
1
+ ---
2
+ name: base:scaffold
3
+ description: Set up BASE in a new workspace
4
+ argument-hint: "[--full]"
5
+ allowed-tools: [Read, Write, Edit, Glob, Bash, AskUserQuestion]
6
+ ---
7
+
8
+ <objective>
9
+ Guided workspace setup — scan, configure, install BASE infrastructure. Optional --full mode adds operational templates.
10
+
11
+ **When to use:** First-time BASE installation, "set up base", "scaffold my workspace".
12
+ </objective>
13
+
14
+ <execution_context>
15
+ @{~/.qwen/commands/qwen-base/tasks/scaffold.md}
16
+ @{~/.qwen/commands/qwen-base/templates/workspace-json.md}
17
+ @{~/.qwen/commands/qwen-base/templates/workspace-json.md}
18
+ </execution_context>
19
+
20
+ <context>
21
+ $ARGUMENTS
22
+ </context>
23
+
24
+ <process>
25
+ Follow task: @{~/.qwen/commands/qwen-base/tasks/scaffold.md}
26
+ </process>
27
+
28
+ <success_criteria>
29
+ - [ ] .base/ directory structure created
30
+ - [ ] workspace.json generated from scan
31
+ - [ ] state.json initialized
32
+ - [ ] Hooks and MCP servers installed (if --full)
33
+ </success_criteria>
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: base:status
3
+ description: Quick workspace health check
4
+ allowed-tools: [Read, Glob, Bash]
5
+ ---
6
+
7
+ <objective>
8
+ One-liner workspace health status — drift score and area summary.
9
+
10
+ **When to use:** Quick check, "workspace status", "how's my workspace".
11
+ </objective>
12
+
13
+ <execution_context>
14
+ @{~/.qwen/commands/qwen-base/tasks/status.md}
15
+ </execution_context>
16
+
17
+ <context>
18
+ @.base/workspace.json
19
+ @.base/data/state.json
20
+ </context>
21
+
22
+ <process>
23
+ Follow task: @{~/.qwen/commands/qwen-base/tasks/status.md}
24
+ </process>
25
+
26
+ <success_criteria>
27
+ - [ ] Health status displayed
28
+ </success_criteria>
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: base:surface-convert
3
+ description: Convert a markdown file into a data surface
4
+ argument-hint: "<file-path>"
5
+ allowed-tools: [Read, Write, Edit, Glob, Bash, AskUserQuestion]
6
+ ---
7
+
8
+ <objective>
9
+ Convert an existing @-mentioned markdown file into a structured data surface. Analyzes structure, proposes schema, migrates content.
10
+
11
+ **When to use:** User has a markdown file they want to convert to a structured surface.
12
+ </objective>
13
+
14
+ <execution_context>
15
+ @{~/.qwen/commands/qwen-base/tasks/surface-convert.md}
16
+ @.base/hooks/_template.py
17
+ </execution_context>
18
+
19
+ <context>
20
+ $ARGUMENTS
21
+
22
+ @.base/workspace.json
23
+ </context>
24
+
25
+ <process>
26
+ Follow task: @{~/.qwen/commands/qwen-base/tasks/surface-convert.md}
27
+ </process>
28
+
29
+ <success_criteria>
30
+ - [ ] .base/data/{name}.json created with migrated items
31
+ - [ ] .base/hooks/{name}-hook.py created
32
+ - [ ] workspace.json updated with surface registration
33
+ - [ ] settings.json updated with hook entry
34
+ - [ ] Original markdown file preserved
35
+ </success_criteria>
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: base:surface-create
3
+ description: Create a new data surface (guided)
4
+ argument-hint: "[surface-name]"
5
+ allowed-tools: [Read, Write, Edit, Glob, Bash, AskUserQuestion]
6
+ ---
7
+
8
+ <objective>
9
+ Create a new data surface through guided conversation. Generates JSON data file, injection hook, workspace.json registration, and settings.json hook entry.
10
+
11
+ **When to use:** User wants to track something new as a structured data surface.
12
+ </objective>
13
+
14
+ <execution_context>
15
+ @{~/.qwen/commands/qwen-base/tasks/surface-create.md}
16
+ @.base/hooks/_template.py
17
+ </execution_context>
18
+
19
+ <context>
20
+ $ARGUMENTS
21
+
22
+ @.base/workspace.json
23
+ </context>
24
+
25
+ <process>
26
+ Follow task: @{~/.qwen/commands/qwen-base/tasks/surface-create.md}
27
+ </process>
28
+
29
+ <success_criteria>
30
+ - [ ] .base/data/{name}.json created
31
+ - [ ] .base/hooks/{name}-hook.py created
32
+ - [ ] workspace.json updated with surface registration
33
+ - [ ] settings.json updated with hook entry
34
+ </success_criteria>
@@ -0,0 +1,27 @@
1
+ ---
2
+ name: base:surface-list
3
+ description: Show all registered data surfaces
4
+ allowed-tools: [Read, Bash]
5
+ ---
6
+
7
+ <objective>
8
+ Display all registered data surfaces with item counts and hook status.
9
+
10
+ **When to use:** User wants to see what surfaces exist.
11
+ </objective>
12
+
13
+ <execution_context>
14
+ @{~/.qwen/commands/qwen-base/tasks/surface-list.md}
15
+ </execution_context>
16
+
17
+ <context>
18
+ @.base/workspace.json
19
+ </context>
20
+
21
+ <process>
22
+ Follow task: @{~/.qwen/commands/qwen-base/tasks/surface-list.md}
23
+ </process>
24
+
25
+ <success_criteria>
26
+ - [ ] All registered surfaces displayed with counts
27
+ </success_criteria>
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: base:weekly-domain
3
+ description: Create a custom domain phase for the weekly ritual
4
+ allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
5
+ ---
6
+
7
+ <objective>
8
+ Guided creation of a custom domain phase for /base:weekly. Walks the user through defining what to check, what tools to use, what questions to ask, and what output to produce.
9
+
10
+ **When to use:** "Add a domain to my weekly", "create a weekly domain phase", "I want to track X in my weekly".
11
+ </objective>
12
+
13
+ <execution_context>
14
+ @{~/.qwen/commands/qwen-base/tasks/weekly-domain-create.md}
15
+ </execution_context>
16
+
17
+ <context>
18
+ $ARGUMENTS
19
+
20
+ @.base/weekly.json
21
+ </context>
22
+
23
+ <process>
24
+ Follow task: @{~/.qwen/commands/qwen-base/tasks/weekly-domain-create.md}
25
+ </process>
26
+
27
+ <success_criteria>
28
+ - [ ] User described the domain area
29
+ - [ ] Data sources identified (with tool discovery if needed)
30
+ - [ ] Weekly questions defined
31
+ - [ ] Position in weekly flow chosen
32
+ - [ ] Output type specified
33
+ - [ ] Domain phase config written to weekly.json
34
+ </success_criteria>
@@ -0,0 +1,39 @@
1
+ ---
2
+ name: base:weekly
3
+ description: Weekly review and planning ritual
4
+ allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
5
+ ---
6
+
7
+ <objective>
8
+ Guided weekly ritual — close the week, plan the next, run maintenance, lock in priorities with calendar events.
9
+
10
+ **When to use:** Weekly planning, "run my weekly", "weekly review", "time for my weekly".
11
+ </objective>
12
+
13
+ <execution_context>
14
+ @{~/.qwen/commands/qwen-base/tasks/weekly.md}
15
+ @{~/.qwen/commands/qwen-base/context/base-principles.md}
16
+ </execution_context>
17
+
18
+ <context>
19
+ $ARGUMENTS
20
+
21
+ @.base/workspace.json
22
+ @.base/data/state.json
23
+ @.base/weekly.json
24
+ </context>
25
+
26
+ <process>
27
+ Follow task: @{~/.qwen/commands/qwen-base/tasks/weekly.md}
28
+ </process>
29
+
30
+ <success_criteria>
31
+ - [ ] Week reviewed (daily logs consumed if available)
32
+ - [ ] Calendar audited with rules applied
33
+ - [ ] Workspace groomed (drift score updated)
34
+ - [ ] Priority stack set (outcome-based, aligned to north star)
35
+ - [ ] Backlog triaged (overdue items processed)
36
+ - [ ] Domain phases executed (if configured)
37
+ - [ ] Blockers identified, follow-ups queued
38
+ - [ ] Week committed — calendar events created, weekly.json entry logged
39
+ </success_criteria>
@@ -0,0 +1,69 @@
1
+ # BASE Principles
2
+
3
+ ## Core Laws
4
+
5
+ 1. **If it's not current, it's harmful.** Stale context documents feed AI bad information. Maintenance isn't optional.
6
+ 2. **Every file earns its place.** If you can't explain why it's here in 5 seconds, it moves or dies.
7
+ 3. **Archive > delete.** When in doubt, archive. You can always delete later. You can't un-delete.
8
+ 4. **The workspace is the product.** Treat it like production code, not a scratch pad.
9
+ 5. **Clean as you go.** The best time to file something correctly is when you create it. The second best time is now.
10
+ 6. **Scaffold generates manifest. Manifest drives everything.** One configuration point. No manual bookkeeping.
11
+ 7. **Tools register themselves.** PAUL projects auto-register with BASE. No human memory required.
12
+
13
+ ## Drift Score
14
+
15
+ Drift is the gap between documented state and actual state. Measured in days-overdue across all tracked areas.
16
+
17
+ - **0** — Everything current. Workspace is clean.
18
+ - **1-7** — Minor drift. Normal during execution sprints. Fix at next groom.
19
+ - **8-14** — Moderate drift. Context documents are likely misleading AI. Groom soon.
20
+ - **15+** — Critical drift. Sessions are operating on stale context. Groom NOW.
21
+
22
+ ## Maintenance Cadence
23
+
24
+ | What | Default Cadence | Override |
25
+ |------|----------------|---------|
26
+ | projects.json | Every session or weekly | workspace.json |
27
+ | Project directory | Monthly | workspace.json |
28
+ | Tools/MCP | Monthly | workspace.json |
29
+ | System layer | Monthly | workspace.json |
30
+ | Full audit | Quarterly or after major shifts | On demand |
31
+
32
+ ## Backlog Rules
33
+
34
+ Items have time-based properties enforced by grooming:
35
+
36
+ - **Added** — auto-set when item enters backlog
37
+ - **Review-by** — priority-based: High=7d, Medium=14d, Low=30d
38
+ - **Staleness** — 2x review-by threshold. Auto-archive if reached without action.
39
+
40
+ During groom: items past review-by surface as "decide or kill." Items past staleness auto-archive with a note.
41
+
42
+ ## Graduation Flow
43
+
44
+ Backlog items don't sit forever. They graduate to active when the operator is ready to work on them.
45
+
46
+ ```
47
+ BACKLOG (status=backlog in projects.json)
48
+ → ACTIVE (status updated to in_progress/todo via base_update_project)
49
+ → DONE (archived via base_archive_project with outcome)
50
+ ```
51
+
52
+ **TASKS vs PROJECTS:** A task is bounded — it has a finish line. "Extract .mcp.json secrets" is a task. "Build the CARL MCP server" might start as a task but could become a project if it grows. The operator decides during groom.
53
+
54
+ **Graduation is never automatic.** The groom flow asks explicitly: "Ready to work on any backlog items?" The operator decides what graduates and where it lands.
55
+
56
+ **Items can also move backward:** An active project that loses priority can return to backlog status. A project that stalls can move to DEFERRED. Nothing is permanent.
57
+
58
+ ## Scaffold Modes
59
+
60
+ BASE scaffold operates in two modes:
61
+
62
+ - **Standard** (`/base:scaffold`) — Data layer only. Creates `.base/` with workspace.json, `.base/data/state.json`, ROADMAP.md. Scans and tracks what exists. Framework-agnostic.
63
+ - **Full** (`/base:scaffold --full`) — Data layer + projects.json + entities.json. Offers CLAUDE.md audit. The "batteries included" version for AI builders who want the full system.
64
+
65
+ Standard mode works for any workspace. Full mode provides Chris's proven operational structure.
66
+
67
+ ## File Location
68
+
69
+ BASE operates strictly out of `.base/`. All data (projects.json, entities.json, state.json, psmm.json) lives in `.base/data/`. Configuration (workspace.json) and documentation (ROADMAP.md) live in `.base/`. Data is accessed via MCP tools (`base_list_projects`, `base_add_project`, `base_update_project`, `base_get_state`, etc.). `.base/data/` is the canonical location for all structured data.
@@ -0,0 +1,53 @@
1
+ # Audit Strategies
2
+
3
+ Reusable audit strategies that can be applied to any workspace area. The workspace manifest (`workspace.json`) maps areas to strategies. The audit command reads the manifest and applies the appropriate strategy to each area.
4
+
5
+ ## Strategies
6
+
7
+ ### staleness
8
+ **Applies to:** Data files (projects.json, state.json, any tracked document)
9
+ **What it does:** Check file modification timestamps against configured thresholds. Flag files past their groom cadence.
10
+ **Config:**
11
+ - `threshold_days` — days after which the file is considered stale
12
+ **Output:** List of stale files with age, recommended action (update or review)
13
+
14
+ ### classify
15
+ **Applies to:** Directories with lifecycle items (projects/, clients/)
16
+ **What it does:** List all items in the directory. For each, present to operator for classification: active, archive, or delete. Check for planning docs, recent activity, git history.
17
+ **Config:**
18
+ - `states` — classification options (default: ["active", "archive", "delete"])
19
+ - `archive_path` — where archived items go (default: `{path}/_archive/`)
20
+ **Output:** Classification decisions, items moved to archive, items deleted
21
+
22
+ ### cross-reference
23
+ **Applies to:** Tools/servers that have a config file mapping (e.g., MCP servers vs .mcp.json)
24
+ **What it does:** Compare directory contents against a configuration file. Identify directories not referenced in config (orphaned) and config entries pointing to missing directories (broken).
25
+ **Config:**
26
+ - `config_file` — path to the configuration file to cross-reference
27
+ **Output:** Orphaned items, broken references, recommendations
28
+
29
+ ### dead-code
30
+ **Applies to:** System directories (hooks, commands, skills)
31
+ **What it does:** Scan for files that appear unused — no references from other files, no recent invocations, no clear purpose. Presents findings for human decision.
32
+ **Config:**
33
+ - `reference_check` — whether to search for references in other files (default: true)
34
+ **Output:** Potentially dead files with evidence, operator decides keep/delete
35
+
36
+ ### pipeline-status
37
+ **Applies to:** Content pipelines, task queues, any workflow with stages
38
+ **What it does:** Check items in each pipeline stage. Flag stuck items (in same stage too long), empty stages, bottlenecks.
39
+ **Config:**
40
+ - `stages` — ordered list of pipeline stages
41
+ - `stuck_threshold_days` — days in one stage before flagging
42
+ **Output:** Pipeline health report, stuck items, stage distribution
43
+
44
+ ## Extending Strategies
45
+
46
+ Custom strategies can be added for workspace-specific needs. A strategy is defined by:
47
+ 1. A name (kebab-case)
48
+ 2. What it applies to (description)
49
+ 3. What it checks (logic)
50
+ 4. What config it needs (parameters)
51
+ 5. What it outputs (findings format)
52
+
53
+ Add custom strategies to this file and reference them in `workspace.json`.
@@ -0,0 +1,256 @@
1
+ # Claude Config Alignment Strategy
2
+
3
+ Standalone strategy for auditing `.qwen/` directory sprawl across a workspace. Discovers all `.qwen/` directories, catalogs their contents, classifies each item against a global/workspace/project hierarchy, and produces a remediation plan.
4
+
5
+ Designed to be composed into any audit workflow that touches the system layer. The `/base:audit-claude` command references this strategy directly. The general `/base:audit` can compose it in when running system-layer checks.
6
+
7
+ ---
8
+
9
+ ## When to Use
10
+
11
+ - During initial BASE setup on an existing workspace (lots of legacy `.qwen/` dirs)
12
+ - As part of periodic workspace audits
13
+ - After installing a new tool/skill globally and wanting to clean up project-level copies
14
+ - When the user suspects their Claude Code config is fragmented
15
+
16
+ ---
17
+
18
+ ## Discovery Rules
19
+
20
+ ### What to scan
21
+ - All directories named `.claude` under the workspace root
22
+ - Recursively (projects may nest: `apps/foo/bar/.qwen/`)
23
+
24
+ ### What to skip
25
+ - `node_modules/` — third-party packages may contain `.qwen/` dirs
26
+ - `_archive/` — archived projects are frozen, don't audit
27
+ - `.git/` — git internals
28
+ - `vendor/`, `dist/`, `build/` — build artifacts
29
+
30
+ ### What to catalog per directory
31
+ For each discovered `.qwen/` directory, record:
32
+ - **Path** (relative to workspace root)
33
+ - **hooks/** — list filenames
34
+ - **commands/** — list subdirectories and files
35
+ - **skills/** — list skill directories
36
+ - **rules/** — list files
37
+ - **settings.json** — exists? contents summary
38
+ - **settings.local.json** — exists? contents summary
39
+ - **Other files** — anything unexpected
40
+
41
+ ---
42
+
43
+ ## Git Boundary Awareness
44
+
45
+ Understanding git boundaries is critical for correct classification. The scanner dataset includes `git_boundary` data for each directory.
46
+
47
+ ### How git boundaries affect visibility
48
+
49
+ - **`has_own_git: true`** — This project has its own git root. It does NOT see the workspace root `.qwen/` or workspace `.mcp.json`. It only sees global `~/.qwen/` + its own `.qwen/`.
50
+ - **`has_own_git: false`** — This project inherits the workspace root. It sees global `~/.qwen/` + workspace root `.qwen/` + its own `.qwen/`.
51
+
52
+ ### What this changes about classification
53
+
54
+ If a project has its own git root and contains a hook that also exists in the workspace root `.qwen/`, that's **not a duplicate running twice** — the workspace root version is invisible to that project. Removing the local copy would leave the project with NO version of that hook.
55
+
56
+ For own-git projects, the right framing is:
57
+ - Does a current version exist in **global** `~/.qwen/`? If yes, the local copy is a true DUPLICATE (global is always visible).
58
+ - Does a version only exist in **workspace root** `.qwen/`? Then the local copy is the project's ONLY access to that functionality. The right recommendation is PROMOTE_TO_GLOBAL — centralize it so all projects benefit, then clean up local copies.
59
+ - Is the local copy an outdated version of something in a baseline? It's DIVERGED.
60
+
61
+ ---
62
+
63
+ ## Classification Rules
64
+
65
+ Each item found in a project-level `.qwen/` must be classified into exactly one category. These rules define how.
66
+
67
+ **Classification order:** TEMPLATE → ACCIDENTAL → DUPLICATE → DIVERGED → PROMOTE_TO_GLOBAL → STALE → GLOBAL_CANDIDATE → PROJECT_SPECIFIC
68
+
69
+ ### DUPLICATE — Exists in a visible baseline, safe to remove
70
+
71
+ An item is a DUPLICATE if:
72
+ - Its MD5 hash matches a file in a baseline the project can **actually see**
73
+ - Global baseline (`~/.qwen/`): always checked — global is always visible
74
+ - Workspace root baseline (`.qwen/`): only checked if `has_own_git: false`
75
+ - A match against a **non-visible** baseline (workspace root for own-git projects) is NOT a duplicate — see PROMOTE_TO_GLOBAL
76
+ - Common examples: hooks copied into project dirs that now run globally, skills that were installed globally after being copied locally
77
+
78
+ **Verification before removal:**
79
+ 1. Confirm the global version is the current/active version (not the other way around)
80
+ 2. Confirm the project's `settings.json` doesn't reference the local copy with a relative path that would break if removed
81
+ 3. If the local copy has modifications not in the global version, flag as DIVERGED instead
82
+
83
+ ### DIVERGED — Local copy differs from global
84
+
85
+ An item is DIVERGED if:
86
+ - A version exists both locally and globally
87
+ - The local copy has meaningful differences (not just whitespace or path variations)
88
+ - Requires human decision: merge local changes into global? Keep local override? Or discard local changes?
89
+
90
+ **Never auto-resolve diverged items. Always present both versions and ask.**
91
+
92
+ ### PROMOTE_TO_GLOBAL — Centralize to global, then clean up copies
93
+
94
+ An item is PROMOTE_TO_GLOBAL if:
95
+ - It exists in workspace root `.qwen/` (or the same pattern appears across multiple own-git projects) but NOT in global `~/.qwen/`
96
+ - For own-git projects: a file matching a non-visible baseline (workspace root) is NOT a duplicate — it's a signal something should be centralized
97
+ - When multiple projects have the same hook with the same MD5, that's strong evidence it belongs in global
98
+ - This is the most valuable finding: "put this in global and stop copying it into every project"
99
+
100
+ **PROMOTE_TO_GLOBAL is about removing the need for copies.** Once promoted, all project copies become true DUPLICATES (global is always visible) and can be safely removed.
101
+
102
+ **Promotion is a suggestion, never automatic.** After promoting to global, the global `settings.json` must also register the hook or it won't fire.
103
+
104
+ ### GLOBAL_CANDIDATE — Should be promoted to global (single occurrence)
105
+
106
+ An item is a GLOBAL_CANDIDATE if:
107
+ - It exists in a project-level `.qwen/` but NOT in global
108
+ - It serves a user-level purpose (not project-specific)
109
+ - It would be useful across multiple projects
110
+ - Examples: a custom skill the user installed in one project but uses everywhere, a hook that provides general utility
111
+
112
+ **Promotion is a suggestion, never automatic.** Present the item, explain why it's a candidate, let operator decide.
113
+
114
+ ### PROJECT_SPECIFIC — Legitimately belongs here
115
+
116
+ An item is PROJECT_SPECIFIC if:
117
+ - It references project-local paths, configs, or conventions
118
+ - It only makes sense in the context of this specific project
119
+ - Examples: project-specific commands, MCP server lists tailored to that project's stack, hooks that interact with project-local files
120
+
121
+ **These stay. Note them for reference but take no action.**
122
+
123
+ ### STALE — References things that no longer exist
124
+
125
+ An item is STALE if:
126
+ - settings.json references MCP servers that aren't in the current `.mcp.json` or global config
127
+ - hooks reference scripts or tools that have been renamed or removed
128
+ - Settings use old configuration patterns that Claude Code no longer supports
129
+ - The `.qwen/` directory hasn't been modified in 60+ days AND the project itself shows no recent activity
130
+
131
+ **Present specific evidence of staleness. Never assume — prove it.**
132
+
133
+ ### ACCIDENTAL — Clearly unintentional
134
+
135
+ An item is ACCIDENTAL if:
136
+ - Nested `.qwen/.qwen/` directories
137
+ - Empty `.qwen/` directories (no files at all)
138
+ - `.qwen/` inside directories that aren't projects (temp dirs, scratch folders)
139
+
140
+ **Safe to remove, but still confirm with operator.**
141
+
142
+ ### TEMPLATE — Intentional scaffold template
143
+
144
+ An item is TEMPLATE if:
145
+ - It lives in a directory named `_template/`, `template/`, or `templates/`
146
+ - It contains placeholder values (e.g., `{{PROJECT_NAME}}`)
147
+ - It's designed to be copied, not used directly
148
+
149
+ **Never modify templates. Note them and move on.**
150
+
151
+ ---
152
+
153
+ ## Settings Reconciliation
154
+
155
+ Project-level `settings.json` and `settings.local.json` require special handling because they override global settings.
156
+
157
+ ### Check for
158
+ 1. **Hook definitions that duplicate global hooks** — If global `settings.json` already runs `base-pulse-check.py` on UserPromptSubmit, a project that also defines it runs it twice (or runs a stale version)
159
+ 2. **Stale MCP server references** — Server names change. Old lists reference servers that no longer exist
160
+ 3. **Empty hook arrays** — `"UserPromptSubmit": []` overrides global hooks with nothing, potentially breaking the user's setup
161
+ 4. **Permission overrides** — Project-level allow/deny that may conflict with or duplicate global permissions
162
+ 5. **enabledMcpjsonServers** — Lists that reference old server names
163
+
164
+ ### Critical safety rule
165
+ **An empty hooks array `[]` in a project settings.json OVERRIDES the global hooks with nothing.** This is the most dangerous pattern — it silently disables all hooks for that project. Always flag this explicitly.
166
+
167
+ ---
168
+
169
+ ## Remediation Safety Protocol
170
+
171
+ This is the most important section. `.qwen/` configuration is what makes Claude Code work. A broken config means a broken development environment. Every remediation action must follow these rules:
172
+
173
+ ### Before any change
174
+ 1. **Explain what will change and why** — No "cleaning up your config." Say exactly: "Removing `apps/casegate-v2/.qwen/hooks/carl-hook.py` because an identical version runs globally from `~/.qwen/hooks/dynamic-rules-loader.py`. The global hook already fires on every prompt in every project."
175
+ 2. **Show evidence** — Side-by-side comparison, file dates, path references
176
+ 3. **Wait for explicit approval** — Not "I'll go ahead and clean these up." Ask: "Approve this removal? [y/n]"
177
+
178
+ ### During changes
179
+ 4. **One category at a time** — Process all ACCIDENTAL items first (lowest risk), then DUPLICATES, then STALE, then DIVERGED. Save GLOBAL_CANDIDATE promotions for last.
180
+ 5. **Verify after each change** — After removing a hook, confirm the project's settings.json no longer references it. After removing a skill, confirm no commands reference it.
181
+ 6. **Never delete settings.json itself** — Even if everything in it is stale. The file's existence may matter. Clean its contents instead, or flag for operator to remove manually.
182
+
183
+ ### After all changes
184
+ 7. **Summary report** — What was changed, what was kept, what needs manual follow-up
185
+ 8. **Recommend a test** — "Open Claude Code in {project} and verify hooks fire correctly"
186
+
187
+ ### What this workflow NEVER does
188
+ - Modify `~/.qwen/` (global config) without explicit promotion approval
189
+ - Delete a `.qwen/` directory entirely (may have gitignore or settings implications)
190
+ - Batch-delete without per-item confirmation
191
+ - Assume a "messy" config is wrong — it may be working exactly as intended
192
+ - Move files between directories (copy + verify + then remove original)
193
+
194
+ ---
195
+
196
+ ## Output Format
197
+
198
+ The discovery phase produces an inventory. Present it as:
199
+
200
+ ```
201
+ ## .qwen/ Directory Inventory
202
+
203
+ Found {N} .qwen/ directories ({N} excluding templates and root).
204
+
205
+ ### {relative/path/.qwen/}
206
+ hooks/: carl-hook.py, get-current-time-cst.py
207
+ settings.json: yes (hooks: 2 UserPromptSubmit)
208
+ settings.local.json: yes (MCP servers: 12)
209
+ skills/: ui-ux-pro-max/
210
+ commands/: (none)
211
+ Last modified: 2026-02-26
212
+
213
+ Classification:
214
+ - hooks/carl-hook.py → DUPLICATE (identical to ~/.qwen/hooks/dynamic-rules-loader.py)
215
+ - hooks/get-current-time-cst.py → DUPLICATE (identical to ~/.qwen/hooks/get-current-time-cst.sh)
216
+ - settings.json hooks → STALE (references local hook paths that would be removed)
217
+ - settings.local.json → PROJECT_SPECIFIC (MCP server list is project-tailored)
218
+ - skills/ui-ux-pro-max/ → DUPLICATE (exists at ~/.qwen/skills/ui-ux-pro-max/)
219
+ ```
220
+
221
+ The remediation phase groups by action type and risk level:
222
+
223
+ ```
224
+ ## Remediation Plan
225
+
226
+ ### Safe Removals (ACCIDENTAL)
227
+ 1. apps/hunter-exotics/.qwen/.qwen/ — nested .claude dir (accidental)
228
+ Action: Delete entire nested directory
229
+ Risk: None
230
+
231
+ ### Duplicate Removals
232
+ 2. apps/casegate-v2/.qwen/hooks/carl-hook.py — identical to global
233
+ Action: Delete file
234
+ Risk: Low — must also clean settings.json hook reference
235
+
236
+ (... etc, one per item ...)
237
+
238
+ ### Requires Decision (DIVERGED)
239
+ 5. apps/hunter-exotics/.qwen/settings.local.json — has project-specific MCP list
240
+ Local version: [12 servers including project-specific ones]
241
+ Global version: [different set]
242
+ Recommendation: Keep as PROJECT_SPECIFIC
243
+ ```
244
+
245
+ ---
246
+
247
+ ## Composability
248
+
249
+ This strategy is a standalone reference document. It does not modify or depend on other strategy files. Any workflow can compose it in:
250
+
251
+ - `/base:audit-claude` — reads this strategy directly as its framework
252
+ - `/base:audit` — can reference this when auditing the system-layer area
253
+ - `/base:groom` — can optionally flag `.qwen/` drift during system-layer groom step
254
+ - Manual invocation — an operator can ask "audit my .claude dirs" and Claude reads this file
255
+
256
+ No registration in workspace.json is required. No modification to audit-strategies.md is needed.