godpowers 0.15.0

package/lib/state-lock.js

@@ -0,0 +1,201 @@
+/**
+ * State Lock - cooperative advisory locking for state.json mutations.
+ *
+ * Contract (from ARCHITECTURE.md "Concurrency contract"):
+ *   - Reads are lock-free.
+ *   - Writes acquire a lock before mutating, release on completion.
+ *   - Lock has a `scope` (e.g. `tier-1.arch`, `linkage`, `all`).
+ *     Concurrent writers with non-overlapping scopes may run.
+ *   - Stale locks (past `expires`) are reclaimable by any actor;
+ *     reclaim emits state.repair with previous holder recorded.
+ *
+ * The lock lives in state.json under the `lock` key. Acquiring writes
+ * { holder, acquired, expires, scope }. Releasing sets lock to null.
+ *
+ * Scope conflict rules:
+ *   - 'all' conflicts with everything.
+ *   - 'tier-N.substep' conflicts with another 'tier-N.substep' on same
+ *     substep AND with 'all'. Does NOT conflict with 'tier-M.substep'
+ *     where M != N.
+ *   - 'linkage' conflicts with 'linkage' and 'all'.
+ *   - Any custom scope: exact-match conflict only (plus 'all').
+ *
+ * Public API:
+ *   acquire(projectRoot, opts) -> { acquired: true, lock } | { acquired: false, reason, holder }
+ *   release(projectRoot, holder) -> { released: bool }
+ *   peek(projectRoot) -> lock | null
+ *   isStale(lock, nowMs?) -> bool
+ *   reclaim(projectRoot, holder) -> { reclaimed: bool, previousHolder? }
+ *   scopesConflict(a, b) -> bool
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const state = require('./state');
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+function nowIso(offsetMs) {
+  const d = offsetMs ? new Date(Date.now() + offsetMs) : new Date();
+  return d.toISOString();
+}
+
+function peek(projectRoot) {
+  const s = state.read(projectRoot);
+  return s ? (s.lock || null) : null;
+}
+
+/**
+ * Return true if the lock is past its `expires` time (or null/malformed).
+ */
+function isStale(lock, nowMs) {
+  if (!lock || !lock.expires) return true;
+  const t = (nowMs != null ? nowMs : Date.now());
+  const exp = Date.parse(lock.expires);
+  return Number.isFinite(exp) ? t > exp : true;
+}
+
+/**
+ * Determine whether two scopes conflict.
+ */
+function scopesConflict(a, b) {
+  if (!a || !b) return false;
+  if (a === 'all' || b === 'all') return true;
+  return a === b;
+}
+
+/**
+ * Try to acquire a lock.
+ *
+ * opts: { holder (required), scope (default 'all'), ttlMs (default 5min), force }
+ *
+ * Returns { acquired: true, lock } on success.
+ * Returns { acquired: false, reason, holder, scope } on conflict.
+ *
+ * Reentrant: same holder can re-acquire. If the existing lock is stale,
+ * it is silently reclaimed.
+ */
+function acquire(projectRoot, opts = {}) {
+  if (!opts.holder) throw new Error('holder is required');
+  const scope = opts.scope || 'all';
+  const ttlMs = opts.ttlMs || DEFAULT_TTL_MS;
+
+  const s = state.read(projectRoot);
+  if (!s) throw new Error('state.json not initialized');
+
+  const existing = s.lock || null;
+
+  if (existing && !isStale(existing) && !opts.force) {
+    // Reentrant: same holder + compatible scope -> refresh expiration
+    if (existing.holder === opts.holder &&
+        (existing.scope === scope || existing.scope === 'all' || scope === 'all')) {
+      existing.expires = nowIso(ttlMs);
+      s.lock = existing;
+      state.write(projectRoot, s);
+      return { acquired: true, lock: existing, reentrant: true };
+    }
+    if (scopesConflict(existing.scope || 'all', scope)) {
+      return {
+        acquired: false,
+        reason: 'held',
+        holder: existing.holder,
+        scope: existing.scope,
+        expires: existing.expires
+      };
+    }
+    // Compatible scopes: layered lock. We support a simple single-lock
+    // slot for now, so reject and tell the caller. Multi-lock support
+    // can be added when there's a real second writer.
+    return {
+      acquired: false,
+      reason: 'scope-coexistence-not-supported',
+      holder: existing.holder,
+      scope: existing.scope
+    };
+  }
+
+  // existing is null OR stale OR force -> take it
+  const lock = {
+    holder: opts.holder,
+    acquired: nowIso(),
+    expires: nowIso(ttlMs),
+    scope
+  };
+  const reclaimedFrom = existing && isStale(existing) ? existing.holder : null;
+  s.lock = lock;
+  state.write(projectRoot, s);
+  return {
+    acquired: true,
+    lock,
+    reclaimed: reclaimedFrom != null,
+    reclaimedFrom
+  };
+}
+
+/**
+ * Release a held lock. Only the current holder can release.
+ *
+ * Returns { released: true } on success, { released: false, reason } otherwise.
+ */
+function release(projectRoot, holder) {
+  if (!holder) throw new Error('holder is required');
+  const s = state.read(projectRoot);
+  if (!s) return { released: false, reason: 'no-state' };
+  const lock = s.lock;
+  if (!lock) return { released: false, reason: 'no-lock' };
+  if (lock.holder !== holder) {
+    return { released: false, reason: 'wrong-holder', heldBy: lock.holder };
+  }
+  s.lock = null;
+  state.write(projectRoot, s);
+  return { released: true, releasedAt: nowIso() };
+}
+
+/**
+ * Force-reclaim a stale lock. Used by /god-repair.
+ * Returns { reclaimed, previousHolder? }.
+ */
+function reclaim(projectRoot, holder) {
+  const s = state.read(projectRoot);
+  if (!s) return { reclaimed: false, reason: 'no-state' };
+  const lock = s.lock;
+  if (!lock) return { reclaimed: false, reason: 'no-lock' };
+  if (!isStale(lock)) {
+    return { reclaimed: false, reason: 'lock-not-stale', expires: lock.expires };
+  }
+  const prev = lock.holder;
+  s.lock = null;
+  state.write(projectRoot, s);
+  return { reclaimed: true, previousHolder: prev };
+}
+
+/**
+ * Convenience wrapper: run an async function under a lock.
+ * Acquires, runs, releases.
+ */
+async function withLock(projectRoot, opts, fn) {
+  const r = acquire(projectRoot, opts);
+  if (!r.acquired) {
+    const err = new Error(`lock unavailable: held by ${r.holder} (scope=${r.scope})`);
+    err.code = 'LOCK_UNAVAILABLE';
+    err.detail = r;
+    throw err;
+  }
+  try {
+    return await fn(r.lock);
+  } finally {
+    release(projectRoot, opts.holder);
+  }
+}
+
+module.exports = {
+  acquire,
+  release,
+  peek,
+  isStale,
+  reclaim,
+  withLock,
+  scopesConflict,
+  DEFAULT_TTL_MS
+};

