@ancleto/spec 0.6.26 → 0.6.28

package/README.md

@@ -120,6 +120,8 @@ Cómo bajarlo:
 - Evitá `--with-engram` salvo que uses esa memoria: es el que más pesa (9× la memoria propia).
 - Podés deshabilitar cualquier servidor en tu `opencode.json`: `"mcp": { "engram": { "enabled": false } }`.
 
+Para medir el consumo **real** por sesión (no estimado): `ancleto stats` lee la base de sesiones de opencode y reporta tokens de entrada/salida/razonamiento/cache, costo y subagentes por sesión. Con `--session <id>` desglosa por agente y con `--since YYYY-MM-DD` permite comparar antes/después de una optimización. Solo funciona con opencode.
+
 ---
 
 ## Guía de .gitignore
@@ -201,6 +203,12 @@ ancleto upgrade           # Re-aplica templates y skills respetando tus personal
 
 ancleto check             # Verifica la integridad de la instalación (faltantes / huérfanos)
 
+ancleto specs check [--change <nombre>] [--json]
+                          # Valida keywords canónicos en aspec/specs y en los deltas de un change
+
+ancleto stats [--all] [--limit N] [--since YYYY-MM-DD] [--session <id>] [--json]
+                          # Tokens por sesión de opencode (rollup de subagentes; --session desglosa por agente)
+
 ancleto doctor            # Diagnostica el entorno (Node, node:sqlite, opencode.json)
 
 ancleto memory context [--scope <project|feature|task>] [--out <archivo>]

package/agents/documenter.md

@@ -105,12 +105,13 @@ Do not treat archive as a blind file move.
    - `tasks.md`
    - `specs/` when the change includes delta specs
 3. Determine whether the change includes spec deltas that must be reflected in `aspec/specs/`
-4. If needed, update the relevant source-of-truth specs so they reflect the completed change
-5. If the change is not ready for archive, stop and report the inconsistency clearly
-6. If the change is ready, archive it to `aspec/changes/archive/{YYYY-MM-DD}-{change-name}/`
-7. Remove the original active change directory from `aspec/changes/{change-name}/` after a successful archive
-8. If any files or folders remain in the original active change directory, report them as cleanup issues instead of leaving silent residue
-9. Return a short structured summary of the finalization and archive result
+4. When deltas exist, run `ancleto specs check --change {change-name} --json` before merging. If a delta spec or its target source-of-truth spec is non-canonical (translated keywords), stop and report it instead of merging into it
+5. If needed, update the relevant source-of-truth specs so they reflect the completed change
+6. If the change is not ready for archive, stop and report the inconsistency clearly
+7. If the change is ready, archive it to `aspec/changes/archive/{YYYY-MM-DD}-{change-name}/`
+8. Remove the original active change directory from `aspec/changes/{change-name}/` after a successful archive
+9. If any files or folders remain in the original active change directory, report them as cleanup issues instead of leaving silent residue
+10. Return a short structured summary of the finalization and archive result
 
 ## Source-of-Truth Rules
 

package/agents/spec-writer.md

@@ -44,8 +44,9 @@ using the `ancleto-workflow` skill and the conventions of:
    - `design.md`
    - `tasks.md`
    - `specs/{capability}/spec.md` as needed
