@ai-is-gonna/get-tasks-done 0.2.0

package/hooks/gtd-validate-commit.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# gtd-hook-version: {{GTD_VERSION}}
+# gtd-validate-commit.sh — PreToolUse hook: enforce Conventional Commits format
+# Blocks git commit commands with non-conforming messages (exit 2).
+# Allows conforming messages and all non-commit commands (exit 0).
+# Uses Node.js for JSON parsing (always available in GTD projects, no jq dependency).
+#
+# OPT-IN: This hook is a no-op unless config.json has hooks.community: true.
+# Enable with: "hooks": { "community": true } in .planning/config.json
+
+# Check opt-in config — exit silently if not enabled
+if [ -f .planning/config.json ]; then
+  ENABLED=$(node -e "try{const c=require('./.planning/config.json');process.stdout.write(c.hooks?.community===true?'1':'0')}catch{process.stdout.write('0')}" 2>/dev/null)
+  if [ "$ENABLED" != "1" ]; then exit 0; fi
+else
+  exit 0
+fi
+
+INPUT=$(cat)
+
+# Extract command from JSON using Node (handles escaping correctly, no jq needed)
+CMD=$(echo "$INPUT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{process.stdout.write(JSON.parse(d).tool_input?.command||'')}catch{}})" 2>/dev/null)
+
+# Only check git commit commands.
+# Delegates to hooks/lib/git-cmd.js isGitSubcommand() — the canonical token-walk
+# classifier that handles env-prefix, -C path, and full-path git invocations.
+# A naive `^git\s+commit` regex misses all three; this guard fixes that (#3129).
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+if GIT_CMD_LIB="$HOOK_DIR/lib/git-cmd.js" node -e "
+  const {isGitSubcommand}=require(process.env.GIT_CMD_LIB);
+  process.exit(isGitSubcommand(process.argv[1],'commit')?0:1);
+" "$CMD" 2>/dev/null; then
+  # Extract message from -m flag
+  MSG=""
+  if [[ "$CMD" =~ -m[[:space:]]+\"([^\"]+)\" ]]; then
+    MSG="${BASH_REMATCH[1]}"
+  elif [[ "$CMD" =~ -m[[:space:]]+\'([^\']+)\' ]]; then
+    MSG="${BASH_REMATCH[1]}"
+  fi
+
+  if [ -n "$MSG" ]; then
+    SUBJECT=$(echo "$MSG" | head -1)
+    # Validate Conventional Commits format
+    if ! [[ "$SUBJECT" =~ ^(feat|fix|docs|style|refactor|perf|test|build|ci|chore)(\(.+\))?:[[:space:]].+ ]]; then
+      # Emit a typed `code` field alongside `reason` (#2974). Tests assert
+      # on the stable code string; the reason is the human-readable copy.
+      echo '{"decision": "block", "code": "CONVENTIONAL_COMMITS_VIOLATION", "reason": "Commit message must follow Conventional Commits: <type>(<scope>): <subject>. Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore. Subject must be <=72 chars, lowercase, imperative mood, no trailing period."}'
+      exit 2
+    fi
+    if [ ${#SUBJECT} -gt 72 ]; then
+      echo '{"decision": "block", "code": "COMMIT_SUBJECT_TOO_LONG", "reason": "Commit subject must be 72 characters or less."}'
+      exit 2
+    fi
+  fi
+fi
+
+exit 0

package/hooks/gtd-workflow-guard.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// gtd-hook-version: {{GTD_VERSION}}
+// GTD Workflow Guard — PreToolUse hook
+// Detects when Claude attempts file edits outside a GTD workflow context
+// (no active /gtd- skill or Task subagent) and injects an advisory warning.
+//
+// This is a SOFT guard — it advises, not blocks. The edit still proceeds.
+// The warning nudges Claude to use /gtd:quick or /gtd:fast instead of
+// making direct edits that bypass state tracking.
+//
+// Enable via config: hooks.workflow_guard: true (default: false)
+// Only triggers on Write/Edit tool calls to non-.planning/ files.
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name;
+
+    // Only guard Write and Edit tool calls
+    if (toolName !== 'Write' && toolName !== 'Edit') {
+      process.exit(0);
+    }
+
+    // Check if we're inside a GTD workflow (Task subagent or /gtd- skill)
+    // Subagents have a session_id that differs from the parent
+    // and typically have a description field set by the orchestrator
+    if (data.tool_input?.is_subagent || data.session_type === 'task') {
+      process.exit(0);
+    }
+
+    // Check the file being edited
+    const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+
+    // Allow edits to .planning/ files (GTD state management)
+    if (filePath.includes('.planning/') || filePath.includes('.planning\\')) {
+      process.exit(0);
+    }
+
+    // Allow edits to common config/docs files that don't need GTD tracking
+    const allowedPatterns = [
+      /\.gitignore$/,
+      /\.env/,
+      /CLAUDE\.md$/,
+      /AGENTS\.md$/,
+      /GEMINI\.md$/,
+      /settings\.json$/,
+    ];
+    if (allowedPatterns.some(p => p.test(filePath))) {
+      process.exit(0);
+    }
+
+    // Check if workflow guard is enabled
+    const cwd = data.cwd || process.cwd();
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (!config.hooks?.workflow_guard) {
+          process.exit(0); // Guard disabled (default)
+        }
+      } catch (e) {
+        process.exit(0);
+      }
+    } else {
+      process.exit(0); // No GTD project — don't guard
+    }
+
+    // If we get here: GTD project, guard enabled, file edit outside .planning/,
+    // not in a subagent context. Inject advisory warning.
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext: `⚠️ WORKFLOW ADVISORY: You're editing ${path.basename(filePath)} directly without a GTD command. ` +
+          'This edit will not be tracked in STATE.md or produce a SUMMARY.md. ' +
+          'Consider using /gtd:fast for trivial fixes or /gtd:quick for larger changes ' +
+          'to maintain project state tracking. ' +
+          'If this is intentional (e.g., user explicitly asked for a direct edit), proceed normally.'
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail — never block tool execution
+    process.exit(0);
+  }
+});

package/hooks/lib/git-cmd.js

@@ -0,0 +1,150 @@
+'use strict';
+
+/**
+ * git-cmd.js — token-walk git command classifier.
+ *
+ * Determines whether a shell command string invokes a specific git
+ * subcommand. Handles the four forms that a naive `^git\s+commit` regex
+ * misses:
+ *
+ *   bare:         git commit -m "..."                 ✓
+ *   -C path:      git -C /some/path commit -m "..."   ✓ (missed by regex)
+ *   env-prefix:   GIT_AUTHOR_NAME=x git commit "..."  ✓ (missed by regex)
+ *   full-path:    /usr/bin/git commit -m "..."         ✓ (missed by regex)
+ *
+ * This module is the single source of truth for git-commit detection so all
+ * hooks that need to gate on git commits share one implementation.
+ *
+ * Exported by the hooks/lib/ directory — require via a path relative to the
+ * hook's own __dirname:
+ *
+ *   const { isGitSubcommand } = require(path.join(__dirname, 'lib', 'git-cmd.js'));
+ */
+
+const path = require('path');
+
+/**
+ * Git global options that take a following argument.
+ * These must be consumed as (option, argument) pairs when walking tokens.
+ */
+const ARGUMENT_TAKING_FLAGS = new Set([
+  '-C',                // working directory
+  '--git-dir',         // path to git repository
+  '--work-tree',       // path to working tree
+  '--namespace',       // git namespace
+  '--super-prefix',    // superproject-relative prefix
+  '--exec-path',       // path to core git programs (when given an arg)
+  '--html-path',
+  '--man-path',
+  '--info-path',
+  '--list-cmds',
+]);
+
+/**
+ * Git global flags that consume no extra argument.
+ */
+const BOOLEAN_FLAGS = new Set([
+  '-p', '--paginate', '--no-pager',
+  '--no-replace-objects', '--bare',
+  '--literal-pathspecs', '--glob-pathspecs', '--noglob-pathspecs',
+  '--icase-pathspecs', '--no-optional-locks',
+  '-P', '--no-lazy-fetch',
+  '--version', '--help',
+]);
+
+/**
+ * Tokenize a shell command string.
+ * Handles single-quoted strings, double-quoted strings, and unquoted tokens.
+ * Does NOT perform variable expansion or brace expansion.
+ *
+ * @param {string} cmd
+ * @returns {string[]}
+ */
+function tokenize(cmd) {
+  const tokens = [];
+  let i = 0;
+  const len = cmd.length;
+
+  while (i < len) {
+    // Skip whitespace
+    while (i < len && /\s/.test(cmd[i])) i++;
+    if (i >= len) break;
+
+    let token = '';
+    while (i < len && !/\s/.test(cmd[i])) {
+      if (cmd[i] === "'") {
+        // Single-quoted string: take everything until closing '
+        i++;
+        while (i < len && cmd[i] !== "'") token += cmd[i++];
+        if (i < len) i++; // consume closing '
+      } else if (cmd[i] === '"') {
+        // Double-quoted string: take everything until closing " (no escape handling)
+        i++;
+        while (i < len && cmd[i] !== '"') token += cmd[i++];
+        if (i < len) i++; // consume closing "
+      } else {
+        token += cmd[i++];
+      }
+    }
+    if (token) tokens.push(token);
+  }
+
+  return tokens;
+}
+
+/**
+ * Return true if `cmd` invokes the git subcommand `sub`.
+ *
+ * @param {string} cmd  - Full shell command string (may include env vars, full paths)
+ * @param {string} sub  - Subcommand to test for, e.g. 'commit'
+ * @returns {boolean}
+ */
+function isGitSubcommand(cmd, sub) {
+  if (!cmd || !sub) return false;
+
+  const tokens = tokenize(cmd);
+  let i = 0;
+
+  // Phase 1: skip leading VAR=VALUE environment assignments
+  while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) {
+    i++;
+  }
+
+  // Phase 2: the next token must be the git executable
+  if (i >= tokens.length) return false;
+  const gitToken = tokens[i++];
+  if (path.basename(gitToken) !== 'git') return false;
+
+  // Phase 3: consume git global options
+  while (i < tokens.length) {
+    const t = tokens[i];
+
+    // --flag=value form for argument-taking flags
+    const eqIdx = t.indexOf('=');
+    const flagName = eqIdx !== -1 ? t.slice(0, eqIdx) : t;
+    if (ARGUMENT_TAKING_FLAGS.has(flagName)) {
+      if (eqIdx !== -1) {
+        // consumed as one token: --git-dir=.git
+        i++;
+      } else {
+        // consumed as two tokens: -C /path
+        i += 2;
+      }
+      continue;
+    }
+
+    if (BOOLEAN_FLAGS.has(t)) {
+      i++;
+      continue;
+    }
+
+    // Not a global option — this is the subcommand
+    break;
+  }
+
+  // Phase 4: check the subcommand
+  if (i >= tokens.length) return false;
+  return tokens[i] === sub;
+}
+
+module.exports = { isGitSubcommand, tokenize };