package/lib/state.js

@@ -0,0 +1,142 @@
+/**
+ * State Manager
+ *
+ * Read/write .godpowers/state.json with schema validation.
+ * Source of truth for tier statuses and artifact hashes.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const STATE_VERSION = '1.0.0';
+
+function statePath(projectRoot) {
+  return path.join(projectRoot, '.godpowers', 'state.json');
+}
+
+/**
+ * Read state.json from a project. Returns null if not initialized.
+ */
+function read(projectRoot) {
+  const file = statePath(projectRoot);
+  if (!fs.existsSync(file)) return null;
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+/**
+ * Write state.json to a project. Validates basic structure.
+ */
+function write(projectRoot, state) {
+  if (!state || typeof state !== 'object') {
+    throw new Error('state must be an object');
+  }
+  if (!state.version) state.version = STATE_VERSION;
+  if (!state.$schema) state.$schema = 'https://godpowers.dev/schema/state.v1.json';
+  if (!state.project || !state.project.name) {
+    throw new Error('state.project.name is required');
+  }
+  if (!state.tiers) state.tiers = {};
+
+  const file = statePath(projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(state, null, 2) + '\n');
+  return state;
+}
+
+/**
+ * Initialize a new state.json for a project.
+ */
+function init(projectRoot, projectName, opts = {}) {
+  const state = {
+    $schema: 'https://godpowers.dev/schema/state.v1.json',
+    version: STATE_VERSION,
+    project: {
+      name: projectName,
+      started: new Date().toISOString()
+    },
+    'active-workstream': 'main',
+    tiers: {
+      'tier-0': { orchestration: { status: 'in-flight', updated: new Date().toISOString() } },
+      'tier-1': {
+        prd: { status: 'pending' },
+        arch: { status: 'pending' },
+        roadmap: { status: 'pending' },
+        stack: { status: 'pending' },
+        design: { status: 'pending' },   // conditional: not-required for backend-only
+        product: { status: 'pending' }   // populated only when impeccable installed
+      },
+      'tier-2': {
+        repo: { status: 'pending' },
+        build: { status: 'pending' }
+      },
+      'tier-3': {
+        deploy: { status: 'pending' },
+        observe: { status: 'pending' },
+        launch: { status: 'pending' },
+        harden: { status: 'pending' }
+      }
+    },
+    'lifecycle-phase': 'in-arc',
+    linkage: {
+      'coverage-pct': 0,
+      'orphan-count': 0,
+      'drift-count': 0,
+      'review-required-items': 0
+    },
+    'yolo-decisions': [],
+    ...opts
+  };
+  return write(projectRoot, state);
+}
+
+/**
+ * Update a single sub-step's status.
+ */
+function updateSubStep(projectRoot, tierKey, subStepKey, updates) {
+  const state = read(projectRoot);
+  if (!state) throw new Error('state.json not found');
+  if (!state.tiers[tierKey]) throw new Error(`Tier not found: ${tierKey}`);
+  state.tiers[tierKey][subStepKey] = {
+    ...(state.tiers[tierKey][subStepKey] || {}),
+    ...updates,
+    updated: new Date().toISOString()
+  };
+  write(projectRoot, state);
+  return state.tiers[tierKey][subStepKey];
+}
+
+/**
+ * Hash a file. Used for artifact-hash tracking.
+ */
+function hashFile(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath);
+  const hash = crypto.createHash('sha256').update(content).digest('hex');
+  return `sha256:${hash}`;
+}
+
+/**
+ * Detect drift: for each sub-step with an artifact, rehash and compare.
+ * Returns a list of drift entries.
+ */
+function detectDrift(projectRoot) {
+  const state = read(projectRoot);
+  if (!state) return [];
+  const drift = [];
+  for (const [tierKey, tier] of Object.entries(state.tiers)) {
+    for (const [subStepKey, subStep] of Object.entries(tier)) {
+      if (!subStep.artifact || !subStep['artifact-hash']) continue;
+      const fullPath = path.join(projectRoot, '.godpowers', subStep.artifact);
+      const currentHash = hashFile(fullPath);
+      if (currentHash === null) {
+        drift.push({ tierKey, subStepKey, kind: 'missing', recorded: subStep['artifact-hash'] });
+      } else if (currentHash !== subStep['artifact-hash']) {
+        drift.push({ tierKey, subStepKey, kind: 'modified', recorded: subStep['artifact-hash'], current: currentHash });
+      }
+    }
+  }
+  return drift;
+}
+
+module.exports = { read, write, init, updateSubStep, hashFile, detectDrift, statePath };

