@ghl-ai/aw 0.1.84 → 0.1.85

package/c4/slimRouter.mjs

@@ -74,15 +74,22 @@ Naming a route is not invoking it. Read = call the Skill tool.
 
 | Intent signal in the prompt | Stage skill |
 |---|---|
-| review, "review this PR", findings, governance, "is this ready" | \`aw:review\` |
-| plan, design, refactor strategy, propose approach | \`aw:plan\` |
-| build, implement, write code, add feature, TDD | \`aw:build\` |
+| review, "review this PR", findings, governance, "is this ready", skeptical validation | \`aw:review\` |
+| plan, design, refactor strategy, propose approach, missing/stale docs | \`aw:plan\` |
+| build, implement, write code, add feature, TDD, approved docs | \`aw:build\` |
 | bug, crash, alert, regression, debug, investigate | \`aw:investigate\` |
-| test, QA, e2e, coverage, regression suite | \`aw:test\` |
+| test, QA, e2e, coverage, regression suite, compatibility proof | \`aw:test\` |
 | deploy, release, rollout, staging | \`aw:deploy\` |
 | ship, launch, rollback readiness, closeout | \`aw:ship\` |
 | feature end-to-end (research → ship) | \`aw:feature\` |
-| agent/skill/command/rule authoring | \`aw:adk\` |
+| agent/skill/command/rule authoring, trigger/routing quality, context/token budget | \`aw:adk\` |
+
+## Token budget and evidence packet
+
+Default to a bounded packet: prompt, loaded repo rules, existing AW docs/state,
+exact target files/tests, and git diff. Load domain references only after the
+stage skill names them. Stop gathering context once route, repo scope, next
+artifact/command, assumptions, blockers, and validation proof are clear.
 
 ## Tier-3 domain skills are delegated, not invoked directly
 
@@ -141,15 +148,22 @@ Naming a route is not invoking it. Read = open the SKILL.md file.
 
 | Intent signal in the prompt | Stage skill |
 |---|---|
-| review, "review this PR", findings, governance, "is this ready" | \`aw-review\` |
-| plan, design, refactor strategy, propose approach | \`aw-plan\` |
-| build, implement, write code, add feature, TDD | \`aw-build\` |
+| review, "review this PR", findings, governance, "is this ready", skeptical validation | \`aw-review\` |
+| plan, design, refactor strategy, propose approach, missing/stale docs | \`aw-plan\` |
+| build, implement, write code, add feature, TDD, approved docs | \`aw-build\` |
 | bug, crash, alert, regression, debug, investigate | \`aw-investigate\` |
-| test, QA, e2e, coverage, regression suite | \`aw-test\` |
+| test, QA, e2e, coverage, regression suite, compatibility proof | \`aw-test\` |
 | deploy, release, rollout, staging | \`aw-deploy\` |
 | ship, launch, rollback readiness, closeout | \`aw-ship\` |
 | feature end-to-end (research → ship) | \`aw-feature\` |
-| agent/skill/command/rule authoring | \`aw-adk\` |
+| agent/skill/command/rule authoring, trigger/routing quality, context/token budget | \`aw-adk\` |
+
+## Token budget and evidence packet
+
+Default to a bounded packet: prompt, loaded repo rules, existing AW docs/state,
+exact target files/tests, and git diff. Load domain references only after the
+stage skill names them. Stop gathering context once route, repo scope, next
+artifact/command, assumptions, blockers, and validation proof are clear.
 
 ## Tier-3 domain skills are delegated, not invoked directly
 

package/cli.mjs

@@ -33,6 +33,7 @@ const COMMANDS = {
   'slack-sim': () => import('./commands/slack-sim.mjs').then(m => m.slackSimCommand),
   c4:      () => import('./commands/c4.mjs').then(m => m.c4Command),
   'init-repo': () => import('./commands/init-repo.mjs').then(m => m.initRepoCommand),
+  'clickup-sync': () => import('./commands/clickup-sync.mjs').then(m => m.clickupSyncCommand),
 };
 
 const COMMAND_NAMES = Object.keys(COMMANDS);
@@ -182,6 +183,8 @@ function printHelp() {
     cmd('aw integrations add <key>', 'Install a specific tool (e.g. codex, caveman, context-mode)'),
     cmd('aw integrations remove <key>', 'Remove a tool'),
     cmd('aw integrations bundle <name>', 'Install a preset bundle'),
+    cmd('aw clickup-sync <items.json> --list <id>', 'Sync JSON items into a ClickUp list (create new, comment recurring; input-validated, fail-closed)'),
+    cmd('aw clickup-sync <items.json> --list <id> --dry-run', 'Preview the create/comment plan without any writes'),
     cmd('aw drop <path>', 'Stop syncing or delete local content'),
     cmd('aw nuke', 'Remove entire .aw_registry/ & start fresh'),
     cmd('aw daemon install', 'Auto-pull on a schedule (macOS launchd / Linux cron)'),

package/clickup-sync.mjs

@@ -0,0 +1,154 @@
+// clickup-sync.mjs — pure core for `aw clickup-sync`.
+// Schema validation + sentinel-based dedup + sync-plan computation.
+// No I/O: side effects live in commands/clickup-sync.mjs and integrations/clickup.mjs.
+// Contract: .aw_docs/features/aw-clickup-sync/spec.md §3.
+
+// Stable item key: leading alnum, then alnum plus . _ - : / (so structured
+// producer keys like `<repo>:<app>:<category>:<file>` are accepted), 1..256 chars.
+// Whitespace and angle brackets stay excluded so the key always round-trips
+// through the dedup sentinel `<!-- aw-sync-key: KEY -->` unambiguously. This is
+// also the drift guard — a key that could not round-trip is refused up front
+// (spec §3.1, §3.2).
+export const KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/;
+
+// Machine-parseable dedup marker embedded in each created task's description.
+export const SENTINEL_RE = /<!--\s*aw-sync-key:\s*(\S+)\s*-->/;
+
+// Legacy migration (F2): tasks created by the previous ClickUp path carry the
+// key as a trailing `key:<finding_key>` token in the task NAME (e.g.
+// "... · key:ghl-revex-backend:saas:APPSEC:apps/saas/src/x.ts"), not the
+// description sentinel. Dual-read this so those tasks are recognized (commented,
+// not duplicated) on the first run. The captured token is validated against
+// KEY_RE before use.
+export const LEGACY_NAME_KEY_RE = /key:(\S+)\s*$/;
+
+export const TITLE_MAX = 255;
+export const DESC_MAX = 8000;
+
+const ALLOWED_FIELDS = new Set(['key', 'title', 'description']);
+
+/**
+ * Validate untrusted, already-parsed JSON into a normalized item list.
+ * Fail-closed: throws a clear Error on any shape/field/format violation.
+ * An empty array is valid and returns []. No mutation of the input.
+ * @param {unknown} raw
+ * @returns {Array<{ key: string, title: string, description: string }>}
+ */
+export function parseAndValidateItems(raw) {
+  if (!Array.isArray(raw)) {
+    throw new Error('Invalid items file: top-level JSON must be an array of items.');
+  }
+
+  const seenKeys = new Set();
+  const items = raw.map((item, index) => {
+    if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+      throw new Error(`Invalid item ${index}: expected an object with key, title, description.`);
+    }
+
+    for (const field of Object.keys(item)) {
+      if (!ALLOWED_FIELDS.has(field)) {
+        throw new Error(`Invalid item ${index}: unknown field "${field}" (allowed: key, title, description).`);
+      }
+    }
+
+    const { key, title } = item;
+    if (typeof key !== 'string') {
+      throw new Error(`Invalid item ${index}: "key" is required and must be a string.`);
+    }
+    if (!KEY_RE.test(key)) {
+      throw new Error(`Invalid item ${index}: "key" "${key}" must match ${KEY_RE} (alphanumeric start; . _ - allowed; max 64).`);
+    }
+    if (seenKeys.has(key)) {
+      throw new Error(`Invalid items file: duplicate key "${key}" (keys must be unique to avoid duplicate tasks).`);
+    }
+    seenKeys.add(key);
+
+    if (typeof title !== 'string' || title.trim().length === 0) {
+      throw new Error(`Invalid item ${index}: "title" is required and must be a non-empty string.`);
+    }
+    if (title.length > TITLE_MAX) {
+      throw new Error(`Invalid item ${index}: "title" exceeds ${TITLE_MAX} characters.`);
+    }
+
+    const description = item.description === undefined ? '' : item.description;
+    if (typeof description !== 'string') {
+      throw new Error(`Invalid item ${index}: "description" must be a string when present.`);
+    }
+    if (description.length > DESC_MAX) {
+      throw new Error(`Invalid item ${index}: "description" exceeds ${DESC_MAX} characters.`);
+    }
+
+    return { key, title, description };
+  });
+
+  return items;
+}
+
+/**
+ * Append the dedup sentinel to a task description.
+ * @param {string} description
+ * @param {string} key
+ * @returns {string}
+ */
+export function embedSentinel(description, key) {
+  const base = description ? `${description}\n\n` : '';
+  return `${base}<!-- aw-sync-key: ${key} -->`;
+}
+
+/**
+ * Extract the embedded key from an existing ClickUp task, or null if absent.
+ * Reads `description` first, falling back to `text_content`.
+ * @param {{ description?: string, text_content?: string }} task
+ * @returns {string | null}
+ */
+export function extractKey(task) {
+  if (!task || typeof task !== 'object') return null;
+
+  // 1. New format: description sentinel (authoritative).
+  const source = typeof task.description === 'string' && task.description.length > 0
+    ? task.description
+    : (typeof task.text_content === 'string' ? task.text_content : '');
+  const match = source.match(SENTINEL_RE);
+  if (match) return match[1];
+
+  // 2. Legacy fallback: trailing `key:<finding_key>` token in the task name.
+  if (typeof task.name === 'string') {
+    const legacy = task.name.match(LEGACY_NAME_KEY_RE);
+    if (legacy && KEY_RE.test(legacy[1])) return legacy[1];
+  }
+
+  return null;
+}
+
+/**
+ * Split items into new (create) vs recurring (comment) against existing tasks.
+ * Pure — inputs are not mutated.
+ * @param {Array<{ key: string, title: string, description: string }>} items
+ * @param {Array<Record<string, unknown>>} existingTasks
+ * @returns {{ toCreate: typeof items, toComment: Array<{ item: (typeof items)[number], taskId: string }> }}
+ */
+export function computeSyncPlan(items, existingTasks) {
+  const keyToTaskId = new Map();
+  for (const task of existingTasks || []) {
+    const key = extractKey(task);
+    // Guard against a sentinel-bearing task with no id: skip it rather than map
+    // to the literal "undefined" (would later comment on a bogus task id). The
+    // item then falls through to create, which is the safe outcome.
+    if (key !== null && task.id != null && !keyToTaskId.has(key)) {
+      keyToTaskId.set(key, String(task.id));
+    }
+  }
+
+  const toCreate = [];
+  const toComment = [];
+  for (const item of items) {
+    const taskId = keyToTaskId.get(item.key);
+    if (taskId === undefined) {
+      toCreate.push(item);
+    } else {
+      toComment.push({ item, taskId });
+    }
+  }
+
+  return { toCreate, toComment };
+}

package/commands/clickup-sync.mjs

@@ -0,0 +1,120 @@
+// commands/clickup-sync.mjs — `aw clickup-sync <items.json> --list <listId> [--dry-run]`
+//
+// Syncs a JSON items file into a ClickUp list: create new tasks, comment on
+// recurring ones, deduped by an embedded description sentinel. Fail-closed on
+// bad input (validated before any ClickUp write); empty list is a clean no-op;
+// --dry-run performs zero writes. Contract: spec.md §5, §6.
+//
+// fs + client are injected via `deps` for testability; the CLI passes none, so
+// the real readFileSync + createClickUpClient defaults apply.
+
+import { readFileSync } from 'node:fs';
+import * as fmt from '../fmt.mjs';
+import { chalk } from '../fmt.mjs';
+import { createClickUpClient } from '../integrations/clickup.mjs';
+import { parseAndValidateItems, embedSentinel, computeSyncPlan } from '../clickup-sync.mjs';
+
+const RECURRING_COMMENT = 'Recurred via `aw clickup-sync` — item seen again in the source list.';
+
+export async function clickupSyncCommand(args, deps = {}) {
+  const readFile = deps.readFile ?? ((path) => readFileSync(path, 'utf8'));
+  const makeClient = deps.createClient ?? (() => createClickUpClient());
+
+  fmt.configureInteractionMode(args);
+  fmt.intro('aw clickup-sync');
+
+  // ── Args ──
+  const filePath = (args._positional || [])[0];
+  if (!filePath) {
+    fmt.cancel('Missing items file. Usage: aw clickup-sync <items.json> --list <listId> [--dry-run]');
+  }
+  const listId = args['--list'];
+  if (!listId || listId === true) {
+    fmt.cancel('Missing --list <listId>. Usage: aw clickup-sync <items.json> --list <listId> [--dry-run]');
+  }
+  const dryRun = args['--dry-run'] === true;
+
+  // ── Read → parse → validate (all before any network / write) ──
+  let rawText;
+  try {
+    rawText = readFile(filePath);
+  } catch (err) {
+    fmt.cancel(`Cannot read items file "${filePath}": ${errMessage(err)}`);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(rawText);
+  } catch (err) {
+    fmt.cancel(`Invalid JSON in "${filePath}": ${errMessage(err)}`);
+  }
+
+  let items;
+  try {
+    items = parseAndValidateItems(parsed);
+  } catch (err) {
+    fmt.cancel(errMessage(err));
+  }
+
+  if (items.length === 0) {
+    fmt.outro('Nothing to sync (empty items list).');
+    return { created: 0, commented: 0, dryRun };
+  }
+
+  // ── Fetch existing tasks + compute plan (fail-closed on read errors) ──
+  const client = makeClient();
+  let existingTasks;
+  try {
+    existingTasks = await client.listAllTasks(listId);
+  } catch (err) {
+    fmt.cancel(`Failed to read existing tasks from list ${listId}: ${errMessage(err)}`);
+  }
+
+  const { toCreate, toComment } = computeSyncPlan(items, existingTasks);
+
+  if (dryRun) {
+    fmt.note(
+      [
+        `${chalk.green(`${toCreate.length} to create`)}  ${chalk.cyan(`${toComment.length} to comment`)}`,
+        '',
+        ...toCreate.map((i) => `${chalk.green('+ create')} ${i.key} — ${i.title}`),
+        ...toComment.map((c) => `${chalk.cyan('~ comment')} ${c.item.key} → task ${c.taskId}`),
+      ].join('\n'),
+      'Dry run — no writes',
+    );
+    fmt.outro(`Dry run complete: would create ${toCreate.length}, comment ${toComment.length}.`);
+    return { created: 0, commented: 0, dryRun: true };
+  }
+
+  // ── Execute: fail-fast. Input was validated atomically; the write phase is
+  //    fail-fast + idempotent-resumable (a re-run skips created tasks). ──
+  let created = 0;
+  for (const item of toCreate) {
+    try {
+      await client.createTask(listId, {
+        name: item.title,
+        description: embedSentinel(item.description, item.key),
+      });
+      created++;
+    } catch (err) {
+      fmt.cancel(`Failed creating task for "${item.key}" after ${created} created (re-run to resume): ${errMessage(err)}`);
+    }
+  }
+
+  let commented = 0;
+  for (const { item, taskId } of toComment) {
+    try {
+      await client.addComment(taskId, RECURRING_COMMENT);
+      commented++;
+    } catch (err) {
+      fmt.cancel(`Failed commenting on task ${taskId} for "${item.key}": ${errMessage(err)}`);
+    }
+  }
+
+  fmt.outro(`${chalk.green(`${created} created`)} · ${chalk.cyan(`${commented} commented`)}`);
+  return { created, commented, dryRun: false };
+}
+
+function errMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}

package/integrations/clickup.mjs

@@ -0,0 +1,137 @@
+// integrations/clickup.mjs — ClickUp v2 HTTP client for the aw CLI.
+//
+// Faithful .mjs port of apps/api/src/mcp/integrations/clickup.handler.ts, which
+// remains the source of truth for base URL, headers, 10s timeout, and the
+// throw-on-non-ok contract. The CLI runs standalone ESM (no TS build), so the
+// handler cannot be imported directly. Additions over the handler: page
+// accumulation with a hard cap and bounded 429 backoff (spec §3.3, §3.4).
+//
+// A factory (createClickUpClient) injects token + sleep so behavior is unit
+// testable with a mocked global fetch and no real timers.
+
+export const CLICKUP_BASE = 'https://api.clickup.com/api/v2';
+export const MAX_PAGES = 200;
+export const MAX_RETRIES = 3;
+// The handler uses 10s for interactive single-task MCP calls. Bulk list paging
+// over a large list is much slower (observed ~40s for one 100-task page), so
+// the CLI uses a far larger per-request budget, overridable via env for very
+// large lists. (spec §3.3)
+export const DEFAULT_TIMEOUT_MS = 120_000;
+const ENV_TIMEOUT_MS = Number(process.env.AW_CLICKUP_TIMEOUT_MS);
+const REQUEST_TIMEOUT_MS = Number.isFinite(ENV_TIMEOUT_MS) && ENV_TIMEOUT_MS > 0
+  ? ENV_TIMEOUT_MS
+  : DEFAULT_TIMEOUT_MS;
+const MAX_BACKOFF_MS = 60_000;
+
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// Resolve a 429 backoff delay (ms) from Retry-After (seconds) or
+// X-RateLimit-Reset (epoch seconds), clamped to [0, 60]s. Defaults to 1s.
+function resolveRetryDelayMs(res) {
+  const retryAfter = res.headers.get('retry-after');
+  if (retryAfter !== null && retryAfter !== undefined && retryAfter !== '') {
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds)) return clampMs(seconds * 1000);
+  }
+  const reset = res.headers.get('x-ratelimit-reset');
+  if (reset !== null && reset !== undefined && reset !== '') {
+    const resetEpoch = Number(reset);
+    if (Number.isFinite(resetEpoch)) return clampMs(resetEpoch * 1000 - Date.now());
+  }
+  return 1000;
+}
+
+function clampMs(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return 0;
+  return Math.min(ms, MAX_BACKOFF_MS);
+}
+
+/**
+ * @param {{ token?: string, sleep?: (ms: number) => Promise<void> }} [opts]
+ */
+export function createClickUpClient(opts = {}) {
+  const token = opts.token ?? process.env.CLICKUP_API_TOKEN ?? '';
+  const sleep = opts.sleep ?? realSleep;
+
+  async function clickupFetch(path, init) {
+    if (!token) {
+      throw new Error('CLICKUP_API_TOKEN not set. Export a ClickUp API token before running clickup-sync.');
+    }
+
+    const method = init?.method ?? 'GET';
+    // A transport failure (timeout / reset) is ambiguous — the request may have
+    // been processed server-side. Retrying is only safe for idempotent GETs;
+    // retrying a POST (createTask / addComment) could duplicate a task or comment
+    // that actually succeeded. Non-GET transport failures fail fast; the sync is
+    // cross-run resumable, so the next run re-pulls and skips via the sentinel.
+    const retriableTransport = method === 'GET';
+
+    for (let attempt = 0; ; attempt++) {
+      let res;
+      try {
+        res = await fetch(`${CLICKUP_BASE}${path}`, {
+          method,
+          headers: { Authorization: token, 'Content-Type': 'application/json' },
+          body: init?.body,
+          signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+      } catch (err) {
+        // Large ClickUp lists have high, variable per-page latency, so retry
+        // transient GET failures with a bounded backoff before giving up.
+        if (retriableTransport && attempt < MAX_RETRIES) {
+          await sleep(Math.min((attempt + 1) * 2000, MAX_BACKOFF_MS));
+          continue;
+        }
+        const suffix = retriableTransport ? ` after ${MAX_RETRIES + 1} attempts` : ' (not retried; non-idempotent request)';
+        throw new Error(`ClickUp ${method} request failed${suffix}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+
+      if (res.ok) return res.json();
+
+      // 429 means the request was rejected before side effects, so it is safe to
+      // retry for any method; every other non-2xx fails fast.
+      if (res.status === 429 && attempt < MAX_RETRIES) {
+        await sleep(resolveRetryDelayMs(res));
+        continue;
+      }
+
+      const text = await res.text();
+      throw new Error(`ClickUp API ${res.status}: ${text.slice(0, 500)}`);
+    }
+  }
+
+  // Page through every task in a list (spec §3.3). include_closed so completed
+  // prior tasks are not recreated; subtasks so nested tasks are matched too.
+  async function listAllTasks(listId) {
+    const tasks = [];
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const params = new URLSearchParams({
+        page: String(page),
+        include_closed: 'true',
+        subtasks: 'true',
+      });
+      const body = await clickupFetch(`/list/${encodeURIComponent(listId)}/task?${params}`);
+      const pageTasks = Array.isArray(body?.tasks) ? body.tasks : [];
+      if (pageTasks.length === 0) return tasks;
+      tasks.push(...pageTasks);
+      if (body?.last_page === true) return tasks;
+    }
+    throw new Error(`ClickUp list ${listId} exceeded the ${MAX_PAGES}-page cap; aborting to avoid duplicate creates.`);
+  }
+
+  async function createTask(listId, { name, description }) {
+    return clickupFetch(`/list/${encodeURIComponent(listId)}/task`, {
+      method: 'POST',
+      body: JSON.stringify({ name, description }),
+    });
+  }
+
+  async function addComment(taskId, commentText) {
+    return clickupFetch(`/task/${encodeURIComponent(taskId)}/comment`, {
+      method: 'POST',
+      body: JSON.stringify({ comment_text: commentText }),
+    });
+  }
+
+  return { clickupFetch, listAllTasks, createTask, addComment };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.84",
+  "version": "0.1.85",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "bin.js",
     "c4/",
     "cli.mjs",
