godpowers 2.4.2 → 2.5.0

package/references/orchestration/README.md

@@ -5,6 +5,12 @@ god-orchestrator and related agents.
 
 ## Files
 
+- [GOD-MODE-RUNBOOK.md](GOD-MODE-RUNBOOK.md): `/god-mode` transcript,
+  flags, final sync, and completion contracts.
+- [GOD-NEXT-RUNBOOK.md](GOD-NEXT-RUNBOOK.md): `/god-next` invocation modes,
+  route detail, and edge cases.
+- [GOD-ORCHESTRATOR-RUNBOOK.md](GOD-ORCHESTRATOR-RUNBOOK.md): detailed
+  god-orchestrator operating contracts delegated out of the agent prompt.
 - [MODE-DETECTION.md](MODE-DETECTION.md): Mode A/B/C/E detection, plus Mode D
   suite membership.
 - [SCALE-DETECTION.md](SCALE-DETECTION.md): scale rubric and calibration.

package/references/shared/DASHBOARD-CONTRACT.md

@@ -0,0 +1,93 @@
+# Godpowers Dashboard Contract
+
+This reference owns the shared dashboard shape for `/god-status`, `/god-next`, `/god-mode` closeouts, and completed command closeouts.
+
+## Runtime source
+
+Prefer `lib/dashboard.js` for dashboard computation. Call `dashboard.compute(projectRoot)`, then render with `dashboard.render(result)` unless the caller needs a narrower brief view.
+
+If the runtime module is unavailable, use a manual disk scan and say `Dashboard engine: unavailable, manual scan used`.
+
+Never mix workflow progress with audit, hygiene, remediation, or launch-readiness scores. Label those scores separately when they appear.
+
+## Required shape
+
+```text
+Godpowers Dashboard
+
+Source: runtime dashboard (lib/dashboard.js)
+
+Current status:
+  State: <complete | partial | blocked | proposal | complete with deferred item>
+  Phase: <plain-language phase> (tier <human ordinal> of <human total>)
+  Step: <sub-step label> (step <n> of <total steps>)
+  Progress: <pct>% workflow progress (<done> of <total> tracked steps complete)
+  Worktree: <clean | modified files unstaged | staged changes | mixed>
+  Index: <untouched | staged files listed>
+
+Action brief:
+  Next: <recommended command or user decision>
+  Why: <route reason tied to disk state>
+  Readiness: <ready | needs attention>
+  Attention: <top blockers or none>
+  Host guarantees: <full | degraded | unknown with host and first gap>
+
+Planning visibility:
+  PRD: <done | pending | missing | deferred> <artifact path when present>
+  Roadmap: <done | pending | missing | deferred> <artifact path when present>
+  Current milestone: <roadmap milestone, tier, or next planning gate when known>
+  Completion basis: <state.json, PROGRESS.md, artifacts, or audit score source>
+
+Deliverable progress:
+  Requirements: <done>/<total> done (<pct>%), <in-progress> in progress, <untouched> not started
+  Increments: <done> done, <building> building, <pending> pending
+  Ledger: .godpowers/REQUIREMENTS.md
+
+What changed:
+  1. <highest-signal user-visible change>
+  2. <highest-signal user-visible change>
+
+Validation:
+  + <command>: <result>
+
+Proactive checks:
+  Checkpoint: <fresh | refreshed | missing | stale | conflicts with state.json>
+  Reviews: <none | N pending, suggest /god-review-changes>
+  Sync: <fresh | missing | stale | local helper ran | suggest /god-sync>
+  Docs: <fresh | N stale, suggest /god-docs | repo-doc-sync ran>
+  Repo surface: <fresh | N stale, suggest /god-doctor | repo-surface-sync ran>
+  Host: <full | degraded | unknown with host and first gap>
+  Runtime: <not-applicable | known URL, suggest /god-test-runtime | no known URL, defer deployed verification>
+  Automation: <not configured | N active | available via provider, suggest /god-automation-setup>
+  Security: <clear | sensitive files changed, suggest /god-harden>
+  Dependencies: <clear | dependency files changed, suggest /god-update-deps>
+  Hygiene: <fresh | stale, suggest /god-hygiene>
+
+Open items:
+  1. <deferred staging, unstaged files, pending review, blocker, or none>
+
+Next:
+  Recommended: <one concrete command or user decision>
+  Why: <one sentence tied to current state>
+```
+
+## Proposition closeout
+
+When a command only recommends work, end with this proposition block unless it already launched the selected command.
+
+```text
+Proposition:
+  1. Implement partial: <single suggested command>
+  2. Implement complete: <recipe sequence or /god-mode when safe>
+  3. Discuss more: /god-discuss <routing ambiguity or missing prerequisite>
+  4. Inspect status: /god-status, /god-locate, or /god-next
+Recommended: <one option and why>
+```
+
+## Proactive rules
+
+`/god-status` is read-only by default, so Level 3 agent work becomes a suggestion unless the user asked it to continue work.
+
+`/god-next` may run Level 2 local helpers only when there is a direct trigger. Standalone `/god-next` turns Level 3 work into the recommended command or a proposition option.
+
+Report checkpoint, review, sync, docs, repo surface, host, runtime, automation, security, dependency, and hygiene signals using the labels in the required shape.