package/hooks/lib/gtd-graphify-rebuild.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# gtd-graphify-rebuild.sh — detached rebuild runner for hooks/gtd-graphify-update.sh.
+#
+# Usage:
+#   gtd-graphify-rebuild.sh <STATUS_FILE> <LOCK_FILE> <HEAD_SHA> <MS_START> <GRAPHIFY_BIN>
+#
+# Writes its own PID into LOCK_FILE on start, removes LOCK_FILE on exit (any cause),
+# runs `graphify update .` from the project root (cwd inherited from caller), copies
+# the produced graphify-out/* into .planning/graphs/, and rewrites STATUS_FILE to
+# reflect the final status ("ok" if graphify exited 0, "failed" otherwise).
+#
+# Designed to be invoked via `setsid ... &` so it is reparented away from the hook
+# caller and never blocks the user-facing tool call.
+
+set -uo pipefail
+
+STATUS_FILE="${1:?STATUS_FILE required}"
+LOCK_FILE="${2:?LOCK_FILE required}"
+HEAD_SHA="${3:?HEAD_SHA required}"
+MS_START="${4:?MS_START required}"
+GRAPHIFY_BIN="${5:?GRAPHIFY_BIN required}"
+
+# Atomic-ish lock acquire: write our PID and trap cleanup
+echo "$$" > "$LOCK_FILE"
+trap 'rm -f "$LOCK_FILE"' EXIT
+
+"$GRAPHIFY_BIN" update . >/dev/null 2>&1
+EXIT_CODE=$?
+
+# Copy outputs only on success — failure path preserves the prior valid graph.
+if [ "$EXIT_CODE" -eq 0 ] && [ -f graphify-out/graph.json ]; then
+  cp graphify-out/graph.json .planning/graphs/graph.json
+  cp graphify-out/graph.html .planning/graphs/graph.html 2>/dev/null || true
+  cp graphify-out/GRAPH_REPORT.md .planning/graphs/GRAPH_REPORT.md 2>/dev/null || true
+  cp .planning/graphs/graph.json .planning/graphs/.last-build-snapshot.json 2>/dev/null || true
+fi
+
+# Compute duration in ms
+MS_END=$(node -e 'process.stdout.write(String(Date.now()))' 2>/dev/null || echo "$MS_START")
+DURATION=$((MS_END - MS_START))
+
+STATUS_NAME="ok"
+[ "$EXIT_CODE" -eq 0 ] || STATUS_NAME="failed"
+
+TS_END=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")
+
+# Write the final status file. Use Node for safe JSON encoding.
+GTD_STATUS_TS="$TS_END" \
+GTD_STATUS_NAME="$STATUS_NAME" \
+GTD_EXIT_CODE="$EXIT_CODE" \
+GTD_DURATION="$DURATION" \
+GTD_HEAD_SHA="$HEAD_SHA" \
+GTD_STATUS_FILE="$STATUS_FILE" \
+node -e '
+  const fs = require("node:fs");
+  const status = {
+    ts: process.env.GTD_STATUS_TS,
+    status: process.env.GTD_STATUS_NAME,
+    exit_code: parseInt(process.env.GTD_EXIT_CODE, 10),
+    duration_ms: parseInt(process.env.GTD_DURATION, 10),
+    head_at_build: process.env.GTD_HEAD_SHA,
+    graphify_version: null,
+  };
+  fs.writeFileSync(process.env.GTD_STATUS_FILE, JSON.stringify(status, null, 2) + "\n");
+' 2>/dev/null || true

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@ai-is-gonna/get-tasks-done",
+  "version": "0.2.0",
+  "description": "Task-based execution control for AI-assisted development workflows.",
+  "bin": {
+    "get-tasks-done": "bin/install.js",
+    "gtd-sdk": "bin/gtd-sdk.js",
+    "gtd-tools": "bin/gtd-sdk.js"
+  },
+  "files": [
+    "bin",
+    "commands",
+    "get-tasks-done",
+    "agents",
+    "hooks",
+    "scripts",
+    "sdk/src",
+    "sdk/shared",
+    "sdk/prompts",
+    "sdk/dist",
+    "sdk/package.json",
+    "sdk/package-lock.json",
+    "sdk/tsconfig.json"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "meta-prompting",
+    "context-engineering",
+    "spec-driven-development",
+    "gemini",
+    "gemini-cli",
+    "codex",
+    "codex-cli"
+  ],
+  "author": "Davide Troiani",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ai-is-gonna/get-tasks-done.git"
+  },
+  "homepage": "https://github.com/ai-is-gonna/get-tasks-done",
+  "bugs": {
+    "url": "https://github.com/ai-is-gonna/get-tasks-done/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=10.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.84",
+    "ws": "^8.20.0"
+  },
+  "devDependencies": {
+    "c8": "^11.0.0"
+  },
+  "optionalDependencies": {
+    "fallow": "^2.70.0"
+  },
+  "overrides": {
+    "fast-uri": "3.1.2"
+  },
+  "scripts": {
+    "build:hooks": "node scripts/build-hooks.js",
+    "build:sdk": "cd sdk && npm ci && npm run build",
+    "check:alias-drift": "cd sdk && npm run check:alias-drift",
+    "check:state-document-fresh": "cd sdk && npm run check:state-document-fresh",
+    "check:configuration-fresh": "cd sdk && npm run check:configuration-fresh",
+    "check:workstream-inventory-builder-fresh": "cd sdk && npm run check:workstream-inventory-builder-fresh",
+    "check:project-root-fresh": "cd sdk && npm run check:project-root-fresh",
+    "prepublishOnly": "npm run build:hooks && npm run build:sdk",
+    "pretest": "npm run build:sdk && npm run lint:skill-deps",
+    "pretest:coverage": "npm run build:sdk",
+    "lint:descriptions": "node scripts/lint-descriptions.cjs",
+    "lint:skill-deps": "node scripts/lint-skill-deps.cjs",
+    "lint:tests": "node scripts/lint-no-source-grep.cjs",
+    "lint:pr-checks": "node scripts/lint-pr-check-project-dir.cjs",
+    "test": "node scripts/run-tests.cjs",
+    "test:coverage": "c8 --check-coverage --lines 70 --reporter text --include 'get-tasks-done/bin/lib/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs"
+  }
+}