+    "clickup-sync.mjs",
     "commands/",
     "config.mjs",
     "codex.mjs",

package/render-rules.mjs

@@ -398,7 +398,7 @@ Is the user authoring/editing a CASRE artifact (command, agent, skill, rule, eva
                                         └── NO  → /aw-build
 \`\`\`
 
-**ADK triggers**: "create an agent/skill/command/rule/eval", "score my skill", "audit all agents", "ADK", "developer kit", "fix lint errors" on registry artifacts.
+**ADK triggers**: "create/improve an agent/skill/command/rule/eval", "score my skill", "audit all agents", "ADK", "developer kit", "fix lint errors" on registry artifacts, trigger/routing quality, skill context size, token budget, evidence packets, progressive disclosure, or stop conditions for AW skills.
 
 **Publish triggers**: "push this agent/skill/rule to the registry", "publish registry changes", "sync to platform-docs", "aw push", "aw push-rules". NOT regular git push, app PRs, or deploys.
 
@@ -412,6 +412,12 @@ Is the user authoring/editing a CASRE artifact (command, agent, skill, rule, eva
 - /aw-build → code changes with tests.
 - /aw-investigate → reproduction + root cause evidence.
 
+## Token Budget Model
+
+- Start from a bounded evidence packet: prompt, repo instructions, existing AW docs/state, exact target files/tests, and git diff.
+- Load bulky platform/domain references only after the selected stage skill or touched files require them.
+- Stop context gathering once route, repo scope, next artifact/command, assumptions, blockers, and validation proof are clear.
+
 ## Org Rules
 
 After the stage skill is loaded, also read the relevant org rules: