@nforma.ai/nforma 0.2.1 → 0.28.0

package/commands/{qgsd → nf}/observe.md

@@ -1,6 +1,6 @@
 ---
-name: qgsd:observe
-description: Fetch issues and drifts from configured sources, render dual-table output, and write to debt ledger. Replaces /qgsd:triage.
+name: nf:observe
+description: Fetch issues and drifts from configured sources, render dual-table output, and write to debt ledger. Replaces /nf:triage.
 argument-hint: "[--source github|sentry|sentry-feedback|bash|internal] [--since 24h|7d] [--limit N]"
 allowed-tools:
   - Read
@@ -11,9 +11,9 @@ allowed-tools:
 ---
 
 <objective>
-Aggregate issues and drifts from all configured sources, deduplicate, render a prioritized dual-table output (Issues + Drifts), write observations to the debt ledger, and route the selected issue to the right QGSD workflow.
+Aggregate issues and drifts from all configured sources, deduplicate, render a prioritized dual-table output (Issues + Drifts), write observations to the debt ledger, and route the selected issue to the right nForma workflow.
 
-This command is the project's unified "what's broken right now?" entry point. It replaces `/qgsd:triage` with debt-aware persistence and dual-table rendering.
+This command is the project's unified "what's broken right now?" entry point. It replaces `/nf:triage` with debt-aware persistence and dual-table rendering.
 </objective>
 
 <process>
@@ -46,7 +46,7 @@ The loader automatically:
 Display:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- QGSD > OBSERVE: No sources configured
+ nForma > OBSERVE: No sources configured
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Create .planning/observe-sources.md to configure issue sources.
 ```
@@ -67,7 +67,7 @@ if (!$SOURCE_FILTER || $SOURCE_FILTER === 'internal') {
 // Critical: check for empty sources AFTER internal injection
 if (config.sources.length === 0) {
   // Display "no sources" message only if sources is empty AFTER internal source injection
-  display("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n QGSD > OBSERVE: No sources configured\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nCreate .planning/observe-sources.md to configure issue sources.");
+  display("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n nForma > OBSERVE: No sources configured\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nCreate .planning/observe-sources.md to configure issue sources.");
   stop();
 }
 ```
@@ -80,19 +80,21 @@ Import handler functions and register them with the registry:
 
 ```javascript
 const { registerHandler } = require('./bin/observe-registry.cjs');
-const { handleGitHub, handleSentry, handleSentryFeedback, handleBash, handleInternal } = require('./bin/observe-handlers.cjs');
+const { handleGitHub, handleSentry, handleSentryFeedback, handleBash, handleInternal, handleUpstream, handleDeps } = require('./bin/observe-handlers.cjs');
 
 registerHandler('github', handleGitHub);
 registerHandler('sentry', handleSentry);
 registerHandler('sentry-feedback', handleSentryFeedback);
 registerHandler('bash', handleBash);
 registerHandler('internal', handleInternal);
+registerHandler('upstream', handleUpstream);
+registerHandler('deps', handleDeps);
 ```
 
 Display dispatch header:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- QGSD > OBSERVE: Fetching from N source(s)...
+ nForma > OBSERVE: Fetching from N source(s)...
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -163,7 +165,7 @@ Display the output.
 If total issues = 0 and no drifts:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- QGSD > OBSERVE: All clear — no open issues found
+ nForma > OBSERVE: All clear — no open issues found
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Sources checked: <list>
 ```
@@ -224,25 +226,56 @@ Enter issue # to work on, "ack N" to acknowledge, "solve" for all internal issue
 **If user enters a number:**
 - Load the full issue details (title, URL, meta) for that index.
 - Determine routing:
-  - If the issue has `source_type: 'internal'` and `_route` metadata: use the `_route` value as the suggested action (example: unfinished quick task suggests `/qgsd:quick "original-slug"`, debug session suggests `/qgsd:debug --resume`)
+  - If the issue has `source_type: 'internal'` and `_route` metadata: use the `_route` value as the suggested action (example: unfinished quick task suggests `/nf:quick "original-slug"`, debug session suggests `/nf:debug --resume`)
+  - If the issue has `issue_type: 'upstream'`: route to **upstream evaluation** (see below)
   - Otherwise, routing by severity:
-    - `severity: error` or `severity: bug` → suggest `/qgsd:debug`
-    - `severity: warning` or `severity: info` → suggest `/qgsd:quick`
+    - `severity: error` or `severity: bug` → suggest `/nf:debug`
+    - `severity: warning` or `severity: info` → suggest `/nf:quick`
 - Display:
   ```
   ◆ Issue: <title>
     URL: <url>
     Meta: <meta>
 