package/scripts/audit-workflow-script-paths.cjs

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * Post-install path audit for workflow-invoked scripts (#2995).
+ *
+ * Walks workflowsDir, extracts every `${GTD_HOME[...]}/<path>.<cjs|js|sh>`
+ * token, and asserts:
+ *   1. the file exists in the repo at that <path> (catches typos)
+ *   2. <path>'s first segment is in installedPrefixes (catches the
+ *      #2994 class: source-vs-deployed-path mismatches)
+ *
+ * Pure function over (workflowsDir, repoRoot, installedPrefixes); no
+ * filesystem mutation. Tests assert on the typed AUDIT_FINDING enum.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const AUDIT_FINDING = Object.freeze({
+  MISSING_FROM_REPO: 'missing_from_repo',
+  NOT_INSTALLED: 'not_installed',
+});
+
+// Match `${GTD_HOME}` or `${GTD_HOME:-...}` followed by a /-rooted path
+// ending in .cjs/.js/.sh. The path is captured verbatim (relative to
+// the install root).
+const REF_RE = /\$\{GTD_HOME(?::-[^}]*)?\}\/([A-Za-z0-9_./-]+\.(?:cjs|js|sh))/g;
+
+function listWorkflowFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => path.join(dir, e.name));
+}
+
+function extractReferences(content) {
+  const out = [];
+  let m;
+  // RegExp objects with /g state must be reset per call.
+  const re = new RegExp(REF_RE.source, 'g');
+  while ((m = re.exec(content)) !== null) {
+    out.push(m[1]);
+  }
+  return out;
+}
+
+function auditWorkflowScriptPaths({ workflowsDir, repoRoot, installedPrefixes }) {
+  const findings = [];
+  const installedSet = new Set(installedPrefixes);
+  for (const file of listWorkflowFiles(workflowsDir)) {
+    const content = fs.readFileSync(file, 'utf8');
+    const workflow = path.basename(file);
+    for (const ref of extractReferences(content)) {
+      const firstSegment = ref.split('/')[0];
+      // #2996 CR: emit BOTH findings simultaneously when a reference is
+      // both outside an installed prefix AND missing from the repo. The
+      // earlier `continue` short-circuited MISSING_FROM_REPO, so a
+      // developer who moved a missing reference to an installed prefix
+      // would only discover the second issue on a subsequent CI run.
+      if (!installedSet.has(firstSegment)) {
+        findings.push({ workflow, path: ref, kind: AUDIT_FINDING.NOT_INSTALLED });
+      }
+      const sourceFile = path.join(repoRoot, ref);
+      if (!fs.existsSync(sourceFile)) {
+        findings.push({ workflow, path: ref, kind: AUDIT_FINDING.MISSING_FROM_REPO });
+      }
+    }
+  }
+  return { ok: findings.length === 0, findings };
+}
+
+module.exports = { auditWorkflowScriptPaths, AUDIT_FINDING, extractReferences };