package/references/shared/LOCKING.md

@@ -0,0 +1,15 @@
+# Shared Locking Contract
+
+This reference owns the state-lock contract used by mutating Godpowers commands.
+
+## Contract
+
+The orchestrator acquires a state lock before any skill mutates project state. The lock is scoped to the smallest affected unit, such as `tier-1.prd` for `/god-prd` or `linkage` for `/god-scan`.
+
+The default lock TTL is 5 minutes. The same holder may re-enter the lock. Stale locks are force-reclaimable through `/god-repair`.
+
+Read-only inspection commands do not block on the lock. Examples include `/god-status`, `/god-doctor`, and `/god-locate`.
+
+Concurrent writers on non-overlapping scopes are allowed. Concurrent writers on overlapping scopes must pause or route through `/god-next`.
+
+The full architecture contract lives in `ARCHITECTURE.md` under the concurrency contract section.

package/references/shared/README.md

@@ -8,6 +8,8 @@ Cross-tier reference content used by multiple agents.
 - [ORCHESTRATORS.md](ORCHESTRATORS.md): composition patterns with other AI
   coding workflow systems, including migration and managed sync-back.
 - [GLOSSARY.md](GLOSSARY.md): standardized vocabulary across tiers.
+- [DASHBOARD-CONTRACT.md](DASHBOARD-CONTRACT.md): shared dashboard and proposition output contract.
+- [LOCKING.md](LOCKING.md): shared state-lock contract for mutating commands.
 
 ## Planned content
 

package/routing/god-arch.yaml

@@ -34,6 +34,7 @@ standards:
   three-label-test: true
   have-nots: [A-01, A-02, A-03, A-04, A-05, A-06, A-07, A-08, A-09, A-10, A-11, A-12, A-13]
   gate-on-failure: pause-for-user
+  gate-command: npx godpowers gate --tier=arch --project=.
 
 success-path:
   next-recommended: /god-roadmap

package/routing/god-build.yaml

@@ -29,6 +29,7 @@ standards:
   three-label-test: true
   have-nots: [B-01, B-02, B-03, B-04, B-05, B-06, B-07, B-08, B-09, B-10, B-11, B-12]
   gate-on-failure: pause-for-user
+  gate-command: npx godpowers gate --tier=build --project=.
 
 success-path:
   next-recommended: /god-deploy

package/routing/god-design.yaml

@@ -50,6 +50,7 @@ standards:
     - "purple-blue gradients" # impeccable anti-pattern
     - "Inter everywhere"      # impeccable anti-pattern
     - "cards in cards"        # impeccable anti-pattern
+  gate-command: npx godpowers gate --tier=design --project=.
 
 success-path:
   next-recommended: /god-arch

package/routing/god-harden.yaml

@@ -33,6 +33,7 @@ standards:
   three-label-test: true
   have-nots: [H-01, H-02, H-03, H-04, H-05, H-06, H-07, H-08, H-09, H-10, H-11]
   gate-on-failure: pause-for-user
+  gate-command: npx godpowers gate --tier=harden --project=.
 
 success-path:
   next-recommended: /god-launch

package/routing/god-prd.yaml

@@ -35,6 +35,7 @@ standards:
   three-label-test: true
   have-nots: [P-01, P-02, P-03, P-04, P-05, P-06, P-07, P-08, P-09, P-10, P-11, P-12, P-13, P-14, P-15]
   gate-on-failure: pause-for-user
+  gate-command: npx godpowers gate --tier=prd --project=.
 
 success-path:
   next-recommended: /god-arch

package/routing/god-repo.yaml