package/lib/story-validator.js

@@ -0,0 +1,301 @@
+/**
+ * Story Validator
+ *
+ * Parses and validates STORY.md files (story-file workflow).
+ * Backward-compatible: doesn't replace /god-feature; complements it
+ * with finer-grained slices.
+ *
+ * STORY.md schema:
+ *   ---
+ *   id: STORY-{slug}-NNN
+ *   title: "Short noun phrase"
+ *   status: pending | in-progress | blocked | done
+ *   owner: name
+ *   deps: [STORY-other-001]
+ *   created: ISO date
+ *   ---
+ *
+ *   ## User Story
+ *   As a [persona], I want [capability] so that [outcome].
+ *
+ *   ## Acceptance Criteria
+ *   - [DECISION] User can do X. Acceptance: clicks Y, sees Z.
+ *
+ *   ## Slice Plan
+ *   1. Step 1
+ *   2. Step 2
+ *
+ *   ## Notes
+ *
+ * Public API:
+ *   parseStory(filePath) -> { id, title, status, owner, deps, body, sections, errors }
+ *   validateStory(story) -> findings
+ *   findStoryFiles(projectRoot) -> [paths]
+ *   listStories(projectRoot) -> [{ id, status, ... }]
+ *   listByStatus(projectRoot, status) -> [...]
+ *   isValidId(id) -> bool
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const VALID_STATUSES = ['pending', 'in-progress', 'blocked', 'done'];
+const ID_PATTERN = /^STORY-[\w-]+-\d+$/;
+const USER_STORY_PATTERN = /as\s+a[n]?\s+.+,\s+i\s+want\s+.+\s+so\s+that\s+/i;
+
+function isValidId(id) {
+  return ID_PATTERN.test(id);
+}
+
+function storiesDir(projectRoot) {
+  return path.join(projectRoot, '.godpowers', 'stories');
+}
+
+/**
+ * Find all STORY-*.md files under .godpowers/stories/.
+ */
+function findStoryFiles(projectRoot) {
+  const dir = storiesDir(projectRoot);
+  const found = [];
+  if (!fs.existsSync(dir)) return found;
+
+  function walk(d) {
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); }
+    catch (e) { return; }
+    for (const e of entries) {
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.isFile() && /^STORY-/.test(e.name) && e.name.endsWith('.md')) {
+        found.push(full);
+      }
+    }
+  }
+  walk(dir);
+  return found;
+}
+
+/**
+ * Parse a STORY.md. Returns object with frontmatter, parsed sections, errors.
+ */
+function parseStory(filePath) {
+  const errors = [];
+  if (!fs.existsSync(filePath)) {
+    return { errors: ['file-not-found'] };
+  }
+  const raw = fs.readFileSync(filePath, 'utf8');
+  if (!raw.startsWith('---')) {
+    return { errors: ['missing-frontmatter'], raw };
+  }
+  const fmEnd = raw.indexOf('\n---', 3);
+  if (fmEnd === -1) {
+    return { errors: ['unclosed-frontmatter'], raw };
+  }
+  const fmText = raw.slice(3, fmEnd).trim();
+  const body = raw.slice(fmEnd + 4).trim();
+
+  const fm = {};
+  for (const line of fmText.split('\n')) {
+    const m = line.match(/^([\w-]+):\s*(.*)$/);
+    if (m) {
+      let value = m[2].trim();
+      // Parse arrays: [a, b] or ["a", "b"]
+      if (value.startsWith('[') && value.endsWith(']')) {
+        value = value.slice(1, -1).split(',').map(s => {
+          let t = s.trim();
+          // Strip surrounding quotes if present
+          if ((t.startsWith('"') && t.endsWith('"')) ||
+              (t.startsWith("'") && t.endsWith("'"))) {
+            t = t.slice(1, -1);
+          }
+          return t;
+        }).filter(Boolean);
+      } else if (value.startsWith('"') && value.endsWith('"')) {
+        value = value.slice(1, -1);
+      }
+      fm[m[1]] = value;
+    }
+  }
+
+  // Parse sections
+  const sections = {};
+  let currentHeading = null;
+  let currentLines = [];
+  for (const line of body.split('\n')) {
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      if (currentHeading) {
+        sections[currentHeading] = currentLines.join('\n').trim();
+      }
+      currentHeading = m[1].trim();
+      currentLines = [];
+    } else if (currentHeading) {
+      currentLines.push(line);
+    }
+  }
+  if (currentHeading) {
+    sections[currentHeading] = currentLines.join('\n').trim();
+  }
+
+  return {
+    path: filePath,
+    id: fm.id,
+    title: fm.title,
+    status: fm.status,
+    owner: fm.owner,
+    deps: Array.isArray(fm.deps) ? fm.deps : (fm.deps ? [fm.deps] : []),
+    created: fm.created,
+    frontmatter: fm,
+    body,
+    sections,
+    errors
+  };
+}
+
+/**
+ * Validate a parsed story. Returns findings.
+ */
+function validateStory(story) {
+  const findings = [];
+
+  if (story.errors && story.errors.length > 0) {
+    for (const e of story.errors) {
+      findings.push({ severity: 'error', kind: e, message: e });
+    }
+    return findings;
+  }
+
+  if (!story.id) {
+    findings.push({ severity: 'error', kind: 'missing-id', message: 'STORY missing `id` in frontmatter' });
+  } else if (!isValidId(story.id)) {
+    findings.push({
+      severity: 'error',
+      kind: 'invalid-id-format',
+      message: `STORY id "${story.id}" does not match STORY-{slug}-NNN pattern`
+    });
+  }
+  if (!story.title) {
+    findings.push({ severity: 'error', kind: 'missing-title', message: 'STORY missing `title`' });
+  }
+  if (!story.status) {
+    findings.push({ severity: 'error', kind: 'missing-status', message: 'STORY missing `status`' });
+  } else if (!VALID_STATUSES.includes(story.status)) {
+    findings.push({
+      severity: 'error',
+      kind: 'invalid-status',
+      message: `Status "${story.status}" not one of ${VALID_STATUSES.join(', ')}`
+    });
+  }
+  if (!story.owner) {
+    findings.push({ severity: 'warning', kind: 'missing-owner', message: 'STORY missing `owner` field' });
+  }
+
+  // User Story section format
+  if (!story.sections || !story.sections['User Story']) {
+    findings.push({
+      severity: 'warning',
+      kind: 'missing-user-story',
+      message: 'STORY missing `## User Story` section'
+    });
+  } else {
+    const us = story.sections['User Story'];
+    if (!USER_STORY_PATTERN.test(us)) {
+      findings.push({
+        severity: 'warning',
+        kind: 'user-story-format',
+        message: 'User Story does not match "As a X, I want Y so that Z" format'
+      });
+    }
+  }
+
+  // Acceptance Criteria
+  if (!story.sections || !story.sections['Acceptance Criteria']) {
+    findings.push({
+      severity: 'warning',
+      kind: 'missing-acceptance',
+      message: 'STORY missing `## Acceptance Criteria` section'
+    });
+  }
+
+  return findings;
+}
+
+/**
+ * List all stories with summary fields.
+ */
+function listStories(projectRoot) {
+  const files = findStoryFiles(projectRoot);
+  return files.map(f => {
+    const story = parseStory(f);
+    return {
+      id: story.id,
+      title: story.title,
+      status: story.status,
+      owner: story.owner,
+      deps: story.deps || [],
+      path: f
+    };
+  });
+}
+
+function listByStatus(projectRoot, status) {
+  return listStories(projectRoot).filter(s => s.status === status);
+}
+
+/**
+ * Detect dep cycles.
+ */
+function detectDepCycles(projectRoot) {
+  const stories = listStories(projectRoot);
+  const byId = {};
+  for (const s of stories) byId[s.id] = s;
+  const visited = new Set();
+  const stack = new Set();
+  const cycles = [];
+  function dfs(id, path) {
+    if (stack.has(id)) {
+      cycles.push([...path, id]);
+      return;
+    }
+    if (visited.has(id)) return;
+    visited.add(id);
+    stack.add(id);
+    const s = byId[id];
+    if (s && s.deps) {
+      for (const dep of s.deps) {
+        if (byId[dep]) dfs(dep, [...path, id]);
+      }
+    }
+    stack.delete(id);
+  }
+  for (const s of stories) dfs(s.id, []);
+  return cycles;
+}
+
+/**
+ * Update story status (writes back to file).
+ */
+function setStatus(filePath, newStatus) {
+  if (!VALID_STATUSES.includes(newStatus)) {
+    throw new Error(`invalid status: ${newStatus}`);
+  }
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const updated = raw.replace(/^status:\s*\w+/m, `status: ${newStatus}`);
+  fs.writeFileSync(filePath, updated);
+  return { path: filePath, newStatus };
+}
+
+module.exports = {
+  parseStory,
+  validateStory,
+  findStoryFiles,
+  listStories,
+  listByStatus,
+  detectDepCycles,
+  setStatus,
+  isValidId,
+  storiesDir,
+  VALID_STATUSES,
+  ID_PATTERN,
+  USER_STORY_PATTERN
+};