wizz-method 1.15.0 → 1.16.1

package/tools/installer/prompts.js

@@ -10,7 +10,6 @@
 let _clack = null;
 let _clackCore = null;
 let _picocolors = null;
-const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
@@ -578,10 +577,6 @@ async function autocomplete(options) {
   return result;
 }
 
-function hasPathSeparator(value) {
-  return value.endsWith('/') || value.endsWith('\\');
-}
-
 function expandHome(input) {
   if (!input) return input;
   if (input === '~') return os.homedir();
@@ -591,91 +586,60 @@ function expandHome(input) {
   return input;
 }
 
-function toDirectoryOption(value, label = value, synthetic = false) {
-  return { value, label, synthetic };
-}
-
-function isExistingDirectory(value) {
-  try {
-    return fs.existsSync(value) && fs.statSync(value).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-function listDirectoryOptions(input, options) {
+/**
+ * Resolve o texto do prompt de diretório para um caminho absoluto.
+ * @param {string} input - Texto submetido
+ * @param {Object} [options] - { cwd, default }
+ * @returns {string} Caminho absoluto
+ */
+function resolveDirectoryInput(input, options = {}) {
   const cwd = options.cwd || process.cwd();
-  const rawInput = input.trim();
-  const expandedInput = expandHome(rawInput);
-  const trailingSep = hasPathSeparator(rawInput) || hasPathSeparator(expandedInput);
-  const resolvedInput = expandedInput ? path.resolve(cwd, expandedInput) : cwd;
-  const browseDir = expandedInput && !trailingSep && !isExistingDirectory(resolvedInput) ? path.dirname(resolvedInput) : resolvedInput;
-  const prefix = expandedInput && browseDir !== resolvedInput ? path.basename(resolvedInput).toLowerCase() : '';
-  const results = [];
-
-  if (!trailingSep && isExistingDirectory(resolvedInput)) {
-    results.push(toDirectoryOption(resolvedInput, `. (use this directory)`));
-  }
-
-  if (isExistingDirectory(browseDir)) {
-    try {
-      for (const entry of fs.readdirSync(browseDir, { withFileTypes: true })) {
-        if (!entry.isDirectory()) continue;
-        if (prefix && !entry.name.toLowerCase().startsWith(prefix)) continue;
-        const fullPath = path.join(browseDir, entry.name);
-        if (!results.some((option) => option.value === fullPath)) {
-          results.push(toDirectoryOption(fullPath));
-        }
-      }
-    } catch {
-      // Skip unreadable directories; validation still reports path issues.
-    }
-  }
-
-  const validation = options.validate?.(rawInput);
-  const hasMatchingOption = results.some((option) => option.value === resolvedInput);
-  if (expandedInput && !validation && !hasMatchingOption) {
-    results.unshift(toDirectoryOption(resolvedInput, `Create/use: ${resolvedInput}`, true));
-  }
-
-  return results;
+  const rawInput = typeof input === 'string' ? input.trim() : '';
+  // Linha vazia significa "usar o default", resolvido do mesmo jeito que texto
+  // digitado, para um default `~/…` ou relativo ainda devolver caminho absoluto.
+  const effective = rawInput || (options.default || '').trim();
+  if (!effective) return cwd;
+  return path.resolve(cwd, expandHome(effective));
 }
 
 /**
- * Directory prompt with autocomplete candidates and create-directory support.
- * Uses @clack/core directly so typed paths that do not exist yet can still be
- * submitted when validation allows creating them.
+ * Directory prompt.
+ *
+ * Entrada de texto simples: o que está na linha é o que é submetido, resolvido
+ * para caminho absoluto.
+ *
+ * A linha vem pré-preenchida com o default (o diretório atual, de onde os
+ * installs costumam ser rodados) como texto editável de verdade, e não como
+ * placeholder, para poder ser encurtada ou estendida em vez de redigitada.
+ * Limpar a linha e apertar Enter ainda aceita o default.
+ *
+ * Substitui uma AutocompletePrompt cuja lista de candidatos era invisível: o
+ * Enter devolvia a opção em foco, não o texto digitado, então dava para instalar
+ * num caminho que o usuário nunca escreveu. Com TextPrompt o defeito some por
+ * construção — não existe seleção escondida que o Enter possa submeter.
+ *
  * @param {Object} options - Prompt options
  * @param {string} options.message - Prompt message
- * @param {string} [options.default] - Default directory
- * @param {string} [options.placeholder] - Placeholder text
+ * @param {string} [options.default] - Default directory, pré-preenchido na linha
+ * @param {string} [options.placeholder] - Placeholder mostrado só se a linha for limpa
  * @param {Function} [options.validate] - Sync validation function
- * @returns {Promise<string>} Selected or typed directory path
+ * @param {Object} [options.input] - Input stream (default process.stdin; testes injetam)
+ * @param {Object} [options.output] - Output stream (default process.stdout; testes injetam)
+ * @returns {Promise<string>} Caminho absoluto do diretório
  */
 async function directory(options) {
   const core = await getClackCore();
   const color = await getPicocolors();
-  const tabCompletion = {
-    prefix: '',
-    index: -1,
-    options: [],
-    lastValue: '',
-  };
 
-  let prompt;
-  prompt = new core.AutocompletePrompt({
+  const prompt = new core.TextPrompt({
+    ...(options.input ? { input: options.input } : {}),
+    ...(options.output ? { output: options.output } : {}),
     initialValue: options.default,
-    options: () => listDirectoryOptions(prompt?.userInput || '', options),
-    filter: () => true,
-    validate: (value) => options.validate?.(value ?? prompt.userInput),
+    defaultValue: options.default,
+    validate: options.validate,
     render() {
-      const title = `${color.gray('◆')}  ${options.message}`;
       const bar = color.gray('│');
-      const barEnd = color.gray('└');
       const userInput = this.userInput;
-      const placeholder = options.placeholder || options.default;
-      const inputDisplay = userInput ? this.userInputWithCursor : `${color.inverse(color.hidden('_'))}${color.dim(placeholder || '')}`;
-      const errorLine = this.state === 'error' ? [`${color.yellow('│')}  ${color.yellow(this.error)}`] : [];
 
       switch (this.state) {
         case 'submit': {
@@ -685,42 +649,20 @@ async function directory(options) {
           return `${color.gray('◇')}  ${options.message}\n${bar}  ${color.strikethrough(color.dim(userInput || ''))}`;
         }
         default: {
-          return [title, `${bar}  ${inputDisplay}`, ...errorLine, barEnd].join('\n');
+          const placeholder = options.placeholder || options.default;
+          const inputDisplay = userInput ? this.userInputWithCursor : `${color.inverse(color.hidden('_'))}${color.dim(placeholder || '')}`;
+          const lines = [`${color.gray('◆')}  ${options.message}`, `${bar}  ${inputDisplay}`];
+          if (this.state === 'error') lines.push(`${color.yellow('│')}  ${color.yellow(this.error)}`);
+          lines.push(color.gray('└'));
+          return lines.join('\n');
         }
       }
     },
   });
 
-  const hasSetUserInput = typeof prompt._setUserInput === 'function';
-  const hasClearUserInput = typeof prompt._clearUserInput === 'function';
-
-  prompt.on('key', (_, key) => {
-    if (key?.name !== 'tab') return;
-    if (!hasSetUserInput) return; // @clack/core API surface changed — skip Tab silently.
-    const currentInput = prompt.userInput;
-    const isContinuingCycle = tabCompletion.lastValue && currentInput === tabCompletion.lastValue;
-    const completionOptions = isContinuingCycle ? tabCompletion.options : prompt.filteredOptions.filter((option) => !option.synthetic);
-    if (completionOptions.length === 0) return;
-
-    if (isContinuingCycle) {
-      tabCompletion.index = (tabCompletion.index + 1) % completionOptions.length;
-    } else {
-      tabCompletion.prefix = currentInput;
-      tabCompletion.options = completionOptions;
-      tabCompletion.index = 0;
-    }
-
-    const focusedOption = completionOptions[tabCompletion.index];
-    if (!focusedOption) return;
-    const completedValue = focusedOption.value;
-    tabCompletion.lastValue = completedValue;
-    if (hasClearUserInput) prompt._clearUserInput();
-    prompt._setUserInput(completedValue, true);
-  });
-
   const result = await prompt.prompt();
   await handleCancel(result);
-  return result;
+  return resolveDirectoryInput(result, options);
 }
 
 /**

package/tools/installer/ui.js

@@ -114,6 +114,45 @@ async function getModuleVersion(moduleCode, { repoUrl = null, registryDefault =
  * UI utilities for the installer
  */
 class UI {
+  /**
+   * Avisa uma vez para cada módulo selecionado que o registry marca como
+   * depreciado.
+   *
+   * Um módulo depreciado nunca é removido da seleção — uma instalação
+   * existente continua funcionando e continua sendo atualizada quando pedido.
+   * O aviso é a única mudança de comportamento, e é ele que informa quem usa
+   * CLI (`--modules`, `--yes`) o que o picker interativo mostra como dica.
+   *
+   * @param {Array<string>} selectedModules - Códigos prestes a ser instalados
+   * @returns {Promise<Array<string>>} Os códigos depreciados que geraram aviso
+   */
+  async _warnDeprecatedModules(selectedModules = []) {
+    const externalManager = new ExternalModuleManager();
+    let registryModules;
+    try {
+      registryModules = await externalManager.listAvailable();
+    } catch {
+      return []; // Registry ilegível — nunca travar uma instalação por causa de um aviso.
+    }
+
+    const deprecatedByCode = new Map();
+    for (const mod of registryModules) {
+      if (!mod.deprecated) continue;
+      deprecatedByCode.set(mod.code, mod);
+      for (const alias of mod.aliases) deprecatedByCode.set(alias, mod);
+    }
+
+    const warned = [];
+    for (const code of selectedModules) {
+      const mod = deprecatedByCode.get(code);
+      if (!mod || warned.includes(mod.code)) continue;
+      warned.push(mod.code);
+      const detail = mod.deprecationMessage || 'It is no longer receiving updates.';
+      await prompts.log.warn(`${mod.name} (${mod.code}) is deprecated. ${detail}`);
+    }
+    return warned;
+  }
+
   async _retainUnavailableInstalledModules(selectedModules, installedModuleIds, wizzDir, options = {}) {
     const { OfficialModules } = require('./modules/official-modules');
     const officialCodes = new Set(['core']);
@@ -274,6 +313,10 @@ class UI {
 
       // Handle quick update separately
       if (actionType === 'quick-update') {
+        // O Quick Update nunca mostra o picker de módulos, então este é o único
+        // ponto em que uma instalação existente de módulo depreciado ouve o aviso.
+        await this._warnDeprecatedModules(existingInstall.moduleIds || []);
+
         return {
           actionType: 'quick-update',
           directory: confirmedDirectory,
@@ -338,6 +381,11 @@ class UI {
           );
         }
 
+        // Mostra os avisos de depreciação para o que acabou selecionado. O picker
+        // interativo só dá a dica na lista de opções, e os caminhos --modules /
+        // --yes nunca veem essa lista.
+        await this._warnDeprecatedModules(selectedModules);
+
         // For existing installs, resolve per-module update decisions BEFORE
         // we clone anything. Reads the existing manifest's recorded channel
         // per module and prompts the user on available upgrades (patch/minor
@@ -423,6 +471,8 @@ class UI {
       selectedModules.unshift('core');
     }
 
+    await this._warnDeprecatedModules(selectedModules);
+
     // Interactive channel gate: "Ready to install (all stable)? [Y/n]"
     // Only shown for fresh installs with no channel flags and an external module
     // selected. Skipped for prerelease launches because channelOptions.global
@@ -1236,25 +1286,32 @@ class UI {
       }
     }
 
-    // Add external registry modules (skip built-in duplicates)
-    const externalRegistryModules = registryModules.filter((mod) => !mod.builtIn && !builtInCodes.has(mod.code));
+    // Add external registry modules (skip built-in duplicates and deprecated
+    // modules that are not already installed — um módulo depreciado continua
+    // visível só para quem já o tem instalado poder seguir gerenciando).
+    const externalRegistryModules = registryModules.filter(
+      (mod) => !mod.builtIn && !builtInCodes.has(mod.code) && (!mod.deprecated || installedModuleIds.has(mod.code)),
+    );
     let externalRegistryEntries = [];
     if (externalRegistryModules.length > 0) {
       const spinner = await prompts.spinner();
       spinner.start('Checking latest module versions...');
 
       externalRegistryEntries = await Promise.all(
-        externalRegistryModules.map(async (mod) => ({
-          code: mod.code,
-          entry: await buildModuleEntry(
+        externalRegistryModules.map(async (mod) => {
+          const entry = await buildModuleEntry(
             mod.code,
             mod.name,
             mod.description,
             mod.defaultSelected,
             mod.url || null,
             mod.defaultChannel || null,
-          ),
-        })),
+          );
+          if (mod.deprecated && mod.deprecationMessage) {
+            entry.hint = entry.hint ? `${entry.hint} — ${mod.deprecationMessage}` : mod.deprecationMessage;
+          }
+          return { code: mod.code, entry };
+        }),
       );
 
       spinner.stop('Checked latest module versions.');

package/wizz-modules.yaml

@@ -17,6 +17,29 @@
 # repo changes owner, disappears, or ships something unexpected.
 # type: experimental — same delegated trust, plus unstable by upstream's
 # own definition.
+#
+# deprecated (optional, default false) — when true, the module is hidden from
+# the installer picker UNLESS it is already installed (so existing users can
+# still see/manage it, but new users are not offered it).
+# deprecation-message (optional) — surfaced in the picker hint for a deprecated
+# module that is still installed; use it to point users to the replacement.
+#
+# marketplace-plugin (optional, default false) — when true, the module's
+# installable skills are resolved from its .claude-plugin/marketplace.json via
+# the plugin resolver (instead of copying the single module-definition dir).
+# Use this for modules whose module.yaml does not sit alongside the skill
+# folders. module-definition should still point at the real module.yaml so
+# config/version lookups work.
+#
+# post-install-message (optional) — an "action needed" notice shown to the user
+# after install completes, once for each install run that includes the module.
+# Interactive installs require the user to acknowledge it (press Enter);
+# non-interactive (--yes) installs print it and continue. Use for required
+# follow-up steps (e.g. "run the X setup skill").
+#
+# aliases (optional) — prior `code` values this module was registered under.
+# An existing install recorded under an alias resolves to this entry instead of
+# being orphaned as "no source available" when the code changes.
 
 modules:
   bmad-method-test-architecture-enterprise:
@@ -41,19 +64,33 @@ modules:
     npmPackage: bmad-builder
     default_channel: stable
 
-  wizz-automator:
-    url: https://github.com/bmad-code-org/wizz-automator
-    module-definition: skills/module.yaml
-    code: automator
-    name: "Wizz Automator Epic Builder Experimental"
-    description: "EXPERIMENTAL: only supports claude and codex currently"
+  bmad-loop:
+    url: https://github.com/bmad-code-org/bmad-loop
+    module-definition: src/bmad_loop/data/skills/bmad-loop-setup/assets/module.yaml
+    code: bmad-loop
+    # bauto é o código pré-rename (o módulo era bmad-auto antes do repo e do
+    # conteúdo serem renomeados para bmad-loop); mantém instalações em bauto
+    # migrando para a frente em vez de virarem órfãs.
+    aliases: [bauto]
+    name: "Wizz Loop"
+    description: "Builds, verifies, and retros a whole epic unattended"
     defaultSelected: false
-    type: experimental
-    npmPackage: bmad-story-automator
-    default_channel: next
+    type: upstream-org
+    default_channel: stable
+    # As skills vivem fora de um diretório único de module.yaml; resolve pelo
+    # .claude-plugin/marketplace.json via plugin resolver (ver external-manager).
+    marketplace-plugin: true
+    post-install-message: |
+      Wizz Loop installed. To finish setup, run the bmad-loop-setup skill
+      from your agent:
+
+        > use the bmad-loop-setup skill
+
+      It installs the bmad-loop orchestrator tool and wires up the per-project
+      hooks and policy. The automation skills don't run until setup completes.
 
   bmad-creative-intelligence-suite:
-    url: https://github.com/bmad-code-org/wizz-module-creative-intelligence-suite
+    url: https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite
     module-definition: src/module.yaml
     code: cis
     name: "Wizz Creative Intelligence Suite"
@@ -64,7 +101,7 @@ modules:
     default_channel: stable
 
   bmad-game-dev-studio:
-    url: https://github.com/bmad-code-org/wizz-module-game-dev-studio.git
+    url: https://github.com/bmad-code-org/bmad-module-game-dev-studio.git
     module-definition: src/module.yaml
     code: gds
     name: "Wizz Game Dev Studio"
@@ -74,6 +111,21 @@ modules:
     npmPackage: bmad-game-dev-studio
     default_channel: stable
 
+  # --- Deprecated: hidden from the picker unless already installed ---
+
+  wizz-automator:
+    url: https://github.com/bmad-code-org/bmad-automator
+    module-definition: skills/module.yaml
+    code: automator
+    name: "Wizz Automator Epic Builder Experimental"
+    description: "EXPERIMENTAL: only supports claude and codex currently"
+    defaultSelected: false
+    type: experimental
+    npmPackage: bmad-story-automator
+    default_channel: next
+    deprecated: true
+    deprecation-message: "Wizz Automator has been deprecated and is replaced by Wizz Loop (bmad-loop). Install Wizz Loop instead."
+
   bmad-method-wds-expansion:
     url: https://github.com/bmad-code-org/bmad-method-wds-expansion
     module-definition: src/module.yaml
@@ -85,3 +137,5 @@ modules:
     type: upstream-org
     npmPackage: bmad-wds
     default_channel: stable
+    deprecated: true
+    deprecation-message: "Whiteport Design Studio is no longer receiving updates. Its capabilities are being folded into the bmm module as enhanced UX features. Your existing install is kept as-is."

package/src/bmm-skills/4-implementation/wizz-sprint-planning/checklist.md

@@ -1,34 +0,0 @@
-# Sprint Planning Validation Checklist
-
-## Core Validation
-
-### Complete Coverage Check
-
-- [ ] Every epic found in epic\*.md files appears in sprint-status.yaml
-- [ ] Every story found in epic\*.md files appears in sprint-status.yaml
-- [ ] Every epic has a corresponding retrospective entry
-- [ ] No development_status items in sprint-status.yaml that don't exist in epic files
-- [ ] action_items section (if it existed) carried over unchanged
-
-### Parsing Verification
-
-Compare epic files against generated sprint-status.yaml:
-
-```
-Epic Files Contains:                Sprint Status Contains:
-✓ Epic 1                            ✓ epic-1: [status]
-  ✓ Story 1.1: User Auth              ✓ 1-1-user-auth: [status]
-  ✓ Story 1.2: Account Mgmt           ✓ 1-2-account-mgmt: [status]
-  ✓ Story 1.3: Plant Naming           ✓ 1-3-plant-naming: [status]
-                                      ✓ epic-1-retrospective: [status]
-✓ Epic 2                            ✓ epic-2: [status]
-  ✓ Story 2.1: Personality Model      ✓ 2-1-personality-model: [status]
-  ✓ Story 2.2: Chat Interface         ✓ 2-2-chat-interface: [status]
-                                      ✓ epic-2-retrospective: [status]
-```
-
-### Final Check
-
-- [ ] Total count of epics matches
-- [ ] Total count of stories matches
-- [ ] All items are in the expected order (epic, stories, retrospective)

package/src/core-skills/wizz-brainstorming/scripts/memlog.py

@@ -1,202 +0,0 @@
-#!/usr/bin/env python3
-# /// script
-# requires-python = ">=3.10"
-# ///
-"""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.
-
-Two invariants make it trustworthy:
-
-  1. Append-only, chronological. Entries land at the end, in the order they happen.
-     Nothing is ever inserted backward, reordered, or grouped.
-  2. Write-only / blind. Every command is an atomic, context-free write and echoes the
-     new state as 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.
-
-The file shape (.memlog.md):
-
-    ---
-    topic: Onboarding flow for a budgeting app
-    goal: lift week-1 retention
-    status: active
-    updated: 2026-05-30T14: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
-    - (idea) auto-import one bank account so the first screen shows real numbers
-    - (question) is open-banking consent too heavy for step one?
-    - (technique) started Six Thinking Hats
-    - (idea) black-hat: imported transactions look scary before they're categorized
-    - (insight) the "scary numbers" risk and the "real numbers" idea are one lever: show real data, pre-categorized
-    - (direction) user wants to optimize for the anxious first-timer, not the power user
-    - (decision) lead with one pre-categorized account; defer multi-account import
-
-Each entry may carry an optional `--type` — what KIND it is (idea, insight, question,
-decision, technique, …) — and an optional `--by` naming who it came from (e.g. `user`,
-`coach`), for sessions where authorship matters. 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.
-
-Commands:
-  init   --workspace DIR [--field k=v ...]              create the memlog (errors if it exists)
-  append --workspace DIR --text STR [--type T] [--by W]  append one entry at the end
-  set    --workspace DIR --key K --value V              set/replace a frontmatter field
-
-The workspace is the run folder; the memlog is always {workspace}/.memlog.md.
-"""
-import argparse
-import json
-import os
-import sys
-from datetime import datetime
-from pathlib import Path
-
-MEMLOG = ".memlog.md"
-
-
-def now() -> str:
-    return datetime.now().strftime("%Y-%m-%dT%H:%M")
-
-
-def memlog_path(workspace: str) -> Path:
-    return Path(workspace) / MEMLOG
-
-
-def split(text: str) -> tuple[dict, str]:
-    """Return (frontmatter dict in source order, body str). 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.
-    """
-    lines = text.splitlines()
-    if not lines or lines[0] != "---":
-        raise ValueError(".memlog.md has no frontmatter")
-    end = next((i for i in range(1, len(lines)) if lines[i] == "---"), None)
-    if end is None:
-        raise ValueError(".memlog.md frontmatter is not terminated")
-    meta: dict[str, str] = {}
-    for line in lines[1:end]:
-        if ":" in line:
-            k, v = line.split(":", 1)
-            meta[k.strip()] = v.strip()
-    return meta, "\n".join(lines[end + 1:]).lstrip("\n")
-
-
-def render(meta: dict, body: str) -> str:
-    # Neutralize newlines in values so a multi-line field can't break the fence on re-read.
-    fm = "\n".join(f"{k}: {' '.join(str(v).splitlines())}" for k, v in meta.items())
-    return "---\n" + fm + "\n---\n\n" + body.rstrip("\n") + "\n"
-
-
-def touch(meta: dict) -> None:
-    """Stamp `updated` and keep it last so the field order stays predictable."""
-    meta.pop("updated", None)
-    meta["updated"] = now()
-
-
-def write_atomic(path: Path, text: str) -> None:
-    tmp = path.with_suffix(path.suffix + ".tmp")
-    tmp.write_text(text, encoding="utf-8")
-    os.replace(tmp, path)
-
-
-def entry_count(body: str) -> int:
-    return sum(1 for ln in body.splitlines() if ln.startswith("- "))
-
-
-def ack(path: Path, meta: dict, body: str) -> None:
-    """Echo new state so the caller never re-reads the file to know where it stands."""
-    print(json.dumps({
-        "ok": True,
-        "memlog": str(path),
-        "status": meta.get("status", ""),
-        "entries": entry_count(body),
-    }))
-
-
-def cmd_init(args) -> int:
-    path = memlog_path(args.workspace)
-    if path.exists():
-        print(f"error: {path} already exists; use append/set to update it", file=sys.stderr)
-        return 2
-    path.parent.mkdir(parents=True, exist_ok=True)
-    meta: dict[str, str] = {}
-    for pair in args.field or []:
-        if "=" not in pair:
-            print(f"error: --field expects key=value, got {pair!r}", file=sys.stderr)
-            return 2
-        k, v = pair.split("=", 1)
-        meta[k.strip()] = v.strip()
-    meta.setdefault("status", "active")
-    touch(meta)
-    write_atomic(path, render(meta, ""))
-    ack(path, meta, "")
-    return 0
-
-
-def cmd_append(args) -> int:
-    path = memlog_path(args.workspace)
-    meta, body = split(path.read_text(encoding="utf-8"))
-    text = " ".join(args.text.split())  # collapse newlines/runs → one-line entry, no prose bloat
-    label = args.type or ""
-    if args.by:
-        label = f"{label} by {args.by}".strip()  # attribution: "(idea by user)" / "(by coach)"
-    tag = f"({label}) " if label else ""
-    entry = f"- {tag}{text}"
-    body = (body.rstrip("\n") + "\n" + entry) if body.strip() else entry  # always at the end
-    touch(meta)
-    write_atomic(path, render(meta, body))
-    ack(path, meta, body)
-    return 0
-
-
-def cmd_set(args) -> int:
-    path = memlog_path(args.workspace)
-    meta, body = split(path.read_text(encoding="utf-8"))
-    meta[args.key] = args.value
-    touch(meta)
-    write_atomic(path, render(meta, body))
-    ack(path, meta, body)
-    return 0
-
-
-def main(argv: list[str] | None = None) -> int:
-    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    sub = p.add_subparsers(dest="cmd", required=True)
-
-    pi = sub.add_parser("init", help="create the memlog")
-    pi.add_argument("--workspace", required=True)
-    pi.add_argument("--field", action="append", metavar="KEY=VALUE", help="frontmatter field (repeatable)")
-    pi.set_defaults(func=cmd_init)
-
-    pa = sub.add_parser("append", help="append one entry at the end")
-    pa.add_argument("--workspace", required=True)
-    pa.add_argument("--text", required=True)
-    pa.add_argument("--type", help="entry kind, rendered as an inline tag")
-    pa.add_argument("--by", help="who the entry came from (e.g. user, coach); rendered into the tag")
-    pa.set_defaults(func=cmd_append)
-
-    pset = sub.add_parser("set", help="set a frontmatter field")
-    pset.add_argument("--workspace", required=True)
-    pset.add_argument("--key", required=True)
-    pset.add_argument("--value", required=True)
-    pset.set_defaults(func=cmd_set)
-
-    args = p.parse_args(argv)
-    return args.func(args)
-
-
-if __name__ == "__main__":
-    sys.exit(main())