quiver-cli 1.3.0 → 2.0.0

package/template/.agents/skills/design/impeccable/scripts/hook.mjs

@@ -1,78 +0,0 @@
-#!/usr/bin/env node
-/**
- * Impeccable design hook — PostToolUse + Stop entry point.
- *
- * Reads the Claude Code / Codex / Cursor hook event from stdin and routes by
- * `hook_event_name`:
- *
- *   - PostToolUse: runs the immediate-tier detector rules against the touched
- *     file and emits a system reminder via
- *     `hookSpecificOutput.additionalContext` when findings exist.
- *   - Stop: runs the FULL detector rule set over every UI file touched this
- *     session (the deep pass), deduped against what the per-edit pass already
- *     surfaced, and emits once via the Stop additionalContext channel.
- *
- * Contract: never break a turn. Always exit 0. Clean files emit a small ack
- * unless quiet mode is enabled; a clean Stop pass is silent.
- *
- * Most logic lives in `hook-lib.mjs` so it is unit-testable without a
- * subprocess. This file is the thin stdin/stdout adapter.
- */
-
-import { runHook, runStopHook, writeAuditLog } from './hook-lib.mjs';
-
-async function readStdin() {
-  if (process.stdin.isTTY) return '';
-  const chunks = [];
-  for await (const chunk of process.stdin) chunks.push(chunk);
-  return Buffer.concat(chunks).toString('utf-8');
-}
-
-function isStopEvent(stdinJson) {
-  try {
-    const event = JSON.parse(stdinJson);
-    return event && typeof event === 'object' && event.hook_event_name === 'Stop';
-  } catch {
-    // Malformed stdin falls through to runHook, which audits the skip.
-    return false;
-  }
-}
-
-async function main() {
-  // Snapshot the inherited env FIRST so the re-entrancy guard checks the
-  // parent's value, not the value we are about to export for any child
-  // processes the hook might ever spawn.
-  const inheritedEnv = { ...process.env };
-  process.env.IMPECCABLE_HOOK_DEPTH = process.env.IMPECCABLE_HOOK_DEPTH || '1';
-
-  let stdinJson = '';
-  try { stdinJson = await readStdin(); } catch { /* fall through */ }
-
-  const run = isStopEvent(stdinJson) ? runStopHook : runHook;
-  const result = await run({
-    stdinJson,
-    env: inheritedEnv,
-    cwd: process.cwd(),
-  });
-
-  writeAuditLog(process.env, result.audit, process.cwd());
-
-  if (result.stdout) process.stdout.write(result.stdout);
-  process.exit(result.exitCode || 0);
-}
-
-main().catch((err) => {
-  // Last-ditch: never break the agent's turn even if something we did not
-  // anticipate goes wrong. Audit-log the failure if logging is enabled.
-  try {
-    writeAuditLog(process.env, {
-      ts: new Date().toISOString(),
-      event: 'hook-error',
-      error: String(err && err.message ? err.message : err),
-    });
-  } catch { /* swallow */ }
-  if (process.env.IMPECCABLE_HOOK_DEBUG) {
-    process.stderr.write(`[impeccable-hook] ${err}\n`);
-  }
-  process.exit(0);
-});

package/template/.agents/skills/design/impeccable/scripts/lib/artifact-schema.mjs

@@ -1,93 +0,0 @@
-/**
- * Schema versions for the artifacts Impeccable writes, plus the readers and
- * writers for the PRODUCT.md provenance stamp.
- *
- * Why schema versions rather than the skill version: a PRODUCT.md written by
- * v4.0.0 is not stale under v4.0.1, so stamping the release version would make
- * every artifact "old" on every patch. A schema version changes only when the
- * shape changes, which is exactly when a migration is owed. It also gives the
- * writing flows a literal constant to copy instead of a value they would have
- * to look up.
- *
- * DESIGN.md deliberately carries no stamp. It follows the external
- * design.md spec that Stitch's linter validates, and an extra frontmatter key
- * risks failing that lint for no gain: every DESIGN.md staleness signal
- * (sidecar schema version, sidecar mtime, section coverage, git drift) is
- * measurable without one.
- */
-
-/** PRODUCT.md as init.md writes it today: the ten-section v4 record. */
-export const PRODUCT_SCHEMA_VERSION = 1;
-
-/** `.impeccable/design.json`, as documented in reference/document.md Step 4b. */
-export const DESIGN_SIDECAR_SCHEMA_VERSION = 2;
-
-/**
- * Sections init.md added in v4. A PRODUCT.md carrying none of them, and no
- * stamp, predates the current record. Used only as a fallback: an explicit
- * stamp always wins.
- */
-export const PRODUCT_V4_SECTIONS = Object.freeze([
-  'Positioning',
-  'Operating Context',
-  'Evidence on Hand',
-  'Product Principles',
-]);
-
-/**
- * Headings Impeccable used to read and no longer does, with the reason. The
- * agent needs the reason: told only that a field is deprecated it tends to
- * preserve it "just in case", which is how a v3 register value keeps steering
- * v4 output.
- */
-export const PRODUCT_DEPRECATED_SECTIONS = Object.freeze({
-  Register: 'v4 replaced the brand/product register axis with the four visitor modes '
-    + '(Persuade, Operate, Read, Experience), which are chosen per surface and persisted in that '
-    + "surface's brief. Nothing reads `## Register` any more.",
-});
-
-const PRODUCT_STAMP_RE = /^[ \t]*<!--[ \t]*impeccable:product-schema[ \t]+(\d+)[ \t]*-->[ \t]*$/im;
-
-/** The literal stamp line, for the init template and for migrations. */
-export function productStampLine(version = PRODUCT_SCHEMA_VERSION) {
-  return `<!-- impeccable:product-schema ${version} -->`;
-}
-
-/**
- * Schema version stamped in a PRODUCT.md body, or null when unstamped. Null
- * means "written before stamping existed", not "invalid".
- */
-export function readProductSchemaVersion(markdown) {
-  const match = String(markdown || '').match(PRODUCT_STAMP_RE);
-  if (!match) return null;
-  const version = Number.parseInt(match[1], 10);
-  return Number.isInteger(version) ? version : null;
-}
-
-/**
- * Add or update the stamp, returning the new body. Idempotent. A stamped file
- * keeps the stamp where it already sits so a migration never reorders the
- * user's prose; an unstamped file gets it directly under the leading `#`
- * heading, or at the top when there is none.
- */
-export function stampProductSchema(markdown, version = PRODUCT_SCHEMA_VERSION) {
-  const body = String(markdown || '');
-  const line = productStampLine(version);
-  if (PRODUCT_STAMP_RE.test(body)) return body.replace(PRODUCT_STAMP_RE, line);
-
-  const lines = body.split('\n');
-  const headingIndex = lines.findIndex((entry) => /^#\s+\S/.test(entry));
-  if (headingIndex === -1) return `${line}\n\n${body.replace(/^\n+/, '')}`;
-  lines.splice(headingIndex + 1, 0, '', line);
-  return lines.join('\n');
-}
-
-/**
- * Schema version of a parsed design.json. Returns null for a missing or
- * non-numeric field, which is how schemaVersion-1-era sidecars present
- * (the field predates the v2 rewrite in some files).
- */
-export function readSidecarSchemaVersion(sidecar) {
-  const version = sidecar && typeof sidecar === 'object' ? sidecar.schemaVersion : null;
-  return Number.isInteger(version) ? version : null;
-}

package/template/.agents/skills/design/impeccable/scripts/lib/composition-catalog.mjs

@@ -1,200 +0,0 @@
-import crypto from 'node:crypto';
-import { readFileSync } from 'node:fs';
-import { CONCEPT_STATUSES, normalizeConceptForm } from './concept-catalog.mjs';
-// Defined in roll-selection.mjs for the same reason WELL_TIERS is: this file
-// reads the filesystem, and the roll API imports the taxonomy to validate its
-// grain and platform parameters. Re-exported so importers have one place to look.
-import { COMPOSITION_GRAINS, COMPOSITION_PLATFORMS, isGrain, isPlatform } from './roll-selection.mjs';
-export { COMPOSITION_GRAINS, COMPOSITION_PLATFORMS, isGrain, isPlatform };
-
-// Catalog B: compositions rather than styles. A composition organizes attention,
-// sequence, or manipulation on a surface and must survive being dressed in
-// any committed visual identity; it deliberately carries no palette or type
-// half. Surface-scope seeds draw from here (plus catalog A duals); direction
-// seeds pair one composition with a chosen world for the first surface.
-
-export const COMPOSITION_GRAMMAR_PREFIXES = [
-  'Staging/hierarchy:',
-  'Sequence/attention:',
-  'Controls/state:',
-  'Adaptation:',
-];
-
-// Surfaces align with the skill's modes: a persuade composition and an operate
-// composition are different species, and read/experience surfaces get their own.
-export const COMPOSITION_SURFACES = new Set(['persuade', 'operate', 'read', 'experience']);
-
-
-export function compositionContentHash(composition) {
-  const payload = [
-    composition?.form ?? '',
-    composition?.lineage ?? '',
-    JSON.stringify(composition?.tags ?? []),
-    JSON.stringify(composition?.grammar ?? []),
-    composition?.spark ?? '',
-    composition?.webLeverage ?? '',
-  ].join('\n');
-  return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 12);
-}
-
-export function validateCompositionEntry(composition, { existingForms = new Map() } = {}) {
-  const errors = [];
-  const id = composition?.id || '(unknown)';
-  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(composition?.id || '')) {
-    errors.push(`invalid composition id: ${String(composition?.id)}`);
-  }
-  const normalized = normalizeConceptForm(composition?.form);
-  if (!normalized) {
-    errors.push(`composition ${id} needs a form`);
-  } else if (existingForms.has(normalized)) {
-    errors.push(`duplicate composition form: ${id} and ${existingForms.get(normalized)}`);
-  }
-  if (typeof composition?.form !== 'string'
-    || composition.form.trim().length < 40
-    || composition.form.trim().length > 360
-    || !composition.form.includes(',')) {
-    errors.push(`composition ${id} must name a staging and its structural mechanism after a comma`);
-  }
-  if (typeof composition?.lineage !== 'string'
-    || composition.lineage.trim().length < 12
-    || composition.lineage.trim().length > 200) {
-    errors.push(`composition ${id} needs lineage metadata of 12–200 characters`);
-  }
-  if (!COMPOSITION_SURFACES.has(composition?.surface)) {
-    errors.push(`composition ${id} needs a surface of ${[...COMPOSITION_SURFACES].join(', ')}`);
-  }
-  // Grain: how much of the product this composes. Optional, and absence means
-  // eligible at any grain, so nothing needs backfilling.
-  if (composition?.grain !== undefined && composition.grain !== null && !isGrain(composition.grain)) {
-    errors.push(`composition ${id} grain "${composition.grain}" must be one of ${COMPOSITION_GRAINS.join(', ')}`);
-  }
-  // Platforms this composition survives. Absence means all of them, so listing
-  // every platform is the same as omitting the field and is rejected in favour of
-  // leaving it out; an empty array would exclude the entry from every roll.
-  if (composition?.platforms !== undefined && composition.platforms !== null) {
-    const list = composition.platforms;
-    if (!Array.isArray(list) || list.length === 0) {
-      errors.push(`composition ${id} platforms must be a non-empty array, or omitted to allow every platform`);
-    } else if (list.some(entry => !isPlatform(entry))) {
-      errors.push(`composition ${id} platforms may only contain ${COMPOSITION_PLATFORMS.join(', ')}`);
-    } else if (new Set(list).size !== list.length) {
-      errors.push(`composition ${id} platforms must not repeat a platform`);
-    } else if (list.length === COMPOSITION_PLATFORMS.length) {
-      errors.push(`composition ${id} platforms lists every platform; omit the field instead`);
-    }
-  }
-  if (!Array.isArray(composition?.tags)
-    || composition.tags.length !== 3
-    || composition.tags.some(tag => typeof tag !== 'string' || !tag.trim())) {
-    errors.push(`composition ${id} must have exactly three structural tags`);
-  }
-  if (!Array.isArray(composition?.grammar)
-    || composition.grammar.length !== COMPOSITION_GRAMMAR_PREFIXES.length
-    || composition.grammar.some(rule => typeof rule !== 'string' || rule.trim().length < 12 || rule.trim().length > 180)) {
-    errors.push(`composition ${id} needs grammar with exactly four rules of 12–180 characters`);
-  } else {
-    const unique = new Set(composition.grammar.map(normalizeConceptForm));
-    if (unique.size !== COMPOSITION_GRAMMAR_PREFIXES.length) {
-      errors.push(`composition ${id} has duplicate grammar rules`);
-    }
-    if (composition.grammar.some((rule, index) => !rule.startsWith(COMPOSITION_GRAMMAR_PREFIXES[index]))) {
-      errors.push(`composition ${id} grammar must use staging, sequence, controls, and adaptation prefixes in order`);
-    }
-  }
-  if (typeof composition?.spark !== 'string'
-    || composition.spark.trim().length < 80
-    || composition.spark.trim().length > 320) {
-    errors.push(`composition ${id} needs a vivid spark of 80–320 characters`);
-  }
-  if (typeof composition?.webLeverage !== 'string'
-    || composition.webLeverage.trim().length < 20
-    || composition.webLeverage.trim().length > 240) {
-    errors.push(`composition ${id} needs web leverage of 20–240 characters`);
-  }
-  return errors;
-}
-
-export function readCompositionCatalog(catalogPath, reviewsPath) {
-  const catalog = JSON.parse(readFileSync(catalogPath, 'utf8'));
-  const reviewData = JSON.parse(readFileSync(reviewsPath, 'utf8'));
-  const reviews = reviewData.reviews || {};
-  const familiesById = new Map((catalog.families || []).map(family => [family.id, family]));
-  const compositions = (catalog.compositions || []).map(composition => ({
-    ...composition,
-    familyLabel: familiesById.get(composition.familyId)?.label || null,
-    status: reviews[composition.id]?.status || 'pending',
-    review: reviews[composition.id] || null,
-  }));
-  return { catalog, reviewData, reviews, compositions };
-}
-
-export function validateCompositionCatalog(catalog, reviewData, { minimumTotal } = {}) {
-  const errors = [];
-  const familyIds = new Set();
-  const ids = new Set();
-  const forms = new Map();
-
-  if (!Number.isInteger(catalog?.schemaVersion) || catalog.schemaVersion < 1) {
-    errors.push('composition catalog schemaVersion must be a positive integer');
-  }
-  if (typeof catalog?.qualityBar?.principle !== 'string' || catalog.qualityBar.principle.trim().length < 80) {
-    errors.push('composition qualityBar.principle must define the staging bar');
-  }
-  if (!Array.isArray(catalog?.families) || catalog.families.length < 4) {
-    errors.push('composition catalog needs at least four families');
-  }
-  for (const family of catalog?.families || []) {
-    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(family.id || '')) errors.push(`invalid composition family id: ${String(family.id)}`);
-    if (familyIds.has(family.id)) errors.push(`duplicate composition family id: ${family.id}`);
-    familyIds.add(family.id);
-    if (typeof family.description !== 'string' || family.description.trim().length < 40) {
-      errors.push(`composition family ${family.id || '(unknown)'} needs a description`);
-    }
-  }
-  for (const composition of catalog?.compositions || []) {
-    if (ids.has(composition.id)) errors.push(`duplicate composition id: ${composition.id}`);
-    ids.add(composition.id);
-    if (!familyIds.has(composition.familyId)) {
-      errors.push(`composition ${composition.id} must belong to a declared family, got: ${String(composition.familyId)}`);
-    }
-    errors.push(...validateCompositionEntry(composition, { existingForms: forms }));
-    const normalized = normalizeConceptForm(composition.form);
-    if (normalized) forms.set(normalized, composition.id);
-  }
-  if (minimumTotal !== undefined && (catalog?.compositions || []).length < minimumTotal) {
-    errors.push(`expected at least ${minimumTotal} compositions, found ${(catalog?.compositions || []).length}`);
-  }
-  for (const [id, review] of Object.entries(reviewData?.reviews || {})) {
-    if (!ids.has(id)) errors.push(`composition review references missing entry: ${id}`);
-    if (!CONCEPT_STATUSES.has(review?.status)) errors.push(`invalid composition review status for ${id}`);
-    if (typeof review?.formHash !== 'string' || !review.formHash.trim()) {
-      errors.push(`composition review ${id} needs a formHash`);
-    } else {
-      const entry = (catalog?.compositions || []).find(composition => composition.id === id);
-      if (entry && review.formHash !== compositionContentHash(entry)) {
-        errors.push(`composition review ${id} is stale: content changed since review`);
-      }
-    }
-    // Mirrors the concept catalog: an optional 1-3 grade on approved entries
-    // only, read as a calibration signal and used to weight challenger draws.
-    if (review?.rating !== undefined) {
-      if (![1, 2, 3].includes(review.rating)) {
-        errors.push(`review ${id} rating must be 1, 2, or 3`);
-      } else if (review.status !== 'approved') {
-        errors.push(`review ${id} rating only applies to approved compositions`);
-      }
-    }
-    if (review?.note !== undefined && (typeof review.note !== 'string' || !review.note.trim() || review.note.length > 500)) {
-      errors.push(`composition review ${id} note must be a non-empty string of 500 characters or fewer`);
-    }
-  }
-  return {
-    errors,
-    stats: {
-      families: familyIds.size,
-      compositions: (catalog?.compositions || []).length,
-      approved: Object.values(reviewData?.reviews || {}).filter(review => review?.status === 'approved').length,
-      rejected: Object.values(reviewData?.reviews || {}).filter(review => review?.status === 'rejected').length,
-    },
-  };
-}