-6. When the delegation says the context was produced without a technical seed, declare that in the generated artifacts.
-7. Return a brief summary with generated paths, scope, and open questions or risks
+6. Before returning, verify every generated spec uses the canonical keywords (`### Requirement:`, `#### Scenario:`, `**WHEN**`/`**THEN**`, `SHALL`); fix any translated heading or keyword in place — never leave a spec with translated keywords.
+7. When the delegation says the context was produced without a technical seed, declare that in the generated artifacts.
+8. Return a brief summary with generated paths, scope, and open questions or risks
 
 ## Change Naming
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancleto/spec",
-  "version": "0.6.26",
+  "version": "0.6.28",
   "description": "Orquestador SDD liviano con subagentes optimizados para costo/tokens",
   "type": "module",
   "bin": {

package/skills/ancleto-archive/SKILL.md

@@ -31,6 +31,8 @@ Read `aspec/changes/<name>/tasks.md` (when present); count `- [ ]` (incomplete)
 
 Check for delta specs at `aspec/changes/<name>/specs/`; if none, proceed without a sync prompt.
 
+**Canonical keywords first:** when delta specs exist and the CLI is available, run `ancleto specs check --change <name> --json`. If a delta spec or its target source-of-truth spec is non-canonical (translated keywords), warn that requirement blocks cannot be matched reliably and ask whether to normalize the affected spec first or archive without syncing that capability. Never merge into a non-canonical spec silently.
+
 **If delta specs exist:**
 
 - Diff each delta against its main spec at `aspec/specs/<capability>/spec.md`; show a combined summary of adds/modifications/removals/renames.

package/skills/ancleto-verify/SKILL.md

@@ -26,6 +26,12 @@ Read under `aspec/changes/<name>/`: `tasks.md` (required), plus `proposal.md`, `
 
 **Tasks:** parse checkboxes (`- [ ]` incomplete vs `- [x]` complete) and count. Each incomplete → CRITICAL: "Complete task: `<description>`" or "Mark as done if already implemented".
 
+**Canonical spec keywords:** run `ancleto specs check --change <name> --json` when the CLI is available. For every reported file:
+- Delta spec (`aspec/changes/<name>/specs/...`) → CRITICAL: "Non-canonical spec: `<file>` (missing: `<keywords>`)" + "Normalize `<file>` to the canonical English keywords before archiving".
+- Source-of-truth spec (`aspec/specs/...`) → WARNING with the same recommendation.
+
+A non-canonical spec cannot be matched for coverage or merged reliably, so report it before the checks below.
+
 **Spec coverage:** for each `### Requirement:` in `specs/`, search the codebase for related keywords. Unimplemented → CRITICAL: "Requirement not found: `<requirement name>`" + "Implement requirement: `<description>`".
 
 ### 3. Correctness

package/src/cli/index.js

@@ -4,7 +4,8 @@ import { cp, mkdir, access, writeFile, readFile, readdir, rename } from 'node:fs
 import { spawnSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { createInterface } from 'node:readline'
-import { join, dirname, resolve, basename } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { join, dirname, resolve, basename, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { homedir, tmpdir } from 'node:os'
 import { createMemoryEngine, createReadonlyMemoryEngine, defaultMemoryDbPath } from '../core/memory/engine.js'
@@ -40,6 +41,12 @@ Uso:
   ancleto discovery --check           Estado del seed (READY/STALE/PARTIAL/MISSING)
   ancleto discovery [--compress] [--include G] [--ignore G] [--token-budget N]
                                    Empaca el repo con Repomix y guarda estado
+  ancleto specs check [--change <name>] [--json]
+                                   Valida keywords canonicos (### Requirement:, WHEN, THEN)
+                                   en aspec/specs y, con --change, en los deltas del change
+  ancleto stats [--all] [--limit N] [--since YYYY-MM-DD] [--session <id>] [--json]
+                                   Tokens por sesion de opencode (entrada/salida/razonamiento/cache),
+                                   con rollup de subagentes y desglose por agente con --session
   ancleto memory context [--scope X] [--out file]
                                    Imprime/escribe el bloque <ProjectMemoryRules> (reglas activas)
   ancleto memory list [--type X] [--scope X] [--all] [--json]
@@ -980,6 +987,311 @@ async function checkTierOrphan(cwd) {
   return warnings
 }
 
+// Un spec es canonico cuando usa los keywords literales en ingles. Detecta specs
+// traducidos (p. ej. "#### RF1:" + "**Dado**/**Cuando**/**Entonces**"), que rompen
+// la cobertura por keywords y el merge de deltas.
+function specIssues(content) {
+  const missing = []
+  if (!/^###\s+Requirement:/m.test(content)) missing.push('### Requirement:')
+  if (/^####\s+Scenario:/m.test(content)) {
+    if (!/\bWHEN\b/.test(content)) missing.push('WHEN')
+    if (!/\bTHEN\b/.test(content)) missing.push('THEN')
+  }
+  const unexpected = []
+  const re = /^####\s+(.+)$/gm
+  let m
+  while ((m = re.exec(content)) !== null) {
+    if (!/^Scenario\b/.test(m[1])) unexpected.push(`#### ${m[1]}`)
+  }
+  return { missing, unexpected }
+}
+
+async function collectSpecFiles(dir) {
+  const out = []
+  if (!(await exists(dir))) return out
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name)
+    if (e.isDirectory()) out.push(...(await collectSpecFiles(p)))
+    else if (e.name === 'spec.md') out.push(p)
+  }
+  return out
+}
+
+async function specsCheckCommand(args) {
+  const cwd = process.cwd()
+  const asJson = args.includes('--json')
+  const ci = args.indexOf('--change')
+  const change = ci >= 0 ? args[ci + 1] : null
+  const files = await collectSpecFiles(join(cwd, CHANGES_ROOT, 'specs'))
+  if (change) {
+    const changeDir = join(cwd, CHANGES_ROOT, 'changes', change)
+    if (!(await exists(changeDir))) {
+      console.error(`ancleto: no existe el change "${change}" en ${CHANGES_ROOT}/changes/`)
+      process.exit(1)
+    }
+    files.push(...(await collectSpecFiles(join(changeDir, 'specs'))))
+  }
+  const findings = []
+  for (const f of files) {
+    const { missing, unexpected } = specIssues(await readFile(f, 'utf8'))
+    if (missing.length || unexpected.length) {
+      findings.push({ file: relative(cwd, f).replace(/\\/g, '/'), missing, unexpected })
+    }
+  }
+  const ok = findings.length === 0
+  if (asJson) {
+    console.log(JSON.stringify({ ok, scanned: files.length, nonCanonical: findings }, null, 2))
+  } else if (files.length === 0) {
+    console.log('ancleto: no hay specs para revisar')
+  } else {
+    for (const f of files) {
+      const rel = relative(cwd, f).replace(/\\/g, '/')
+      const found = findings.find((x) => x.file === rel)
+      if (found) {
+        console.log(`  ✖ ${rel} (revisar: ${[...found.missing, ...found.unexpected].join(', ')})`)
+      } else {
+        console.log(`  ✔ ${rel}`)
+      }
+    }
+    console.log(ok ? `ancleto: ${files.length} spec(s) canonicos` : `ancleto: ${findings.length} de ${files.length} spec(s) sin keywords canonicos`)
+  }
+  process.exit(ok ? 0 : 1)
+}
+
+function opencodeDbPath() {
+  return process.env.ANCLETO_OPENCODE_DB || join(homedir(), '.local', 'share', 'opencode', 'opencode.db')
+}
+
+function fmtTokens(n) {
+  if (!n) return '0'
+  if (n >= 1e9) return `${(n / 1e9).toFixed(2)}B`
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}k`
+  return String(n)
+}
+
+function fmtCost(c) {
+  return c && c < 0.01 ? `$${c.toFixed(4)}` : `$${(c || 0).toFixed(2)}`
+}
+
+function fmtDate(ms) {
+  const d = new Date(ms || 0)
+  const p = (x) => String(x).padStart(2, '0')
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`
+}
+
+const normPath = (p) => String(p || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase()
+
+function sessionModel(model) {
+  try {
+    const m = JSON.parse(model || '{}')
+    return m.id ? `${m.id}${m.providerID ? ` (${m.providerID})` : ''}` : ''
+  } catch {
+    return ''
+  }
+}
+
+function buildSessionTree(sessions) {
+  const byId = new Map(sessions.map((s) => [s.id, s]))
+  const children = new Map()
+  for (const s of sessions) {
+    if (!s.parent_id) continue
+    if (!children.has(s.parent_id)) children.set(s.parent_id, [])
+    children.get(s.parent_id).push(s)
+  }
+  const cache = new Map()
+  const totalsOf = (id) => {
+    if (cache.has(id)) return cache.get(id)
+    const own = byId.get(id)
+    const t = {
+      input: own?.tokens_input || 0,
+      output: own?.tokens_output || 0,
+      reasoning: own?.tokens_reasoning || 0,
+      cacheRead: own?.tokens_cache_read || 0,
+      cacheWrite: own?.tokens_cache_write || 0,
+      cost: own?.cost || 0,
+      sessions: own ? 1 : 0
+    }
+    for (const c of children.get(id) || []) {
+      const ct = totalsOf(c.id)
+      t.input += ct.input
+      t.output += ct.output
+      t.reasoning += ct.reasoning
+      t.cacheRead += ct.cacheRead
+      t.cacheWrite += ct.cacheWrite
+      t.cost += ct.cost
+      t.sessions += ct.sessions
+    }
+    cache.set(id, t)
+    return t
+  }
+  const subtreeIds = (id) => [id, ...(children.get(id) || []).flatMap((c) => subtreeIds(c.id))]
+  return { byId, totalsOf, subtreeIds }
+}
+
+function sessionInfo(s, totals) {
+  return {
+    id: s.id,
+    title: s.title || null,
+    agent: s.agent || null,
+    model: sessionModel(s.model) || null,
+    subagentSessions: Math.max(0, totals.sessions - 1),
+    timeCreated: s.time_created || null,
+    timeUpdated: s.time_updated || null,
+    cost: totals.cost,
+    tokens: {
+      input: totals.input,
+      output: totals.output,
+      reasoning: totals.reasoning,
+      cacheRead: totals.cacheRead,
+      cacheWrite: totals.cacheWrite
+    }
+  }
+}
+
+async function statsCommand(args) {
+  const asJson = args.includes('--json')
+  const all = args.includes('--all')
+  const si = args.indexOf('--session')
+  const sessionId = si >= 0 ? args[si + 1] : null
+  const li = args.indexOf('--limit')
+  const limit = li >= 0 ? Number.parseInt(args[li + 1], 10) : 10
+  if (li >= 0 && (!Number.isFinite(limit) || limit < 1)) {
+    console.error('ancleto: --limit requiere un entero >= 1')
+    process.exit(1)
+  }
+  const sinceIdx = args.indexOf('--since')
+  const sinceRaw = sinceIdx >= 0 ? args[sinceIdx + 1] : null
+  let since = null
+  if (sinceRaw) {
+    const t = Date.parse(`${sinceRaw}T00:00:00`)
+    if (Number.isNaN(t)) {
+      console.error('ancleto: --since requiere formato YYYY-MM-DD')
+      process.exit(1)
+    }
+    since = t
+  }
+
+  const dbPath = opencodeDbPath()
+  if (!(await exists(dbPath))) {
+    console.error(`ancleto: no se encontro la base de sesiones de opencode en ${dbPath}`)
+    console.error('ancleto: ancleto stats solo funciona con opencode (podes apuntar ANCLETO_OPENCODE_DB a la base)')
+    process.exit(1)
+  }
+  const db = new DatabaseSync(dbPath, { readOnly: true })
+  let allSessions
+  try {
+    allSessions = db.prepare('SELECT * FROM session').all()
+  } catch (err) {
+    console.error(`ancleto: no se pudo leer la base de sesiones: ${err.message}`)
+    process.exit(1)
+  }
+  const tree = buildSessionTree(allSessions)
+  const cwd = process.cwd()
+
+  if (sessionId) {
+    const root = tree.byId.get(sessionId)
+    if (!root) {
+      console.error(`ancleto: no existe la sesion "${sessionId}"`)
+      process.exit(1)
+    }
+    const ids = tree.subtreeIds(sessionId)
+    let messages = []
+    try {
+      messages = db.prepare(`SELECT data FROM message WHERE session_id IN (${ids.map(() => '?').join(',')})`).all(...ids)
+    } catch {
+      messages = []
+    }
+    const byAgent = new Map()
+    for (const row of messages) {
+      let d
+      try {
+        d = JSON.parse(row.data)
+      } catch {
+        continue
+      }
+      if (d.role !== 'assistant' || !d.tokens) continue
+      const key = d.agent || '(desconocido)'
+      const agg = byAgent.get(key) || { agent: key, messages: 0, input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 }
+      agg.messages++
+      agg.input += d.tokens.input || 0
+      agg.output += d.tokens.output || 0
+      agg.reasoning += d.tokens.reasoning || 0
+      agg.cacheRead += d.tokens.cache?.read || 0
+      agg.cacheWrite += d.tokens.cache?.write || 0
+      byAgent.set(key, agg)
+    }
+    const agents = [...byAgent.values()].sort((a, b) => b.input - a.input)
+    const totals = tree.totalsOf(sessionId)
+    db.close()
+    if (asJson) {
+      console.log(JSON.stringify({ ok: true, scope: 'session', session: sessionInfo(root, totals), byAgent: agents, totals }, null, 2))
+      return
+    }
+    console.log(`ancleto: sesion ${root.id}`)
+    console.log(`  titulo: ${root.title || '(sin titulo)'}`)
+    console.log(`  agente: ${root.agent || '-'} · modelo: ${sessionModel(root.model) || '-'}`)
+    console.log(`  creada: ${fmtDate(root.time_created)} · ultima actividad: ${fmtDate(root.time_updated)}`)
+    console.log(`  sesiones incluidas: ${totals.sessions} (raiz + subagentes)`)
+    console.log('')
+    console.log('  agente        mensajes   entrada   salida    razon     cache-read')
+    for (const a of agents) {
+      console.log(`  ${String(a.agent).padEnd(13)} ${String(a.messages).padEnd(10)} ${fmtTokens(a.input).padEnd(9)} ${fmtTokens(a.output).padEnd(9)} ${fmtTokens(a.reasoning).padEnd(9)} ${fmtTokens(a.cacheRead)}`)
+    }
+    console.log('')
+    console.log(`  totales: entrada ${fmtTokens(totals.input)} · salida ${fmtTokens(totals.output)} · razon ${fmtTokens(totals.reasoning)} · cache ${fmtTokens(totals.cacheRead)} · costo ${fmtCost(totals.cost)}`)
+    return
+  }
+
+  let roots = allSessions.filter((s) => !s.parent_id)
+  let scope = 'all'
+  if (!all) {
+    scope = 'directory'
+    const cwdN = normPath(cwd)
+    const inDir = (d) => {
+      const dn = normPath(d)
+      return dn === cwdN || dn.startsWith(`${cwdN}/`) || cwdN.startsWith(`${dn}/`)
+    }
+    roots = roots.filter((s) => inDir(s.directory))
+  }
+  if (since !== null) roots = roots.filter((s) => (s.time_created || 0) >= since)
+  roots.sort((a, b) => (b.time_updated || 0) - (a.time_updated || 0))
+  const shown = roots.slice(0, limit)
+  const rows = shown.map((s) => ({ ...sessionInfo(s, tree.totalsOf(s.id)), directory: s.directory }))
+  const totals = rows.reduce(
+    (acc, r) => {
+      acc.input += r.tokens.input
+      acc.output += r.tokens.output
+      acc.reasoning += r.tokens.reasoning
+      acc.cacheRead += r.tokens.cacheRead
+      acc.cacheWrite += r.tokens.cacheWrite
+      acc.cost += r.cost
+      return acc
+    },
+    { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0, cost: 0 }
+  )
+  db.close()
+
+  if (asJson) {
+    console.log(JSON.stringify({ ok: true, scope, directory: scope === 'directory' ? cwd.replace(/\\/g, '/') : null, since: sinceRaw || null, sessions: rows, totals }, null, 2))
+    return
+  }
+  if (rows.length === 0) {
+    console.log(`ancleto: no hay sesiones${scope === 'directory' ? ' para este directorio' : ''}${sinceRaw ? ` desde ${sinceRaw}` : ''}`)
+    if (scope === 'directory') console.log('ancleto: proba --all para ver todas las sesiones de la maquina')
+    return
+  }
+  console.log(`ancleto: stats (opencode)${scope === 'directory' ? ` — ${cwd.replace(/\\/g, '/')}` : ' — todas las sesiones'}${sinceRaw ? ` — desde ${sinceRaw}` : ''}`)
+  console.log('')
+  console.log('  fecha              agente        entrada   salida    razon     cache     costo    titulo')
+  for (const r of rows) {
+    console.log(`  ${fmtDate(r.timeUpdated).padEnd(18)} ${String(r.agent || '-').padEnd(13)} ${fmtTokens(r.tokens.input).padEnd(9)} ${fmtTokens(r.tokens.output).padEnd(9)} ${fmtTokens(r.tokens.reasoning).padEnd(9)} ${fmtTokens(r.tokens.cacheRead).padEnd(9)} ${fmtCost(r.cost).padEnd(8)} ${String(r.title || '').slice(0, 42)}`)
+  }
+  console.log('')
+  const shownLabel = roots.length > rows.length ? `${rows.length} de ${roots.length} sesiones` : rows.length === 1 ? '1 sesion' : `${rows.length} sesiones`
+  console.log(`  totales (${shownLabel}): entrada ${fmtTokens(totals.input)} · salida ${fmtTokens(totals.output)} · razon ${fmtTokens(totals.reasoning)} · cache ${fmtTokens(totals.cacheRead)} · costo ${fmtCost(totals.cost)}`)
+}
+
 async function doctorCommand() {
   let fatal = false
 
@@ -1045,6 +1357,12 @@ switch (cmd) {
   case 'check':
     await checkCommand()
     break
+  case 'specs':
+    await specsCheckCommand(rest)
+    break
+  case 'stats':
+    await statsCommand(rest)
+    break
   case 'doctor':
     await doctorCommand()
     break