godpowers 1.6.10 → 1.6.12

package/agents/god-orchestrator.md

@@ -190,6 +190,11 @@ pillar sync work with `lib/pillars.planArtifactSync(projectRoot, artifacts,
 apply the pillar updates immediately and log the action to
 `.godpowers/YOLO-DECISIONS.md`.
 
+Whenever Pillars sync is auto-invoked, show an auto-invoked status card. Say
+whether this was an agent spawn or a local runtime call. For Pillars sync the
+agent is usually `none, local runtime only` unless the current workflow
+explicitly spawned `god-context-writer`.
+
 Before or alongside that import, write `.godpowers/prep/INITIAL-FINDINGS.md`
 using `templates/INITIAL-FINDINGS.md`. This artifact records what Godpowers
 observed directly during init:
@@ -277,6 +282,44 @@ This is the third layer of decision support:
 2. **Recipes** (`<runtimeRoot>/routing/recipes/<recipe>.yaml`): scenario-based sequences
 3. **Standards** (god-standards-check): quality gates between stages
 
+## Proactive Auto-Invoke Matrix
+
+Before every user-visible closeout, and after every successful state mutation,
+evaluate the master auto-invoke policy against disk state. The goal is to keep
+Godpowers moving intelligently without hiding work from the user.
+
+| Level | Default behavior | Orchestrator action |
+|---|---|---|
+| 1 | Auto-suggest | Compute `/god-next`, review queues, hygiene age, and status summary |
+| 2 | Auto-run local helper | Run checkpoint, linkage, Pillars planning, context dry-run, or progress refresh |
+| 3 | Auto-spawn bounded agent | Spawn only when trigger is direct and the workflow scope owns that surface |
+| 4 | Require approval | Pause or list the exact user decision needed |
+
+Use this trigger map:
+
+| Trigger | Auto action | Visibility |
+|---|---|---|
+| `state.json` or `PROGRESS.md` changed | refresh `.godpowers/CHECKPOINT.md` | `Auto-invoked:` local runtime only |
+| code or artifact files changed | run lightweight reverse-sync or spawn `god-updater` for workflow closeout | `Sync status:` |
+| durable artifact truth changed | run Pillars sync plan | `Auto-invoked:` local runtime only |
+| AI tool instruction files changed | spawn or dry-run `god-context-writer` | `Auto-invoked:` |
+| `REVIEW-REQUIRED.md` gains entries | suggest `/god-review-changes` | closeout proposition |
+| `DESIGN.md` or `PRODUCT.md` changed | spawn `god-design-reviewer` | gate card before propagation |
+| docs and code both changed | spawn `god-docs-writer` in drift-check mode when current workflow owns docs, otherwise suggest `/god-docs` | `Auto-invoked:` or proposition |
+| frontend-visible files changed and a known URL exists | spawn `god-browser-tester` inside build, design, launch, harden, or explicit runtime workflows | runtime status card |
+| frontend-visible files changed and no known URL exists | suggest `/god-test-runtime` with local URL setup, defer deployed URL | proposition |
+| security-sensitive files changed | auto-spawn only inside harden, hotfix, launch, or project run; otherwise suggest `/god-harden` | proposition |
+| dependency files changed | auto-spawn only inside update-deps, hygiene, or approved project run; otherwise suggest `/god-update-deps` | proposition |
+| full project run complete or hygiene stale | suggest `/god-hygiene` | proposition |
+
+Never use this matrix to auto-run Level 4 actions: deployed staging against a
+guessed URL, production launch, provider dashboard access, broad dependency
+upgrades, destructive repair, review clearing, Critical security acceptance, or
+git stage, commit, push, package, release, or publish.
+
+Every auto action must emit either `Auto-invoked:`, `Sync status:`, or a
+proposition explaining why it did not run.
+
 ## Detection-Driven Tier 1 Routing
 
 After PRD and before ARCH, branch on UI or product-experience presence:
@@ -496,8 +539,8 @@ requested or final sign-off begins.
 5. Spawn the appropriate specialist agent in a fresh context
 6. Verify their output exists on disk
 7. Run have-nots check on the artifact
-8. If pass: update PROGRESS.md, sync CHECKPOINT.md, print the "Step result"
-   card, then move to next sub-step
+8. If pass: update PROGRESS.md, sync CHECKPOINT.md, run the proactive
+   auto-invoke sweep, print the "Step result" card, then move to next sub-step
 9. If fail and repairable: print the failed result card, then enter the
    autonomous repair loop
 10. If fail and human-only: pause with the smallest needed question
@@ -522,7 +565,8 @@ For single-agent sub-steps:
 | Harden | god-harden-auditor | code | .godpowers/harden/FINDINGS.md |
 
 For all single-agent sub-steps:
-1. Spawn the agent in a fresh context (Task tool)
+1. Spawn the agent in a fresh context using the host platform's native agent
+   spawning mechanism
 2. Pass `--yolo` flag if active so the agent auto-picks defaults
 3. Wait for the agent to return
 4. Verify artifact exists on disk
@@ -602,6 +646,21 @@ Before declaring the project run complete, ALWAYS run /god-sync:
 3. Update SYNC-LOG.md with the project-run completion entry
 4. Update state.json with all final tier statuses
 
+Display the sync status before the final completion block:
+
+```
+Sync status:
+  Trigger: /god-mode final sync
+  Agent: god-updater spawned
+  Local syncs:
+    + reverse-sync: <counts and result>
+    + pillars-sync: <counts and result>
+    + checkpoint-sync: <created, updated, no-op, or skipped>
+    + context-refresh: <spawned, no-op, or skipped>
+  Artifacts: <changed files or no-op>
+  Log: .godpowers/SYNC-LOG.md
+```
+
 This step runs regardless of flags:
 - /god-mode -> sync runs
 - /god-mode --yolo -> sync runs (no pause; auto-applies)
@@ -617,12 +676,16 @@ across all 14 categories.
 
 After Launch completes, write a transition message:
 
-```
+```text
 Godpowers project run complete.
 
+Godpowers Dashboard
+
 Current status:
   State: complete
-  Progress: <pct>% (<done> of <total> steps complete; current step <n> of <total>)
+  Phase: <plain-language phase> (tier <human ordinal> of <human total>)
+  Step: <sub-step label> (step <n> of <total steps>)
+  Progress: <pct>% (<done> of <total> steps complete)
   Worktree: <clean | modified files unstaged | staged changes | mixed>
   Index: <untouched | staged files listed>
 
@@ -639,6 +702,16 @@ What changed:
 Validation:
   + <command>: <result>
 
+Proactive checks:
+  Checkpoint: <fresh | refreshed | stale>
+  Reviews: <none | N pending, suggest /god-review-changes>
+  Sync: <fresh | suggested | local helper ran>
+  Docs: <fresh | suggested | drift-check spawned>
+  Runtime: <not-applicable | suggested | browser test spawned>
+  Security: <clear | suggested | harden spawned>
+  Dependencies: <clear | suggested | deps audit spawned>
+  Hygiene: <fresh | suggest /god-hygiene>
+
 Open items:
   1. <none, or deployed staging deferred, pending review, unstaged files, etc.>
 
@@ -668,6 +741,11 @@ Proposition:
   4. Run deployed staging: provide STAGING_APP_URL=<deployed staging origin> when needed
 ```
 