-  Suggested action: /qgsd:debug "<title> — <meta>"
+  Suggested action: /nf:debug "<title> — <meta>"
   Run it? [Y/n]
   ```
 - If confirmed, invoke the suggested skill with the issue as context.
 
+**Upstream evaluation routing (issue_type: 'upstream'):**
+
+When the user selects an upstream item, do NOT blindly suggest porting it. Instead:
+
+1. Fetch the release notes or PR diff from the upstream URL (use `gh release view <tag> --repo <repo> --json body` or `gh pr view <number> --repo <repo> --json body,files`)
+2. Identify the areas of our codebase that overlap with the upstream change
+3. **Compare quality**: For each overlapping area, assess whether:
+   - Our implementation is already equivalent or better → `SKIP` (we diverged for good reason or already have it)
+   - The upstream change introduces something we lack → `CANDIDATE` (worth porting)
+   - The upstream change conflicts with our architecture → `INCOMPATIBLE` (their approach doesn't fit our patterns)
+4. Display the evaluation:
+   ```
+   ◆ Upstream: <title>
+     Source: <repo> <tag or #PR>
+     URL: <url>
+
+     Evaluation:
+     ┌─────────────────────────────────────────────────┐
+     │ Area              │ Ours  │ Theirs │ Verdict     │
+     ├─────────────────────────────────────────────────┤
+     │ hook registration │ ✓     │ ✓      │ SKIP        │
+     │ error retry logic │ basic │ exp-bo │ CANDIDATE   │
+     │ config format     │ YAML  │ TOML   │ INCOMPATIBLE│
+     └─────────────────────────────────────────────────┘
+
+     Candidates for porting: 1 of 3 areas
+   ```
+5. If there are CANDIDATE items, ask: `Port candidate changes? [Y/n]`
+   - If yes → suggest `/nf:quick "port <area> from <repo> <tag>"` for each candidate
+
 **If user enters "solve":**
 - Collect all issues with `source_type: 'internal'`
-- Display: `Routing all internal issues to /qgsd:solve...`
-- Invoke `/qgsd:solve` to address all internal consistency issues at once
+- Display: `Routing all internal issues to /nf:solve...`
+- Invoke `/nf:solve` to address all internal consistency issues at once
 
 **If user enters "ack N":**
 - Acknowledge the debt entry for issue #N (transition status from "open" to "acknowledged" via the debt state machine).
@@ -254,7 +287,7 @@ Enter issue # to work on, "ack N" to acknowledge, "solve" for all internal issue
 
 **If user presses Enter (blank):**
 ```