@@ -24,6 +24,7 @@ standards:
   three-label-test: true
   have-nots: [RP-01, RP-02, RP-03, RP-04, RP-05, RP-06, RP-07, RP-08]
   gate-on-failure: pause-for-user
+  gate-command: npx godpowers gate --tier=repo --project=.
 
 success-path:
   next-recommended: /god-build

package/routing/god-roadmap-check.yaml

@@ -4,7 +4,7 @@ metadata:
   command: /god-roadmap-check
   description: Reconcile intent against ROADMAP.md before feature work
   tier: 1
-  family: maintain
+  family: compatibility
 
 prerequisites:
   required:

package/routing/god-roadmap.yaml

@@ -31,6 +31,7 @@ standards:
   three-label-test: true
   have-nots: [R-01, R-02, R-03, R-04, R-05, R-06, R-07, R-08, R-09, R-10]
   gate-on-failure: pause-for-user
+  gate-command: npx godpowers gate --tier=roadmap --project=.
 
 success-path:
   next-recommended: /god-stack

package/routing/god-stack.yaml

@@ -29,6 +29,7 @@ standards:
   three-label-test: true
   have-nots: [S-01, S-02, S-03, S-04, S-05]
   gate-on-failure: pause-for-user
+  gate-command: npx godpowers gate --tier=stack --project=.
 
 success-path:
   next-recommended: /god-repo

package/skills/god-arch.md

@@ -26,7 +26,8 @@ Spawn the **god-architect** agent in a fresh context via the host platform's nat
 After god-architect returns:
 1. Verify ARCH.md and ADRs exist on disk
 2. Spawn god-auditor to verify have-nots pass
-3. Update `.godpowers/PROGRESS.md`: Architecture status = done
+3. Run `npx godpowers gate --tier=arch --project=.` and do not proceed on a non-zero exit
+4. Update `.godpowers/PROGRESS.md`: Architecture status = done
 
 ## Pause Format
 
@@ -70,15 +71,4 @@ The reflog records every god-arch invocation as `op:god-arch` for `/god-undo`.
 
 ## Locking
 
-The orchestrator acquires a state-lock before this skill mutates anything,
-scoped to the smallest affected unit (e.g. `tier-1.prd` for `/god-prd`,
-`linkage` for `/god-scan`). Lock TTL is 5 minutes; reentrant for the
-same holder; force-reclaimable if stale via `/god-repair`.
-
-Read-only inspection commands (`/god-status`, `/god-doctor`,
-`/god-locate`) do NOT block on the lock. Concurrent writers on
-non-overlapping scopes are allowed; on overlapping scopes, the second
-writer pauses or routes elsewhere via `/god-next`.
-
-See [ARCHITECTURE.md "Concurrency contract"](../ARCHITECTURE.md) for
-the full contract.
+See `<runtimeRoot>/references/shared/LOCKING.md` for the shared state-lock contract.

package/skills/god-build.md

@@ -76,8 +76,10 @@ After all waves:
    decompose, prune, or escalate. Pass the exact failing diagnostics, rerun the
    command, and repeat until green or until the same root failure exhausts the
    repair budget.
-5. Update PROGRESS.md: Build status = done
-6. If the build plan or implementation establishes durable conventions, plan
+5. Record the exact verification commands that passed in `.godpowers/build/STATE.md`
+6. Run `npx godpowers gate --tier=build --project=.` and do not proceed on a non-zero exit
+7. Update PROGRESS.md: Build status = done
+8. If the build plan or implementation establishes durable conventions, plan
    pillar updates through `lib/pillars.planArtifactSync`. Under
    `/god-mode --yolo`, apply those updates immediately and log the decision.
 
@@ -106,15 +108,4 @@ after the current increment.
 
 ## Locking
 
-The orchestrator acquires a state-lock before this skill mutates anything,
-scoped to the smallest affected unit (e.g. `tier-1.prd` for `/god-prd`,
-`linkage` for `/god-scan`). Lock TTL is 5 minutes; reentrant for the
-same holder; force-reclaimable if stale via `/god-repair`.
-
-Read-only inspection commands (`/god-status`, `/god-doctor`,
-`/god-locate`) do NOT block on the lock. Concurrent writers on
-non-overlapping scopes are allowed; on overlapping scopes, the second
-writer pauses or routes elsewhere via `/god-next`.
-
-See [ARCHITECTURE.md "Concurrency contract"](../ARCHITECTURE.md) for
-the full contract.
+See `<runtimeRoot>/references/shared/LOCKING.md` for the shared state-lock contract.