+Generate the dashboard with `lib/dashboard.compute(projectRoot)` and
+`lib/dashboard.render(result)` when the runtime bundle is available. If the
+runtime module cannot be loaded, fall back to a manual disk scan and say
+`Dashboard engine: unavailable, manual scan used`.
+
 Update PROGRESS.md status to `steady-state-active`.
 
 For focused brownfield, hotfix, refactor, or build workflows that finish without a
@@ -785,11 +863,14 @@ Show:
 - concise phase status
 - before each visible tier/sub-step, a short "what will happen" card
 - after each visible tier/sub-step, a short "what happened" card
+- every auto-invoked command, agent, and local runtime helper using an
+  `Auto-invoked:` or `Sync status:` card
 - durable state detected from disk
 - commands being run and whether they passed or failed
 - scoped file changes
 - final validation summary
-- final current status from disk, including progress, lifecycle, open items,
+- final Godpowers Dashboard from disk, including phase, tier, step, progress,
+  lifecycle, planning visibility, proactive checks, open items,
   worktree/index state, and recommended next action
 - plain-language workflow names. Say "project run" or "workflow" instead of
   unexplained "arc" in visible output
@@ -797,7 +878,7 @@ Show:
 - `Project run complete` or `PAUSE: external access required`
 
 Hide:
-- raw Task input
+- raw spawn input
 - "Hard instructions" sections
 - spawned-agent prompt text
 - system, developer, AGENTS.md, or internal policy recitations
@@ -809,6 +890,36 @@ user-facing question. Do not expose the rule itself. Example: ask for
 `STAGING_APP_URL=<deployed staging origin>` at final sign-off rather than
 showing the Shipping Closure Protocol.
 
+### Auto-Invoked Work Cards
+
+Every automatic step that mutates state, writes artifacts, validates gates, or
+spawns an agent must leave a visible trace in the transcript.
+
+Use this shape:
+
+```
+Auto-invoked:
+  Trigger: <event that caused the automatic step>
+  Agent: <agent name, or none, local runtime only>
+  Local syncs:
+    + <helper>: <result>
+  Artifacts: <changed files, no-op, or deferred>
+  Log: <path, or none>
+```
+
+Required auto-invoked cards:
+- `/god-preflight` started automatically for brownfield or bluefield work
+- standards checks between routed stages
+- design-reviewer checks after DESIGN.md or PRODUCT.md changes
+- `god-updater` spawned for reverse-sync or final sync
+- local `lib/reverse-sync.run` calls, including `/god-scan`
+- Pillars sync through `lib/pillars.pillarizeExisting` or
+  `lib/pillars.applyArtifactSync`
+- checkpoint refresh through `lib/checkpoint.syncFromState`
+- AI-tool context refresh through `god-context-writer`
+
+If an automatic step is skipped, still report it with the skipped reason.
+
 ## Step Narration Protocol
 
 Godpowers must make its work trackable without exposing hidden prompts or
@@ -817,11 +928,11 @@ one compact card.
 
 Before starting a tier/sub-step:
 
-```
+```text
 Next step
-Progress: <pct>% (<done> of <total> steps complete; current step <n> of <total>)
-Tier: <tier-number> <tier-label>
+Phase: <plain-language phase> (tier <human ordinal> of <human total>)
 Step: <sub-step-label>
+Progress: <pct>% (<done> of <total> steps complete; step <n> of <total>)
 Why this now: <one sentence tied to disk state or the prior gate>
 What will happen:
   1. <first observable action>
@@ -832,11 +943,11 @@ Expected output: <artifact path or verification result>
 
 After a tier/sub-step completes or pauses:
 
-```
+```text
 Step result
-Progress: <pct>% (<done> of <total> steps complete; current step <n> of <total>)
-Tier: <tier-number> <tier-label>
+Phase: <plain-language phase> (tier <human ordinal> of <human total>)
 Step: <sub-step-label>
+Progress: <pct>% (<done> of <total> steps complete; step <n> of <total>)
 Result: <done | blocked | failed | skipped | imported>
 What happened:
   1. <observable action completed>
@@ -850,7 +961,7 @@ Rules:
 - Use `lib/state.progressSummary(stateJson)` for the percentage and step count
   whenever state.json is available.
 - Use artifact paths and verification evidence from disk, not memory.