-Observe complete. Run /qgsd:observe again when ready.
+Observe complete. Run /nf:observe again when ready.
 ```
 
 </process>

package/commands/{qgsd → nf}/pause-work.md

@@ -1,5 +1,5 @@
 ---
-name: qgsd:pause-work
+name: nf:pause-work
 description: Create context handoff when pausing work mid-phase
 allowed-tools:
   - Read
@@ -19,7 +19,7 @@ Routes to the pause-work workflow which handles:
 </objective>
 
 <execution_context>
-@~/.claude/qgsd/workflows/pause-work.md
+@~/.claude/nf/workflows/pause-work.md
 </execution_context>
 
 <context>
@@ -27,7 +27,7 @@ State and phase progress are gathered in-workflow with targeted reads.
 </context>
 
 <process>
-**Follow the pause-work workflow** from `@~/.claude/qgsd/workflows/pause-work.md`.
+**Follow the pause-work workflow** from `@~/.claude/nf/workflows/pause-work.md`.
 
 The workflow handles all logic including:
 1. Phase directory detection

package/commands/{qgsd → nf}/plan-milestone-gaps.md

@@ -1,5 +1,5 @@
 ---
-name: qgsd:plan-milestone-gaps
+name: nf:plan-milestone-gaps
 description: Create phases to close all gaps identified by milestone audit
 allowed-tools:
   - Read
@@ -10,15 +10,15 @@ allowed-tools:
   - AskUserQuestion
 ---
 <objective>
-Create all phases necessary to close gaps identified by `/qgsd:audit-milestone`.
+Create all phases necessary to close gaps identified by `/nf:audit-milestone`.
 
 Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase.
 
-One command creates all fix phases — no manual `/qgsd:add-phase` per gap.
+One command creates all fix phases — no manual `/nf:add-phase` per gap.
 </objective>
 
 <execution_context>
-@~/.claude/qgsd/workflows/plan-milestone-gaps.md
+@~/.claude/nf/workflows/plan-milestone-gaps.md
 </execution_context>
 
 <context>
@@ -29,6 +29,6 @@ Original intent and current planning state are loaded on demand inside the workf
 </context>
 
 <process>
-Execute the plan-milestone-gaps workflow from @~/.claude/qgsd/workflows/plan-milestone-gaps.md end-to-end.
+Execute the plan-milestone-gaps workflow from @~/.claude/nf/workflows/plan-milestone-gaps.md end-to-end.
 Preserve all workflow gates (audit loading, prioritization, phase grouping, user confirmation, roadmap updates).
 </process>

package/commands/{qgsd → nf}/plan-phase.md

@@ -1,8 +1,8 @@
 ---
-name: qgsd:plan-phase
+name: nf:plan-phase
 description: Create detailed phase plan (PLAN.md) with verification loop
 argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify]"
-agent: qgsd-planner
+agent: nf-planner
 allowed-tools:
   - Read
   - Write
@@ -18,12 +18,12 @@ Create executable phase prompts (PLAN.md files) for a roadmap phase with integra
 
 **Default flow:** Research (if needed) → Plan → Verify → Done
 
-**Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn qgsd-planner, verify with qgsd-plan-checker, iterate until pass or max iterations, present results.
+**Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn nf-planner, verify with nf-plan-checker, iterate until pass or max iterations, present results.
 </objective>
 
 <execution_context>
-@~/.claude/qgsd/workflows/plan-phase.md
-@~/.claude/qgsd/references/ui-brand.md
+@~/.claude/nf/workflows/plan-phase.md
+@~/.claude/nf/references/ui-brand.md
 </execution_context>
 
 <context>
@@ -39,6 +39,6 @@ Normalize phase input in step 2 before any directory lookups.
 </context>
 
 <process>
-Execute the plan-phase workflow from @~/.claude/qgsd/workflows/plan-phase.md end-to-end.
+Execute the plan-phase workflow from @~/.claude/nf/workflows/plan-phase.md end-to-end.
 Preserve all workflow gates (validation, research, planning, verification loop, routing).
 </process>

package/commands/{qgsd → nf}/polyrepo.md

@@ -1,6 +1,6 @@
 ---
-name: qgsd:polyrepo
-description: Manage polyrepo groups — register repos that form one product for cross-repo QGSD awareness
+name: nf:polyrepo
+description: Manage polyrepo groups — register repos that form one product for cross-repo nForma awareness
 argument-hint: create | add <group> <path> [role] | remove <group> <path> | list [group] | info
 allowed-tools:
   - Read

package/commands/{qgsd → nf}/progress.md

@@ -1,5 +1,5 @@
 ---
-name: qgsd:progress
+name: nf:progress
 description: Check project progress, show context, and route to next action (execute or plan)
 allowed-tools:
   - Read
@@ -15,10 +15,10 @@ Provides situational awareness before continuing work.
 </objective>
 
 <execution_context>
-@~/.claude/qgsd/workflows/progress.md
+@~/.claude/nf/workflows/progress.md
 </execution_context>
 
 <process>
-Execute the progress workflow from @~/.claude/qgsd/workflows/progress.md end-to-end.
+Execute the progress workflow from @~/.claude/nf/workflows/progress.md end-to-end.
 Preserve all routing logic (Routes A through F) and edge case handling.
 </process>

package/commands/{qgsd → nf}/queue.md

@@ -1,7 +1,7 @@
 ---
-name: qgsd:queue
+name: nf:queue
 description: Queue a skill or command to auto-invoke after the next /clear
-argument-hint: <command to queue, e.g. "/qgsd:quick --full">
+argument-hint: <command to queue, e.g. "/nf:quick --full">
 allowed-tools:
   - Bash
   - Write

package/commands/{qgsd → nf}/quick.md

@@ -1,5 +1,5 @@
 ---
-name: qgsd:quick
+name: nf:quick
 description: Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents
 argument-hint: "[--full]"
 allowed-tools:
@@ -16,7 +16,7 @@ allowed-tools:
 Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking).
 
 Quick mode is the same system with a shorter path:
-- Spawns qgsd-planner (quick mode) + qgsd-executor(s)
+- Spawns nf-planner (quick mode) + nf-executor(s)
 - Quick tasks live in `.planning/quick/` separate from planned phases
 - Updates STATE.md "Quick Tasks Completed" table (NOT ROADMAP.md)
 
@@ -34,7 +34,7 @@ Use when you want quality guarantees with formal correctness properties, without
 </objective>
 
 <execution_context>
-@~/.claude/qgsd/workflows/quick.md
+@~/.claude/nf/workflows/quick.md
 </execution_context>
 
 <context>
@@ -44,7 +44,7 @@ Context files are resolved inside the workflow (`init quick`) and delegated via
 </context>
 
 <process>
-Execute the quick workflow from @~/.claude/qgsd/workflows/quick.md end-to-end.
+Execute the quick workflow from @~/.claude/nf/workflows/quick.md end-to-end.
 Preserve all workflow gates (validation, task description, planning, execution, state updates, commits).
 </process>
 
@@ -60,7 +60,7 @@ When Step 6.5 reaches `gaps_found` status, do NOT pause for user input and do NO
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- QGSD ► GAPS FOUND — AUTO-FIX
+ nForma ► GAPS FOUND — AUTO-FIX
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ◆ Verification found gaps. Spawning fix executor...
@@ -88,7 +88,7 @@ Fix gaps identified in verification.
 - Return the fix commit hash in your response (format: 'Fix Commit: {hash}')
 </constraints>
 ",
-  subagent_type="qgsd-executor",
+  subagent_type="nf-executor",
   model="{executor_model}",
   description="Fix gaps: ${DESCRIPTION}"
 )
@@ -96,7 +96,7 @@ Fix gaps identified in verification.
 
 **4. After fix executor returns, run quorum-test to verify gaps are closed:**
 
-Determine test scope from VERIFICATION.md artifacts. If test files exist (`*.test.js`, `*.test.ts`, etc.), call `/qgsd:quorum-test` with those files. If no test files are present (non-testable gaps), skip quorum-test and proceed directly to step 5 treating the result as PASS.
+Determine test scope from VERIFICATION.md artifacts. If test files exist (`*.test.js`, `*.test.ts`, etc.), call `/nf:quorum-test` with those files. If no test files are present (non-testable gaps), skip quorum-test and proceed directly to step 5 treating the result as PASS.
 
 Evaluate quorum-test consensus:
 
@@ -120,7 +120,7 @@ Set `$VERIFICATION_STATUS` based on human response ("verified" → "Verified", "
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- QGSD ► AUTO-FIX EXHAUSTED
+ nForma ► AUTO-FIX EXHAUSTED
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Max fix iterations reached. Quorum still reports gaps.

package/commands/{qgsd → nf}/quorum-test.md

@@ -1,5 +1,5 @@
 ---
-name: qgsd:quorum-test
+name: nf:quorum-test
 description: Run the test suite and submit the full execution bundle to quorum workers for independent quality review. Parallel workers evaluate whether tests genuinely pass and whether assertions are meaningful.
 argument-hint: "[path/to/test.file.js]"
 allowed-tools:
@@ -13,7 +13,7 @@ allowed-tools:
 <objective>
 Run the project test suite, assemble a full execution bundle, and dispatch parallel quorum workers to independently evaluate whether the tests genuinely pass and whether they are real tests.
 
-This command extends QGSD quorum from *planning* (consensus on direction) to *verification* (consensus on test quality).
+This command extends nForma quorum from *planning* (consensus on direction) to *verification* (consensus on test quality).
 </objective>
 
 <process>
@@ -70,7 +70,7 @@ If `$TEST_FILES` is empty, display:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- QGSD ► QUORUM-TEST: No automated tests found
+ nForma ► QUORUM-TEST: No automated tests found
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Searched for: <$TEST_PATTERNS>
@@ -93,7 +93,7 @@ If any file is missing, display:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- QGSD ► QUORUM-TEST: BLOCK (missing test files)
+ nForma ► QUORUM-TEST: BLOCK (missing test files)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Missing: <list of missing files>
@@ -128,7 +128,7 @@ Append `echo "EXIT:$?"` to capture exit code. Store full output as `$TEST_OUTPUT
 Read the full source of every file in `$TEST_FILES`. Store as `$TEST_SOURCES` — a combined block with filename headers:
 
 ```
-=== hooks/qgsd-stop.test.js ===
+=== hooks/nf-stop.test.js ===
 <full source>
 
 === hooks/config-loader.test.js ===
@@ -147,7 +147,7 @@ If exit code is non-zero, stop immediately and display:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- QGSD ► QUORUM-TEST: BLOCK (test infrastructure failure)
+ nForma ► QUORUM-TEST: BLOCK (test infrastructure failure)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Tests did not run cleanly (exit code: N).
@@ -179,7 +179,7 @@ $TEST_SOURCES
 Display:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- QGSD ► QUORUM-TEST: Dispatching workers...
+ nForma ► QUORUM-TEST: Dispatching workers...
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -187,7 +187,7 @@ Dispatch all four workers as parallel Task calls (Task subagents are isolated su
 
 Worker prompt template for each:
 ```
