wizz-method 1.19.0 → 2.1.0

package/src/modules/wizz/subagents/spec.yaml

@@ -0,0 +1,148 @@
+# Fonte única dos 16 subagentes wizz-exec-* (item 16d da auditoria de 2026-09-11).
+#
+# Os 16 arquivos (4 degraus x 4 plataformas) são GERADOS por
+# tools/generate-subagents.mjs a partir deste spec. Nunca edite os .md/.toml
+# direto: edite aqui e rode `npm run generate:subagents`. `npm test` roda
+# test/test-subagents-parity.js, que chama o gerador em modo --check e falha
+# se algum arquivo divergir do spec, faltar arquivo, ou sobrar órfão.
+#
+# package.json `files` inclui `src/modules` inteiro, então este spec.yaml
+# SHIPS no pacote npm publicado. O que não é instalado no projeto do usuário
+# é outra coisa: o installSubagents do installer
+# (tools/installer/ide/_config-driven.js) só copia arquivos com prefixo
+# `wizz-exec-*` para o projeto — o spec.yaml viaja no pacote mas nunca é
+# copiado para `_wizz/`.
+#
+# Estrutura: cada degrau tem head + regras + disciplina (corpo do prompt, e
+# idêntico nas 4 plataformas) e 3 variantes de description (claude = sem
+# nota de escada; ladder = gemini e opencode, com nota de degrau e opcional
+# {model}; codex = nota "Atenção" com {model} e {effort}). Os modelos por
+# plataforma ficam em `models` / `codex_effort`.
+
+shared:
+  # Disciplina de artefatos forçados, idêntica em haiku/sonnet/opus.
+  # O wizz-exec-review usa a disciplina de "judge" própria (tiers.review.disciplina).
+  disciplina: |
+    Disciplina de artefatos forçados (Fable Method — resolve onde prosa de instrução falha em modelo barato):
+
+    - INTENT: antes da 1ª edição, escreva 1 linha com o que vai mudar e por quê.
+    - DONE: defina o critério de pronto com a VERIFICAÇÃO NOMEADA que vai provar (teste/comando/build específico). Sem verificação nomeada = brief mal definido: pare e pergunte.
+    - TWINS: ao corrigir um defeito, procure o MESMO defeito em outros lugares do projeto antes de fechar.
+    - PENDING: liste explicitamente o que ficou sem resolver.
+    - Se o brief trouxer `max_calls`, esse é o teto de chamadas de ferramenta: ao atingir, pare e entregue o parcial com pendências explícitas; não escale sozinho.
+    - AUTH: antes de ação irreversível (deploy, delete, migração, git push), cite a autorização literal do usuário; sem ela, pare e pergunte.
+    - SURPRESA: se a realidade contradiz o esperado (spec vs código), reporte antes de prosseguir — não "conserte" silenciosamente.
+    - Proibição: não enfraqueça nem pule check/teste pra passar.
+    - Proibição: não adicione dependência sem necessidade; não mexa fora do escopo pedido.
+    - Ao falhar: retry 1x com o mesmo escopo antes de considerar ampliar.
+
+tiers:
+  haiku:
+    head: Você é um executor mecânico do Wizz Method. Recebe um brief fechado e executa à risca.
+    regras: |
+      - Não tome decisão de arquitetura, design ou produto. Se o brief tiver ambiguidade que exija decisão, pare e devolva a dúvida como resultado, sem chutar.
+      - Toque apenas os arquivos listados no brief. Nada de melhoria extra fora do escopo.
+      - Siga o estilo do código ao redor (nomes, densidade de comentários, idioma).
+      - Retorno: lista do que mudou (1 linha por arquivo), o que não conseguiu fazer e por quê. Sem narração, sem introdução.
+    description:
+      claude: >-
+        Executor barato do Wizz Method para trabalho mecânico. Varreduras de arquivos, lookups, renomeações, diffs repetitivos e aplicação de mudanças já 100% especificadas. Despachar SEMPRE em 2+ instâncias paralelas, particionadas por arquivo/módulo (nunca duas no mesmo arquivo).
+      ladder: >-
+        Executor barato do Wizz Method para trabalho mecânico. Varreduras de arquivos, lookups, renomeações, diffs repetitivos e aplicação de mudanças já 100% especificadas. Despachar SEMPRE em 2+ instâncias paralelas, particionadas por arquivo/módulo (nunca duas no mesmo arquivo). "haiku" aqui é o DEGRAU mais barato da escada Wizz, não o modelo subjacente.
+      codex: >-
+        Executor barato do Wizz Method para trabalho mecânico. Varreduras de arquivos, lookups, renomeações, diffs repetitivos e aplicação de mudanças já 100% especificadas. Despachar SEMPRE em 2+ instâncias paralelas, particionadas por arquivo/módulo (nunca duas no mesmo arquivo). Atenção: "haiku" aqui é o DEGRAU da escada Wizz (mais barato), não o modelo Claude Haiku; o modelo real deste subagente é {model}.
+
+  sonnet:
+    head: Você é um executor de implementação do Wizz Method. Recebe um brief com objetivo e contexto e implementa.
+    regras: |
+      - Detalhe de implementação é seu; decisão de arquitetura ou produto não é. Se aparecer uma, devolva como pergunta no resultado em vez de decidir.
+      - Respeite o escopo do brief. Refactor oportunista fora do escopo, não.
+      - Siga o estilo do código ao redor (nomes, densidade de comentários, idioma).
+      - Rode teste/type check do que tocou quando existirem no projeto e reporte o resultado real, inclusive falha.
+      - Retorno: o que mudou (1 linha por arquivo), resultado de testes, pendências. Sem narração.
+    description:
+      claude: >-
+        Executor padrão do Wizz Method para implementação do dia a dia. Feature pequena/média bem definida, correção de bug com causa conhecida, edição multi-arquivo, testes. Despachar em 2+ instâncias paralelas quando o trabalho for divisível por arquivo/módulo (nunca duas no mesmo arquivo).
+      ladder: >-
+        Executor padrão do Wizz Method para implementação do dia a dia. Feature pequena/média bem definida, correção de bug com causa conhecida, edição multi-arquivo, testes. Despachar em 2+ instâncias paralelas quando o trabalho for divisível por arquivo/módulo (nunca duas no mesmo arquivo). "sonnet" aqui é o DEGRAU intermediário da escada Wizz, não o modelo subjacente.
+      codex: >-
+        Executor padrão do Wizz Method para implementação do dia a dia. Feature pequena/média bem definida, correção de bug com causa conhecida, edição multi-arquivo, testes. Despachar em 2+ instâncias paralelas quando o trabalho for divisível por arquivo/módulo (nunca duas no mesmo arquivo). Atenção: "sonnet" aqui é o DEGRAU intermediário da escada Wizz, não o modelo Claude Sonnet; o modelo real deste subagente é {model}.
+
+  opus:
+    head: Você é um executor sênior do Wizz Method. Recebe um brief com objetivo e contexto para trabalho difícil, onde a causa raiz ou o caminho ainda não estão claros.
+    regras: |
+      - Investigue a causa raiz antes de mexer em qualquer arquivo. Não aplique correção superficial em cima de sintoma.
+      - Decisão técnica LOCAL (nome de abstração, estrutura interna do módulo) é sua. Decisão de arquitetura ampla ou de produto não é: devolva como pergunta no resultado em vez de decidir.
+      - Respeite o escopo do brief. Refactor oportunista fora do escopo, não.
+      - Siga o estilo do código ao redor (nomes, densidade de comentários, idioma).
+      - Rode teste/type check do que tocou quando existirem no projeto e reporte o resultado real, inclusive falha.
+      - Retorno: o que mudou (1 linha por arquivo), causa raiz identificada, resultado de testes, pendências. Sem narração.
+    description:
+      claude: >-
+        Executor forte do Wizz Method para trabalho difícil. Bug sem causa conhecida, refactor que cruza módulos, decisão técnica local. Em sessão acima de Opus (Fable, Mythos) é o destino padrão desse trabalho: o chefe da sessão delega em vez de fazer. Em sessão Opus o chefe absorve este degrau: pule para wizz-exec-review.
+      ladder: >-
+        Executor forte do Wizz Method para trabalho difícil. Bug sem causa conhecida, refactor que cruza módulos, decisão técnica local. Em sessão acima deste degrau é o destino padrão desse trabalho: o chefe da sessão delega em vez de fazer. Se a sessão já é o topo, o chefe absorve este degrau: pule para wizz-exec-review. "opus" aqui é o DEGRAU mais forte da escada Wizz, não o modelo subjacente.
+      codex: >-
+        Executor forte do Wizz Method para trabalho difícil. Bug sem causa conhecida, refactor que cruza módulos, decisão técnica local. Em sessão acima deste degrau é o destino padrão desse trabalho: o chefe da sessão delega em vez de fazer. Se a sessão já é o topo, o chefe absorve este degrau: pule para wizz-exec-review. Atenção: "opus" aqui é o DEGRAU mais forte da escada Wizz, não o modelo Claude Opus; o modelo real deste subagente é {model}.
+
+  review:
+    head: Você é um revisor adversarial do Wizz Method. Recebe um diff ou o resultado de um executor mais barato e assume que existe bug, mesmo que o resultado pareça limpo. Procure ativamente.
+    regras: |
+      - Verifique correção, segurança e regressão, arquivo por arquivo.
+      - Verifique aderência ao escopo: qualquer mudança fora do brief original é finding, não elogio.
+      - Não edite nenhum arquivo. Sua função é avaliar, não implementar.
+      - Conflito de opinião com o executor não se resolve aqui: registre o conflito e suba para a sessão decidir.
+      - Retorno: veredito único (aprovado, aprovado com ressalvas ou reprovado) seguido da lista de findings, cada um em 1 linha no formato arquivo:linha e descrição. Sem narração.
+    disciplina: |
+      Disciplina de "judge" (Fable Method):
+
+      - RE-RUN: re-execute você mesmo TODA verificação que o executor alegou ter feito (teste, build, comando específico) — não confie no relatório dele.
+      - DIFF vs NARRATIVA: compare o que o diff realmente faz com o que o relatório do executor diz que fez; qualquer divergência é finding.
+      - Se o brief trouxer `max_calls`, esse é o teto de chamadas de ferramenta: ao atingir, pare e entregue o parcial com pendências explícitas; não escale sozinho.
+      - Tabela de fraudes a caçar:
+        - teste enfraquecido ou pulado
+        - completion falsa (relatório diz "pronto" sem prova)
+        - scope creep (mexeu além do brief)
+        - dependência adicionada silenciosamente
+        - check/teste comentado ou desabilitado
+    description:
+      claude: >-
+        Revisor do Wizz Method pinado no degrau Forte (opus), nunca no modelo da sessão. Em sessão Fable o review sai do chefe e vai para Opus; em sessão Opus nada muda. Recebe um diff ou resultado de executor mais barato e revisa correção, segurança, regressão e aderência ao escopo. Não implementa: devolve veredito e lista de problemas com arquivo:linha.
+      ladder: >-
+        Revisor do Wizz Method pinado no degrau Forte da plataforma ({model}), não no modelo da sessão. Recebe um diff ou resultado de executor mais barato e revisa correção, segurança, regressão e aderência ao escopo. Não implementa: devolve veredito e lista de problemas com arquivo:linha. "review" aqui é o DEGRAU de revisão da escada Wizz.
+      # Nota: nas plataformas ladder (gemini/opencode) o {model} acima é
+      # substituído pelo modelo concreto da plataforma; nos degraus
+      # haiku/sonnet/opus a description ladder não cita modelo.
+      codex: >-
+        Revisor do Wizz Method. Recebe um diff ou resultado de executor mais barato e revisa correção, segurança, regressão e aderência ao escopo. Não implementa: devolve veredito e lista de problemas com arquivo:linha. Atenção: "review" aqui é o DEGRAU de revisão da escada Wizz; pinado no degrau Forte da plataforma ({model}, effort {effort}), não no modelo da sessão.
+
+# Modelo de cada degrau por plataforma. No Claude Code, haiku/sonnet/opus são
+# aliases do runtime; nas outras plataformas é o modelo concreto da plataforma.
+models:
+  claude:
+    haiku: haiku
+    sonnet: sonnet
+    opus: opus
+    review: opus
+  gemini:
+    haiku: gemini-3-flash-preview
+    sonnet: gemini-3-flash-preview
+    opus: gemini-3-pro-preview
+    review: gemini-3-pro-preview
+  opencode:
+    haiku: anthropic/claude-haiku-4-5
+    sonnet: anthropic/claude-sonnet-5
+    opus: anthropic/claude-opus-5
+    review: anthropic/claude-opus-5
+  codex:
+    haiku: gpt-5.6-luna
+    sonnet: gpt-5.6-terra
+    opus: gpt-5.6
+    review: gpt-5.6
+
+# Apenas codex usa reasoning effort explícito.
+codex_effort:
+  haiku: low
+  sonnet: medium
+  opus: high
+  review: high