package/skills/god-deploy.md

@@ -95,15 +95,4 @@ The reflog records every god-deploy invocation as `op:god-deploy` for `/god-undo
 
 ## Locking
 
-The orchestrator acquires a state-lock before this skill mutates anything,
-scoped to the smallest affected unit (e.g. `tier-1.prd` for `/god-prd`,
-`linkage` for `/god-scan`). Lock TTL is 5 minutes; reentrant for the
-same holder; force-reclaimable if stale via `/god-repair`.
-
-Read-only inspection commands (`/god-status`, `/god-doctor`,
-`/god-locate`) do NOT block on the lock. Concurrent writers on
-non-overlapping scopes are allowed; on overlapping scopes, the second
-writer pauses or routes elsewhere via `/god-next`.
-
-See [ARCHITECTURE.md "Concurrency contract"](../ARCHITECTURE.md) for
-the full contract.
+See `<runtimeRoot>/references/shared/LOCKING.md` for the shared state-lock contract.

package/skills/god-design.md

@@ -92,6 +92,14 @@ When DESIGN.md or PRODUCT.md change as a result of any subcommand:
 This pattern mirrors code review (god-spec-reviewer + god-quality-reviewer)
 applied to design.
 
+## Verification
+
+After god-designer and god-design-reviewer return:
+1. Verify `DESIGN.md` exists on disk
+2. Verify `.godpowers/design/STATE.md` exists on disk
+3. Run `npx godpowers gate --tier=design --project=.` and do not proceed on a non-zero exit
+4. Update `.godpowers/PROGRESS.md`: Design status = done when the project requires design
+
 ## Output
 
 Project root:
@@ -261,15 +269,4 @@ The reflog records every god-design invocation as `op:god-design` for `/god-undo
 
 ## Locking
 
-The orchestrator acquires a state-lock before this skill mutates anything,
-scoped to the smallest affected unit (e.g. `tier-1.prd` for `/god-prd`,
-`linkage` for `/god-scan`). Lock TTL is 5 minutes; reentrant for the
-same holder; force-reclaimable if stale via `/god-repair`.
-
-Read-only inspection commands (`/god-status`, `/god-doctor`,
-`/god-locate`) do NOT block on the lock. Concurrent writers on
-non-overlapping scopes are allowed; on overlapping scopes, the second
-writer pauses or routes elsewhere via `/god-next`.
-
-See [ARCHITECTURE.md "Concurrency contract"](../ARCHITECTURE.md) for
-the full contract.
+See `<runtimeRoot>/references/shared/LOCKING.md` for the shared state-lock contract.

package/skills/god-feature.md

@@ -109,15 +109,4 @@ in the linkage system:
 
 ## Locking
 
-The orchestrator acquires a state-lock before this skill mutates anything,
-scoped to the smallest affected unit (e.g. `tier-1.prd` for `/god-prd`,
-`linkage` for `/god-scan`). Lock TTL is 5 minutes; reentrant for the
-same holder; force-reclaimable if stale via `/god-repair`.
-
-Read-only inspection commands (`/god-status`, `/god-doctor`,
-`/god-locate`) do NOT block on the lock. Concurrent writers on
-non-overlapping scopes are allowed; on overlapping scopes, the second
-writer pauses or routes elsewhere via `/god-next`.
-
-See [ARCHITECTURE.md "Concurrency contract"](../ARCHITECTURE.md) for
-the full contract.
+See `<runtimeRoot>/references/shared/LOCKING.md` for the shared state-lock contract.

package/skills/god-harden.md

@@ -21,7 +21,8 @@ Spawn the **god-harden-auditor** agent in a fresh context via the host platform'
 
 After god-harden-auditor returns:
 1. Verify FINDINGS.md exists on disk
-2. Read findings classification:
+2. Run `npx godpowers gate --tier=harden --project=.` and do not proceed on a non-zero exit
+3. Read findings classification:
    - If any Critical: PROGRESS.md status = failed, launch is BLOCKED
    - If only High/Medium/Low: PROGRESS.md status = done
 