-You are a skeptical test reviewer for the QGSD project.
+You are a skeptical test reviewer for the nForma project.
 
 <bundle>
 $BUNDLE
@@ -215,7 +215,7 @@ Dispatch (each call in a single parallel message — Task subagents are isolated
 - `Task(subagent_type="general-purpose", prompt="Call mcp__copilot-1__ask with the following prompt. Pass the full literal text of the bundle inline — do not summarize or truncate: [full worker prompt with $BUNDLE inlined verbatim]")`
 - `Task(subagent_type="general-purpose", prompt="Call mcp__codex-cli-1__review with the following prompt. Pass the full literal text of the bundle inline — do not summarize or truncate: [full worker prompt with $BUNDLE inlined verbatim]")`
 
-Note: `agents/qgsd-quorum-test-worker.md` defines this same role and output format and can be invoked directly with a bundle as `$ARGUMENTS`. The parallel Task dispatch above is used when targeting specific external models (Gemini, OpenCode, Copilot, Codex) rather than a single agent.
+Note: `agents/nf-quorum-test-worker.md` defines this same role and output format and can be invoked directly with a bundle as `$ARGUMENTS`. The parallel Task dispatch above is used when targeting specific external models (Gemini, OpenCode, Copilot, Codex) rather than a single agent.
 
 **Collect verdicts and render table**
 
@@ -235,7 +235,7 @@ Display:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- QGSD ► QUORUM-TEST RESULTS
+ nForma ► QUORUM-TEST RESULTS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ┌──────────────┬──────────────────┬─────────────────────────────────────┐