-- Do not print raw Task input, hidden instructions, or full file loadout lists.
+- Do not print raw spawn input, hidden instructions, or full file loadout lists.
 - If a step is blocked, do not show a generic "Suggested next"; show the
   smallest concrete unblock action.
 

package/agents/god-updater.md

@@ -111,6 +111,12 @@ After feature work, every artifact that was impacted needs to reflect reality.
   `drift-count`, `review-required-items`
 - Emit events: `linkage.snapshot`, `drift.detected` (per finding),
   `review-required.populated`
+- Report counts in the final sync status:
+  - scanned files
+  - links added, removed, or unchanged
+  - fenced footers updated
+  - drift findings
+  - REVIEW-REQUIRED.md items created
 
 ### Pillars sync (native context)
 - Call `lib/pillars.pillarizeExisting(projectRoot)` if Pillars is absent or
@@ -122,6 +128,8 @@ After feature work, every artifact that was impacted needs to reflect reality.
   immediately and log the decision to `.godpowers/YOLO-DECISIONS.md`.
 - Never read every file in `agents/` as project context. Only files with
   `pillar:` frontmatter are Pillars files.
+- Report whether Pillars work was initialized, applied, proposed, skipped, or
+  no-op.
 
 ### AI-tool context refresh (always, unless never-ask)
 - Read `state.json` for `project.context-prompt-answered`
@@ -134,16 +142,36 @@ After feature work, every artifact that was impacted needs to reflect reality.
 - Idempotent: if content matches, no write occurs
 - Never touches content outside the `<!-- godpowers:begin -->` /
   `<!-- godpowers:end -->` fence
+- Report whether context refresh spawned `god-context-writer`, changed files,
+  no-oped, or skipped because the project opted out.
+
+### Checkpoint sync
+- After state changes, refresh `.godpowers/CHECKPOINT.md` from disk state using
+  `lib/checkpoint.syncFromState(projectRoot, { nextCommand, nextReason })`
+  when the runtime is available.
+- If checkpoint sync is unavailable in the host tool, say it was skipped and
+  include the reason.
+- Report the checkpoint path and whether it was created, updated, unchanged,
+  or skipped.
 
 ## Output
 
-Write summary to `.godpowers/SYNC-LOG.md` (append-only):
+Write summary to `.godpowers/SYNC-LOG.md` (append-only). The summary must
+include both user-visible status and machine-checkable counts:
 
 ```markdown
 ## Sync: [intent] [timestamp]
 
 Triggered by: [recipe name]
 
+Sync status:
+- Trigger: [manual /god-sync | /god-mode final sync | recipe closeout]
+- Agent: god-updater
+- Reverse-sync: scanned [N] files, updated [N] footers, created [N] review items
+- Pillars sync: [applied/proposed/no-op/skipped], [N] pillar files
+- Checkpoint sync: [created/updated/no-op/skipped] .godpowers/CHECKPOINT.md
+- Context refresh: [spawned god-context-writer/no-op/skipped], [N] files
+
 Updated:
 - prd/PRD.md: added requirement P-MUST-12
 - arch/ARCH.md: added ADR-007 (auth refactor)
@@ -157,11 +185,32 @@ Updated:
 
 Have-nots re-validated: all passing.
 
-Suggested next: /god-status
+Next: /god-status
 ```
 
 Update PROGRESS.md with the latest tier statuses.
 
+Return a compact user-facing closeout in the same shape:
+
+```
+Sync complete.
+
+Sync status:
+  Trigger: <trigger>
+  Agent: god-updater
+  Local syncs:
+    + reverse-sync: <counts and result>
+    + pillars-sync: <counts and result>
+    + checkpoint-sync: <created, updated, no-op, or skipped>
+    + context-refresh: <spawned, no-op, or skipped>
+  Artifacts: <changed files or no-op>
+  Log: .godpowers/SYNC-LOG.md
+
+Next:
+  Recommended: /god-status
+  Why: confirm the disk-derived project state after sync.
+```
+
 ## Have-Nots
 
 Sync FAILS if:

package/bin/install.js

@@ -186,6 +186,9 @@ function installSkillFile(srcFile, skillsDest, runtimeKey, targetName = null) {
   const baseName = targetName || path.basename(srcFile, '.md');
   if (runtimeKey === 'codex') {
     const skillDir = path.join(skillsDest, baseName);
+    if (fs.existsSync(skillDir)) {
+      fs.rmSync(skillDir, { recursive: true, force: true });
+    }
     ensureDir(skillDir);
     fs.copyFileSync(srcFile, path.join(skillDir, 'SKILL.md'));
     return;
@@ -297,6 +300,9 @@ function removeSkillEntry(skillsDir, entry) {
 function parseArgs(argv) {
   const args = argv.slice(2);
   const opts = {
+    command: null,
+    project: process.cwd(),
+    json: false,
     runtimes: [],
     global: false,
     local: false,
@@ -305,8 +311,22 @@ function parseArgs(argv) {
     uninstall: false,
   };
 
-  for (const arg of args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
     switch (arg) {
+      case 'status':
+      case 'next':
+        opts.command = arg;
+        break;
+      case '--json':
+        opts.json = true;
+        break;
+      case '--project':
+        if (args[i + 1]) {
+          opts.project = path.resolve(args[i + 1]);
+          i++;
+        }
+        break;
       case '-g':
       case '--global':
         opts.global = true;
@@ -327,7 +347,9 @@ function parseArgs(argv) {
         opts.uninstall = true;
         break;
       default:
-        if (arg.startsWith('--') && RUNTIMES[arg.slice(2)]) {
+        if (arg.startsWith('--project=')) {
+          opts.project = path.resolve(arg.slice('--project='.length));
+        } else if (arg.startsWith('--') && RUNTIMES[arg.slice(2)]) {
           opts.runtimes.push(arg.slice(2));
         }
         break;
@@ -545,8 +567,14 @@ function uninstallForRuntime(runtimeKey, opts = {}) {
 
 function showHelp() {
   console.log(BANNER);
-  log('Usage: npx godpowers [options]\n');
+  log('Usage: npx godpowers [command] [options]\n');
+  log('Commands:');
+  log('  status               Show the Godpowers Dashboard for a project');
+  log('  next                 Show the dashboard and recommended next command');
+  log('');
   log('Options:');
+  log('  --project=<path>     Project root for status or next (default: cwd)');
+  log('  --json               Emit JSON for status or next');
   log('  -g, --global         Install globally (to config directory)');
   log('  -l, --local          Install locally (to current directory)');
   log('  --claude             Install for Claude Code');
@@ -569,11 +597,28 @@ function showHelp() {
   log('  -h, --help           Show this help message');
   log('');
   log('Examples:');
+  log('  npx godpowers status --project=.');
+  log('  npx godpowers next --project=.');
   log('  npx godpowers --claude --global');
   log('  npx godpowers --all');
   log('  npx godpowers --codex --cursor');
 }
 
+function runDashboardCommand(opts) {
+  const dashboard = require('../lib/dashboard');
+  const result = dashboard.compute(opts.project);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(dashboard.render(result));
+    if (opts.command === 'next') {
+      console.log('');
+      console.log('Suggested next command:');
+      console.log(`  ${result.next && result.next.command ? result.next.command : 'describe the next intent'}`);
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -586,6 +631,11 @@ function main() {
     process.exit(0);
   }
 
+  if (opts.command === 'status' || opts.command === 'next') {
+    runDashboardCommand(opts);
+    return;
+  }
+
   console.log(BANNER);
 
   const srcDir = path.resolve(__dirname, '..');