@@ -92,15 +93,4 @@ The reflog records every god-harden invocation as `op:god-harden` for `/god-undo
 
 ## Locking
 
-The orchestrator acquires a state-lock before this skill mutates anything,
-scoped to the smallest affected unit (e.g. `tier-1.prd` for `/god-prd`,
-`linkage` for `/god-scan`). Lock TTL is 5 minutes; reentrant for the
-same holder; force-reclaimable if stale via `/god-repair`.
-
-Read-only inspection commands (`/god-status`, `/god-doctor`,
-`/god-locate`) do NOT block on the lock. Concurrent writers on
-non-overlapping scopes are allowed; on overlapping scopes, the second
-writer pauses or routes elsewhere via `/god-next`.
-
-See [ARCHITECTURE.md "Concurrency contract"](../ARCHITECTURE.md) for
-the full contract.
+See `<runtimeRoot>/references/shared/LOCKING.md` for the shared state-lock contract.

package/skills/god-hotfix.md

@@ -125,15 +125,4 @@ in the linkage system:
 
 ## Locking
 
-The orchestrator acquires a state-lock before this skill mutates anything,
-scoped to the smallest affected unit (e.g. `tier-1.prd` for `/god-prd`,
-`linkage` for `/god-scan`). Lock TTL is 5 minutes; reentrant for the
-same holder; force-reclaimable if stale via `/god-repair`.
-
-Read-only inspection commands (`/god-status`, `/god-doctor`,
-`/god-locate`) do NOT block on the lock. Concurrent writers on
-non-overlapping scopes are allowed; on overlapping scopes, the second
-writer pauses or routes elsewhere via `/god-next`.
-
-See [ARCHITECTURE.md "Concurrency contract"](../ARCHITECTURE.md) for
-the full contract.
+See `<runtimeRoot>/references/shared/LOCKING.md` for the shared state-lock contract.

package/skills/god-launch.md

@@ -97,15 +97,4 @@ The reflog records every god-launch invocation as `op:god-launch` for `/god-undo
 
 ## Locking
 
-The orchestrator acquires a state-lock before this skill mutates anything,
-scoped to the smallest affected unit (e.g. `tier-1.prd` for `/god-prd`,
-`linkage` for `/god-scan`). Lock TTL is 5 minutes; reentrant for the
-same holder; force-reclaimable if stale via `/god-repair`.
-
-Read-only inspection commands (`/god-status`, `/god-doctor`,
-`/god-locate`) do NOT block on the lock. Concurrent writers on
-non-overlapping scopes are allowed; on overlapping scopes, the second
-writer pauses or routes elsewhere via `/god-next`.
-
-See [ARCHITECTURE.md "Concurrency contract"](../ARCHITECTURE.md) for
-the full contract.
+See `<runtimeRoot>/references/shared/LOCKING.md` for the shared state-lock contract.

package/skills/god-link.md

@@ -76,15 +76,4 @@ No source files are modified by this skill.
 
 ## Locking
 
-The orchestrator acquires a state-lock before this skill mutates anything,
-scoped to the smallest affected unit (e.g. `tier-1.prd` for `/god-prd`,
-`linkage` for `/god-scan`). Lock TTL is 5 minutes; reentrant for the
-same holder; force-reclaimable if stale via `/god-repair`.
-
-Read-only inspection commands (`/god-status`, `/god-doctor`,
-`/god-locate`) do NOT block on the lock. Concurrent writers on
-non-overlapping scopes are allowed; on overlapping scopes, the second
-writer pauses or routes elsewhere via `/god-next`.
-
-See [ARCHITECTURE.md "Concurrency contract"](../ARCHITECTURE.md) for
-the full contract.
+See `<runtimeRoot>/references/shared/LOCKING.md` for the shared state-lock contract.

package/skills/god-migrate.md

@@ -141,6 +141,4 @@ Suggested next:
 
 ## Locking
 
-Acquire the state lock with scope `migration.source-systems` before writing
-`.godpowers/prep/IMPORTED-CONTEXT.md`, seed artifacts, source-system companion
-files, or `state.json`.
+See `<runtimeRoot>/references/shared/LOCKING.md` for the shared state-lock contract.

package/skills/god-mode.md

@@ -121,6 +121,10 @@ workflow.
        `safe-sync-clear` fails, run
        `/god-reconcile Release Truth And Safe Sync` before deploy, observe,
        harden, launch, broad migration, or resume work.
+     - Instruction to run `npx godpowers gate --tier=<tier> --project=.`
+       after each tier skill returns and before starting the downstream tier
+       for PRD, design when required, architecture, roadmap, stack, repo,
+       build, and harden. A non-zero exit pauses the project run for repair.
      - Instruction that `--yolo` cannot bypass safe sync blockers or
        unresolved Critical harden findings. These are release-truth gates, not
        preference pauses.