feat(#2792): namespace meta-skills + keyword-tag descriptions + context utilization guard (#2825)

* feat(#2792): namespace meta-skills retargeted at the post-#2790 surface

This branch is now based on #2790's HEAD (the consolidation PR) instead
of main, and every routing table targets the consolidated surface so a
user routed by a namespace meta-skill never lands at a deleted /
folded sub-skill.

Cross-PR inconsistencies the original PR #2825 carried (vs #2790):

  - ns-ideate routed to gsd-note / gsd-add-todo / gsd-add-backlog /
    gsd-plant-seed → all folded into gsd-capture by #2790. Now routes
    to gsd-capture (the parent picks the mode from the user's intent).
  - ns-context routed to gsd-scan and gsd-intel → folded into
    gsd-map-codebase --fast / --query by #2790. Now routes to those
    flag forms.
  - ns-manage routed all workspace intent to gsd-list-workspaces (a
    list-only entry) → CR also flagged the over-narrow target. #2790
    folds into gsd-workspace; routing now points there.
  - ns-workflow routed to gsd-research-phase → deleted outright by
    #2790. Removed.
  - ns-project routed to gsd-plan-milestone-gaps → deleted outright by
    #2790. Removed.
  - None of the namespaces previously surfaced #2790's new consolidated
    skills (gsd-capture, gsd-phase, gsd-config, gsd-workspace,
    gsd-progress). All five are now reachable through the routers.
  - extract_learnings → extract-learnings (canonicalized by #2858).

Defect fixes within the namespace skills:

  - Hyphen-form `name:` (gsd-workflow, …) per the canonical naming
    contract — the colon-form addressed CR's drift complaint.
  - `Skill` added to allowed-tools on every router. The body instructs
    "Invoke the matched skill directly using the Skill tool" — without
    Skill in the permission list the meta-skill cannot route at all.

New regression guard in tests/enh-2792-namespace-skills.test.cjs: every
gsd-* token in any namespace router's table column resolves to a
surviving commands/gsd/*.md file (or to a known consolidated parent for
flag-form targets like gsd-map-codebase --fast). This single test would
have caught every dead-end route the original PR shipped with.

Skill-count cap in tests/enh-2790-skill-consolidation.test.cjs now
filters out ns-*.md from its <= 63 cap. Namespace routers are
descriptor-only entries, not part of the consolidation surface that cap
is policing — they have their own contract in
tests/enh-2792-namespace-skills.test.cjs.

INVENTORY.md gains a "Namespace Meta-Skills" section with the 6 router
rows; INVENTORY-MANIFEST.json gains 6 entries; the headline count moves
59 → 65 to match.

Out of scope for this rebase: the gsd-health --context flag (PR #2825
advertised the contract but didn't implement it). That's a separate
feature concern and is left untouched here.

5908/5908 on `npm test`.

* feat(#2792): implement gsd-health --context utilization guard

The original PR #2825 advertised a `--context` flag on gsd-health with a
60%/70% utilization threshold table but never implemented the workflow
logic — CR caught it as a contract leak, the rebase deferred it. This
commit closes the gap with TDD red/green/refactor.

Math layer (pure):
  - get-shit-done/bin/lib/context-utilization.cjs
    classifyContextUtilization(tokensUsed, contextWindow) →
      { percent, state }
    State boundaries use the exact ratio:
      < 60% healthy / 60–70% warning / ≥ 70% critical (fracture point)
    Display percent rounded for humans. Throws TypeError on non-integer
    or out-of-range inputs.
  - STATES = Object.freeze({ HEALTHY, WARNING, CRITICAL }) exported
    so callers reference the names by symbol, not by literal string.

SDK CLI integration:
  - get-shit-done/bin/gsd-tools.cjs
    `validate context --tokens-used N --context-window M [--json]`
    routes to the classifier, owns the recommendation copy (the
    classifier intentionally does not — keeps the renderer free to
    evolve without touching the math layer or its tests), and uses
    core.output's rawValue path for the sync-flush guarantee.
  - sdk/src/query/validate.ts + sdk/src/query/index.ts
    TypeScript validateContext handler registered at 'validate.context'
    and 'validate context'. Mirrors the CJS classifier inline (15 lines
    of arithmetic; not worth a shared cross-language module).

User-facing wiring:
  - commands/gsd/health.md frontmatter advertises --context, body
    documents the three-state threshold table.
  - get-shit-done/workflows/health.md adds a `context_check` step
    that's reached only when --context is set. Step calls
    `gsd-sdk query validate.context` with self-reported tokensUsed and
    contextWindow, prints the SDK output verbatim, and ends. Includes
    a TEXT_MODE plain-text fallback for non-Claude runtimes per #2012.

Tests:
  - tests/context-utilization.test.cjs (17 tests) — pure-function
    contract: state thresholds at every boundary, percent rounding,
    input validation, return-shape (no recommendation field — that's
    the renderer's job).
  - tests/validate-context.test.cjs (9 tests) — SDK CLI plumbing:
    arg parsing errors, JSON vs human rendering, recommendation copy
    pinned per state.
  - tests/enh-2792-namespace-skills.test.cjs (4 new tests) — markdown
    contract: --context advertised in argument-hint, threshold table
    in command body, context_check step exists in workflow, step
    invokes gsd-sdk query validate.context with both flags.

Inventory bookkeeping:
  - docs/INVENTORY.md "CLI Modules" 31 → 32; new row for
    context-utilization.cjs.
  - docs/INVENTORY-MANIFEST.json mirror.

5939/5939 on `npm test`.

commands/gsd/health.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:health
 description: Diagnose planning directory health and optionally repair issues
-argument-hint: [--repair]
+argument-hint: "[--repair] [--context]"
 allowed-tools:
   - Read
   - Bash
@@ -10,6 +10,14 @@ allowed-tools:
 ---
 <objective>
 Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans.
+
+`--context` runs an orthogonal check: the running session's context utilization. The workflow asks for the model's tokensUsed + contextWindow, calls `gsd-sdk query validate.context`, and renders one of three states:
+
+| Utilization | State    | Action                                                |
+|-------------|----------|-------------------------------------------------------|
+| < 60%       | healthy  | no action — context is comfortable                    |
+| 60% – 70%   | warning  | recommend `/gsd-thread` to start fresh                |
+| ≥ 70%       | critical | reasoning quality may degrade past the fracture point |
 </objective>
 
 <execution_context>
@@ -18,5 +26,5 @@ Validate `.planning/` directory integrity and report actionable issues. Checks f
 
 <process>
 Execute the health workflow from @~/.claude/get-shit-done/workflows/health.md end-to-end.
-Parse --repair flag from arguments and pass to workflow.
+Parse `--repair` and `--context` flags from arguments and pass to workflow.
 </process>

commands/gsd/ns-context.md

@@ -0,0 +1,22 @@
+---
+name: gsd-context
+description: "codebase intelligence | map graphify docs learnings"
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Skill
+---
+
+Route to the appropriate codebase-intelligence skill based on the user's intent.
+`gsd-scan` and `gsd-intel` were folded into `gsd-map-codebase` flags by #2790.
+
+| User wants | Invoke |
+|---|---|
+| Map the full codebase structure | gsd-map-codebase |
+| Quick lightweight codebase scan | gsd-map-codebase --fast |
+| Query mapped intelligence files | gsd-map-codebase --query |
+| Generate a knowledge graph | gsd-graphify |
+| Update project documentation | gsd-docs-update |
+| Extract learnings from a completed phase | gsd-extract-learnings |
+
+Invoke the matched skill directly using the Skill tool.

commands/gsd/ns-ideate.md

@@ -0,0 +1,23 @@
+---
+name: gsd-ideate
+description: "exploration capture | explore sketch spike spec capture"
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Skill
+---
+
+Route to the appropriate exploration / capture skill based on the user's intent.
+`gsd-note`, `gsd-add-todo`, `gsd-add-backlog`, and `gsd-plant-seed` were folded
+into `gsd-capture` (with `--note`, default, `--backlog`, `--seed` modes) by
+#2790. The capture target lists pending todos via `--list`.
+
+| User wants | Invoke |
+|---|---|
+| Explore an idea or opportunity | gsd-explore |
+| Sketch out a rough design or plan | gsd-sketch |
+| Time-boxed technical spike | gsd-spike |
+| Write a spec for a phase | gsd-spec-phase |
+| Capture a thought (todo / note / backlog / seed) | gsd-capture |
+
+Invoke the matched skill directly using the Skill tool.

commands/gsd/ns-manage.md

@@ -0,0 +1,28 @@
+---
+name: gsd-manage
+description: "config workspace | workstreams thread update ship inbox"
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Skill
+---
+
+Route to the appropriate management skill based on the user's intent.
+`gsd-config` (settings + advanced + integrations + profile) and `gsd-workspace`
+(new + list + remove) are post-#2790 consolidated entries.
+
+| User wants | Invoke |
+|---|---|
+| Configure GSD settings (basic / advanced / integrations / profile) | gsd-config |
+| Manage workspaces (create / list / remove) | gsd-workspace |
+| Manage parallel workstreams | gsd-workstreams |
+| Continue work in a fresh context thread | gsd-thread |
+| Pause current work | gsd-pause-work |
+| Resume paused work | gsd-resume-work |
+| Update the GSD installation | gsd-update |
+| Ship completed work | gsd-ship |
+| Process inbox items | gsd-inbox |
+| Create a clean PR branch | gsd-pr-branch |
+| Undo the last GSD action | gsd-undo |
+
+Invoke the matched skill directly using the Skill tool.

commands/gsd/ns-project.md

@@ -0,0 +1,22 @@
+---
+name: gsd-project
+description: "project lifecycle | milestones audits summary"
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Skill
+---
+
+Route to the appropriate project / milestone skill based on the user's intent.
+`gsd-plan-milestone-gaps` was deleted by #2790 — gap planning now happens
+inline as part of `gsd-audit-milestone`'s output.
+
+| User wants | Invoke |
+|---|---|
+| Start a new project | gsd-new-project |
+| Create a new milestone | gsd-new-milestone |
+| Complete the current milestone | gsd-complete-milestone |
+| Audit a milestone for issues | gsd-audit-milestone |
+| Summarize milestone status | gsd-milestone-summary |
+
+Invoke the matched skill directly using the Skill tool.

commands/gsd/ns-review.md

@@ -0,0 +1,25 @@
+---
+name: gsd-review
+description: "quality gates | code review debug audit security eval ui"
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Skill
+---
+
+Route to the appropriate quality / review skill based on the user's intent.
+`gsd-code-review-fix` was absorbed by `gsd-code-review --fix` in #2790.
+
+| User wants | Invoke |
+|---|---|
+| Review code for quality and correctness | gsd-code-review |
+| Auto-fix code review findings | gsd-code-review --fix |
+| Audit UAT / acceptance testing | gsd-audit-uat |
+| Security review of a phase | gsd-secure-phase |
+| Evaluate AI response quality | gsd-eval-review |
+| Review UI for design and accessibility | gsd-ui-review |
+| Validate phase outputs | gsd-validate-phase |
+| Debug a failing feature or error | gsd-debug |
+| Forensic investigation of a broken system | gsd-forensics |
+
+Invoke the matched skill directly using the Skill tool.

commands/gsd/ns-workflow.md

@@ -0,0 +1,27 @@
+---
+name: gsd-workflow
+description: "workflow | discuss plan execute verify phase progress"
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Skill
+---
+
+Route to the appropriate phase-pipeline skill based on the user's intent.
+Sub-skill names below are post-#2790 consolidated targets — `gsd-phase`
+absorbs the former add/insert/remove/edit-phase commands and `gsd-progress`
+absorbs the former next/do commands.
+
+| User wants | Invoke |
+|---|---|
+| Gather context before planning | gsd-discuss-phase |
+| Clarify what a phase delivers | gsd-spec-phase |
+| Create a PLAN.md | gsd-plan-phase |
+| Execute plans in a phase | gsd-execute-phase |
+| Verify built features through UAT | gsd-verify-work |
+| Add / insert / remove / edit a phase | gsd-phase |
+| Advance to the next logical step | gsd-progress |
+| Offload planning to the ultraplan cloud | gsd-ultraplan-phase |
+| Cross-AI plan review convergence loop | gsd-plan-review-convergence |
+
+Invoke the matched skill directly using the Skill tool.