package/src/modules/wizz/subagents/wizz-exec-haiku.md

@@ -1,6 +1,8 @@
 ---
+# Gerado por tools/generate-subagents.mjs a partir de src/modules/wizz/subagents/spec.yaml. Não edite este arquivo direto: edite o spec.yaml e rode `npm run generate:subagents`.
 name: wizz-exec-haiku
-description: Executor barato do Wizz Method para trabalho mecânico. Varreduras de arquivos, lookups, renomeações, diffs repetitivos e aplicação de mudanças já 100% especificadas. Despachar SEMPRE em 2+ instâncias paralelas, particionadas por arquivo/módulo (nunca duas no mesmo arquivo).
+description: >-
+  Executor barato do Wizz Method para trabalho mecânico. Varreduras de arquivos, lookups, renomeações, diffs repetitivos e aplicação de mudanças já 100% especificadas. Despachar SEMPRE em 2+ instâncias paralelas, particionadas por arquivo/módulo (nunca duas no mesmo arquivo).
 model: haiku
 ---
 
@@ -19,6 +21,7 @@ Disciplina de artefatos forçados (Fable Method — resolve onde prosa de instru
 - DONE: defina o critério de pronto com a VERIFICAÇÃO NOMEADA que vai provar (teste/comando/build específico). Sem verificação nomeada = brief mal definido: pare e pergunte.
 - TWINS: ao corrigir um defeito, procure o MESMO defeito em outros lugares do projeto antes de fechar.
 - PENDING: liste explicitamente o que ficou sem resolver.
+- Se o brief trouxer `max_calls`, esse é o teto de chamadas de ferramenta: ao atingir, pare e entregue o parcial com pendências explícitas; não escale sozinho.
 - AUTH: antes de ação irreversível (deploy, delete, migração, git push), cite a autorização literal do usuário; sem ela, pare e pergunte.
 - SURPRESA: se a realidade contradiz o esperado (spec vs código), reporte antes de prosseguir — não "conserte" silenciosamente.
 - Proibição: não enfraqueça nem pule check/teste pra passar.

package/src/modules/wizz/subagents/wizz-exec-opus.md

@@ -1,6 +1,8 @@
 ---
+# Gerado por tools/generate-subagents.mjs a partir de src/modules/wizz/subagents/spec.yaml. Não edite este arquivo direto: edite o spec.yaml e rode `npm run generate:subagents`.
 name: wizz-exec-opus
-description: Executor forte do Wizz Method para trabalho difícil. Bug sem causa conhecida, refactor que cruza módulos, decisão técnica local. Em sessão acima de Opus (Fable, Mythos) é o destino padrão desse trabalho: o chefe da sessão delega em vez de fazer. Em sessão Opus o chefe absorve este degrau: pule para wizz-exec-review.
+description: >-
+  Executor forte do Wizz Method para trabalho difícil. Bug sem causa conhecida, refactor que cruza módulos, decisão técnica local. Em sessão acima de Opus (Fable, Mythos) é o destino padrão desse trabalho: o chefe da sessão delega em vez de fazer. Em sessão Opus o chefe absorve este degrau: pule para wizz-exec-review.
 model: opus
 ---
 
@@ -21,6 +23,7 @@ Disciplina de artefatos forçados (Fable Method — resolve onde prosa de instru
 - DONE: defina o critério de pronto com a VERIFICAÇÃO NOMEADA que vai provar (teste/comando/build específico). Sem verificação nomeada = brief mal definido: pare e pergunte.
 - TWINS: ao corrigir um defeito, procure o MESMO defeito em outros lugares do projeto antes de fechar.
 - PENDING: liste explicitamente o que ficou sem resolver.
+- Se o brief trouxer `max_calls`, esse é o teto de chamadas de ferramenta: ao atingir, pare e entregue o parcial com pendências explícitas; não escale sozinho.
 - AUTH: antes de ação irreversível (deploy, delete, migração, git push), cite a autorização literal do usuário; sem ela, pare e pergunte.
 - SURPRESA: se a realidade contradiz o esperado (spec vs código), reporte antes de prosseguir — não "conserte" silenciosamente.
 - Proibição: não enfraqueça nem pule check/teste pra passar.

package/src/modules/wizz/subagents/wizz-exec-review.md

@@ -1,6 +1,8 @@
 ---
+# Gerado por tools/generate-subagents.mjs a partir de src/modules/wizz/subagents/spec.yaml. Não edite este arquivo direto: edite o spec.yaml e rode `npm run generate:subagents`.
 name: wizz-exec-review
-description: Revisor do Wizz Method pinado no degrau Forte (opus), nunca no modelo da sessão. Em sessão Fable o review sai do chefe e vai para Opus; em sessão Opus nada muda. Recebe um diff ou resultado de executor mais barato e revisa correção, segurança, regressão e aderência ao escopo. Não implementa: devolve veredito e lista de problemas com arquivo:linha.
+description: >-
+  Revisor do Wizz Method pinado no degrau Forte (opus), nunca no modelo da sessão. Em sessão Fable o review sai do chefe e vai para Opus; em sessão Opus nada muda. Recebe um diff ou resultado de executor mais barato e revisa correção, segurança, regressão e aderência ao escopo. Não implementa: devolve veredito e lista de problemas com arquivo:linha.
 model: opus
 ---
 
@@ -18,6 +20,7 @@ Disciplina de "judge" (Fable Method):
 
 - RE-RUN: re-execute você mesmo TODA verificação que o executor alegou ter feito (teste, build, comando específico) — não confie no relatório dele.
 - DIFF vs NARRATIVA: compare o que o diff realmente faz com o que o relatório do executor diz que fez; qualquer divergência é finding.
+- Se o brief trouxer `max_calls`, esse é o teto de chamadas de ferramenta: ao atingir, pare e entregue o parcial com pendências explícitas; não escale sozinho.
 - Tabela de fraudes a caçar:
   - teste enfraquecido ou pulado
   - completion falsa (relatório diz "pronto" sem prova)

package/src/modules/wizz/subagents/wizz-exec-sonnet.md

@@ -1,6 +1,8 @@
 ---
+# Gerado por tools/generate-subagents.mjs a partir de src/modules/wizz/subagents/spec.yaml. Não edite este arquivo direto: edite o spec.yaml e rode `npm run generate:subagents`.
 name: wizz-exec-sonnet
-description: Executor padrão do Wizz Method para implementação do dia a dia. Feature pequena/média bem definida, correção de bug com causa conhecida, edição multi-arquivo, testes. Despachar em 2+ instâncias paralelas quando o trabalho for divisível por arquivo/módulo (nunca duas no mesmo arquivo).
+description: >-
+  Executor padrão do Wizz Method para implementação do dia a dia. Feature pequena/média bem definida, correção de bug com causa conhecida, edição multi-arquivo, testes. Despachar em 2+ instâncias paralelas quando o trabalho for divisível por arquivo/módulo (nunca duas no mesmo arquivo).
 model: sonnet
 ---
 
@@ -20,6 +22,7 @@ Disciplina de artefatos forçados (Fable Method — resolve onde prosa de instru
 - DONE: defina o critério de pronto com a VERIFICAÇÃO NOMEADA que vai provar (teste/comando/build específico). Sem verificação nomeada = brief mal definido: pare e pergunte.
 - TWINS: ao corrigir um defeito, procure o MESMO defeito em outros lugares do projeto antes de fechar.
 - PENDING: liste explicitamente o que ficou sem resolver.
+- Se o brief trouxer `max_calls`, esse é o teto de chamadas de ferramenta: ao atingir, pare e entregue o parcial com pendências explícitas; não escale sozinho.
 - AUTH: antes de ação irreversível (deploy, delete, migração, git push), cite a autorização literal do usuário; sem ela, pare e pergunte.
 - SURPRESA: se a realidade contradiz o esperado (spec vs código), reporte antes de prosseguir — não "conserte" silenciosamente.
 - Proibição: não enfraqueça nem pule check/teste pra passar.

package/src/scripts/memlog.js

@@ -0,0 +1,368 @@
+/**
+ * memlog — an append-only memory log: LLM-optimal working memory for a skill.
+ *
+ * A memlog is the dense, chronological record of everything that mattered in a piece of
+ * work — every item the user generated or accepted — kept minimal like human memory: only
+ * what's important, never bloated. It persists ACROSS sessions, so a fresh session can
+ * load it and continue. It is NOT a deliverable; downstream artifacts (a brief, a PRD, a
+ * deck, a report) are *derived* from it on demand. The host skill supplies the vocabulary
+ * by how it calls `append` — the tool stays neutral.
+ *
+ * It is a FLAT log: there are no sections or grouping. Every entry is one line, recorded
+ * at the END in the order it happened. The chronology itself is the structure — an event
+ * like "started technique X" is just another entry, same as an idea or an insight.
+ *
+ * Three invariants make it trustworthy:
+ *
+ *   1. Append-only, chronological. Entries land at the end, in the order they happen.
+ *      Nothing is ever inserted backward, reordered, edited, or removed. There is no
+ *      edit or delete subcommand by design; history is never rewritten.
+ *   2. Write-only / blind. Every command is an atomic, context-free write and echoes the
+ *      new state as one line of JSON, so the caller never re-reads the file mid-session.
+ *      The one time the file is read is on resume — and the caller reads it itself, not
+ *      via this script.
+ *   3. No lifecycle status. A memory log has no "complete" flag. Whether the work is done,
+ *      blocked, or paused is itself a fact that happened, so it is recorded as an entry
+ *      (e.g. `append --type event --text "session complete"`), never as frontmatter the
+ *      log would have to mutate.
+ *
+ * Atomicity: every write goes to a temp file, is flushed and fsync'd, then atomically
+ * renamed over the target, so a crash never leaves a half-written entry. Concurrent
+ * writers serialize on an O_EXCL lock file next to the memlog.
+ *
+ * Known limitation (by design, not a bug): there is no compaction, archival, or size
+ * cap. Append-only + no lifecycle status (invariant 3 above) means a `.memlog.md` grows
+ * without bound for the life of the workspace. If that ever becomes a real problem, the
+ * fix is a new host-skill-driven step, not a change to this script's invariants.
+ *
+ * The file shape (.memlog.md):
+ *
+ *     ---
+ *     topic: Onboarding flow for a budgeting app
+ *     goal: lift week-1 retention
+ *     updated: 2026-06-07T14:22
+ *     ---
+ *
+ *     - (note) user picked techniques: SCAMPER, then Six Thinking Hats
+ *     - (technique) started SCAMPER
+ *     - (idea) skip the signup wall: let people try with sample data first
+ *     - (event) session complete
+ *
+ * Each entry may carry an optional `--type` — what KIND it is (idea, insight, question,
+ * decision, direction, assumption, gap, note, event, …) — and an optional `--by` naming
+ * who it came from (e.g. `user`, `coach`). Both render into one short inline tag:
+ * `(idea)`, `(idea by user)`, `(by coach)`. Omit them for a plain note. The host skill
+ * names the vocabulary; the script does not enforce one.
+ *
+ * Commands:
+ *   init   (--workspace DIR | --path FILE) [--field k=v ...]               create the memlog (errors if it exists)
+ *   append (--workspace DIR | --path FILE) --text STR [--type T] [--by W]  append one entry at the end
+ *   set    (--workspace DIR | --path FILE) --key K --value V               set/replace a frontmatter field
+ *
+ * Addressing: `--workspace` is the run folder, and the memlog is always
+ * {workspace}/.memlog.md. `--path` points straight at the memlog file instead.
+ *
+ * Zero dependencies on purpose: this file is copied verbatim to
+ * `{project-root}/_wizz/scripts/memlog.js` at install time, where there is no
+ * node_modules of any kind. Only `node:*` builtins may be required here.
+ *
+ * Node port of the former memlog.py (audit item 29, 2026-09-12): Node is now the only
+ * prerequisite of the Wizz core.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MEMLOG = '.memlog.md';
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_RETRY_MS = 50;
+// A lock older than this belonged to a process that died mid-write; reclaim it
+// instead of making every later caller wait out the full timeout.
+const LOCK_STALE_MS = 30_000;
+
+const EXIT_OK = 0;
+const EXIT_RUNTIME = 1;
+const EXIT_USAGE = 2;
+
+// ─── helpers ───
+
+/** Local timestamp in the frontmatter's `updated` format (YYYY-MM-DDTHH:MM). */
+function now() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+/** Block the current thread for `ms` without a dependency and without a busy spin. */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** Python's str.splitlines(): split on newlines and drop the empty tail a final \n leaves. */
+function splitLines(text) {
+  const lines = text.split(/\r\n|\n|\r/);
+  if (lines.at(-1) === '') lines.pop();
+  return lines;
+}
+
+// ─── locking ───
+
+/**
+ * Take an exclusive lock on `lockFile` (O_EXCL create), retrying until LOCK_TIMEOUT_MS.
+ * @param {string} lockFile
+ * @returns {number} open file descriptor for the lock
+ */
+function acquireLock(lockFile) {
+  fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+  const start = Date.now();
+  while (Date.now() - start < LOCK_TIMEOUT_MS) {
+    try {
+      return fs.openSync(lockFile, 'wx');
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      reclaimIfStale(lockFile);
+      sleepSync(LOCK_RETRY_MS);
+    }
+  }
+  throw new Error(
+    `Falha ao adquirir lock de ${lockFile} após ${LOCK_TIMEOUT_MS / 1000}s. ` + 'Outro processo pode estar gravando o arquivo de memória.',
+  );
+}
+
+/** Delete a lock left behind by a crashed writer (older than LOCK_STALE_MS). */
+function reclaimIfStale(lockFile) {
+  try {
+    if (Date.now() - fs.statSync(lockFile).mtimeMs > LOCK_STALE_MS) fs.unlinkSync(lockFile);
+  } catch {
+    // Gone already, or not ours to clean up: the retry loop handles both.
+  }
+}
+
+/** Release the lock: close the descriptor and remove the lock file. */
+function releaseLock(fd, lockFile) {
+  try {
+    fs.closeSync(fd);
+  } catch {
+    // Already closed.
+  }
+  try {
+    fs.unlinkSync(lockFile);
+  } catch {
+    // Another writer already reclaimed it as stale.
+  }
+}
+
+// ─── file shape ───
+
+/** The memlog file, from either addressing mode: {workspace}/.memlog.md or an explicit --path. */
+function resolveTarget(args) {
+  return args.path ? path.normalize(args.path) : path.join(args.workspace, MEMLOG);
+}
+
+/**
+ * Return [frontmatter Map in source order, body string]. Frontmatter is plain key: value.
+ * The closing fence is the first line that is *exactly* `---`, so a `---` inside a field
+ * value (topic/goal are free user text) never truncates the frontmatter.
+ * @param {string} text
+ * @returns {[Map<string, string>, string]}
+ */
+function split(text) {
+  const lines = splitLines(text);
+  if (lines.length === 0 || lines[0] !== '---') throw new Error('.memlog.md has no frontmatter');
+  const end = lines.findIndex((line, i) => i >= 1 && line === '---');
+  if (end === -1) throw new Error('.memlog.md frontmatter is not terminated');
+  const meta = new Map();
+  for (const line of lines.slice(1, end)) {
+    const at = line.indexOf(':');
+    if (at === -1) continue;
+    meta.set(line.slice(0, at).trim(), line.slice(at + 1).trim());
+  }
+  return [
+    meta,
+    lines
+      .slice(end + 1)
+      .join('\n')
+      .replace(/^\n+/, ''),
+  ];
+}
+
+/**
+ * Render frontmatter + body back to the file shape.
+ * Newlines in values are neutralized so a multi-line field can't break the fence on re-read.
+ */
+function render(meta, body) {
+  const fm = [...meta].map(([k, v]) => `${k}: ${splitLines(String(v)).join(' ')}`).join('\n');
+  return `---\n${fm}\n---\n\n${body.replace(/\n+$/, '')}\n`;
+}
+
+/** Stamp `updated` and keep it last so the field order stays predictable. */
+function touch(meta) {
+  meta.delete('updated');
+  meta.set('updated', now());
+}
+
+/** Temp + write + fsync + atomic rename, so a crash never half-writes an entry. */
+function writeAtomic(target, text) {
+  const tmp = `${target}.tmp`;
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeFileSync(fd, text, 'utf8');
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, target);
+}
+
+function entryCount(body) {
+  return splitLines(body).filter((line) => line.startsWith('- ')).length;
+}
+
+/** Echo new state so the caller never re-reads the file to know where it stands. */
+function ack(target, body) {
+  process.stdout.write(`${JSON.stringify({ ok: true, memlog: target, entries: entryCount(body) })}\n`);
+}
+
+/** Read and parse the memlog, turning a missing file into a friendly usage error. */
+function readMemlog(target) {
+  let text;
+  try {
+    text = fs.readFileSync(target, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new UsageError(`${target} does not exist; run \`init\` before append/set`);
+    }
+    throw new Error(`failed to read ${target}: ${error.message}`);
+  }
+  return split(text);
+}
+
+// ─── commands ───
+
+class UsageError extends Error {}
+
+function cmdInit(args) {
+  const target = resolveTarget(args);
+  if (fs.existsSync(target)) {
+    throw new UsageError(`${target} already exists; use append/set to update it`);
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const meta = new Map();
+  for (const pair of args.field) {
+    const at = pair.indexOf('=');
+    if (at === -1) throw new UsageError(`--field expects key=value, got '${pair}'`);
+    meta.set(pair.slice(0, at).trim(), pair.slice(at + 1).trim());
+  }
+  touch(meta);
+  writeAtomic(target, render(meta, ''));
+  ack(target, '');
+  return EXIT_OK;
+}
+
+/** Build one entry line: `- (type by who) text`, with the tag omitted when both are absent. */
+function entryLine(args) {
+  const text = args.text.trim().split(/\s+/).filter(Boolean).join(' ');
+  let label = args.type || '';
+  if (args.by) label = `${label} by ${args.by}`.trim(); // attribution: "(idea by user)" / "(by coach)"
+  return `- ${label ? `(${label}) ` : ''}${text}`;
+}
+
+/** Run `mutate(meta, body)` under the lock and write the result atomically. */
+function withLockedMemlog(target, mutate) {
+  const lockFile = `${target}.lock`;
+  const fd = acquireLock(lockFile);
+  try {
+    const [meta, body] = readMemlog(target);
+    const nextBody = mutate(meta, body);
+    touch(meta);
+    writeAtomic(target, render(meta, nextBody));
+    ack(target, nextBody);
+    return EXIT_OK;
+  } finally {
+    releaseLock(fd, lockFile);
+  }
+}
+
+function cmdAppend(args) {
+  const target = resolveTarget(args);
+  return withLockedMemlog(target, (_meta, body) => {
+    const entry = entryLine(args);
+    return body.trim() ? `${body.replace(/\n+$/, '')}\n${entry}` : entry; // always at the end
+  });
+}
+
+function cmdSet(args) {
+  const target = resolveTarget(args);
+  return withLockedMemlog(target, (meta, body) => {
+    meta.set(args.key, args.value);
+    return body;
+  });
+}
+
+// ─── CLI ───
+
+const COMMANDS = {
+  init: { run: cmdInit, flags: { field: 'many' }, required: [] },
+  append: { run: cmdAppend, flags: { text: 'one', type: 'one', by: 'one' }, required: ['text'] },
+  set: { run: cmdSet, flags: { key: 'one', value: 'one' }, required: ['key', 'value'] },
+};
+
+const USAGE = 'usage: memlog.js {init,append,set} (--workspace DIR | --path FILE) [options]';
+
+/**
+ * Parse argv for one subcommand. Throws UsageError on anything argparse would reject.
+ * @param {string[]} argv
+ * @returns {{spec: object, args: object}}
+ */
+function parseArgs(argv) {
+  const [name, ...rest] = argv;
+  const spec = Object.prototype.hasOwnProperty.call(COMMANDS, name) ? COMMANDS[name] : null;
+  if (!spec) throw new UsageError(`invalid choice: '${name ?? ''}' (choose from init, append, set)`);
+  const flags = { workspace: 'one', path: 'one', ...spec.flags };
+  const args = { field: [] };
+  for (let i = 0; i < rest.length; i++) {
+    const key = rest[i].startsWith('--') ? rest[i].slice(2) : null;
+    const kind = key && Object.prototype.hasOwnProperty.call(flags, key) ? flags[key] : null;
+    if (!kind) throw new UsageError(`unrecognized argument: ${rest[i]}`);
+    const value = rest[++i];
+    if (value === undefined) throw new UsageError(`argument --${key}: expected one argument`);
+    if (kind === 'many') args[key].push(value);
+    else args[key] = value;
+  }
+  // Mutually exclusive AND required: exactly one of the two must be present.
+  if (Boolean(args.workspace) === Boolean(args.path)) {
+    throw new UsageError('one of the arguments --workspace --path is required (and not both)');
+  }
+  for (const required of spec.required) {
+    if (args[required] === undefined) throw new UsageError(`the following arguments are required: --${required}`);
+  }
+  return { spec, args };
+}
+
+/**
+ * Entry point. Returns the process exit code instead of throwing, so callers
+ * (tests included) can assert on it.
+ * @param {string[]} argv - argv without node and script
+ * @returns {number}
+ */
+function main(argv) {
+  try {
+    const { spec, args } = parseArgs(argv);
+    return spec.run(args);
+  } catch (error) {
+    if (error instanceof UsageError) {
+      process.stderr.write(`${USAGE}\nerror: ${error.message}\n`);
+      return EXIT_USAGE;
+    }
+    process.stderr.write(`error: ${error.message}\n`);
+    return EXIT_RUNTIME;
+  }
+}
+
+if (require.main === module) {
+  process.exitCode = main(process.argv.slice(2));
+}
+
+module.exports = { main, split, render, entryCount, MEMLOG };