liteagents 2.15.3 → 2.17.1

package/CHANGELOG.md

@@ -15,6 +15,205 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Enhanced testing capabilities
 - Performance optimizations
 
+## [2.17.1] - 2026-08-25
+
+### Fixed
+- **`AGENT_RULES.md`'s table of contents linked to an anchor that does not exist** in the
+  droid, opencode and ampcode kits. Entry 9 pointed at `#claudemd-stub` while the heading it
+  names is `## AGENTS.md Stub` / `## AGENT.md Stub` — anchors `#agentsmd-stub` /
+  `#agentmd-stub`. The per-tool rename substituted the visible heading text and the link
+  label and left the anchor on the claude spelling, so the link was dead in three of four
+  kits. Claude's was correct and is untouched. Cosmetic, but it is the mention-form this repo
+  already has a rule about: a rename sweep must cover every form, and an anchor is one. Every
+  TOC anchor in all four copies was audited against every heading; this was the only
+  mismatch. Found while diffing the agentic-toolkit mirror, which carried the correct anchor
+  and the *wrong* settings path — each side right about a different line.
+
+## [2.17.0] - 2026-08-24
+
+### Added
+- **docs-builder v3 — the model sorts a corpus into four buckets, behind an approval gate.**
+  v2 could only move a file a mechanical rule already recognised; everything else stayed put.
+  v3 has `discover` *propose* a bucket per file (`product` / `logs` / `archive`, with
+  `oversized` as a separate boolean flag, not a bucket) and stop — a classification interview
+  fills in `bucket`, and only then does `apply-reorg` move anything. The risk was never the
+  model's judgement, it was a silent move; so the gate is the fix, not a better heuristic.
+  `reconcile`, `due` and `archive-cleanup` folded into the `reorg` front door — `due`'s output
+  contract is preserved because `/remember` step 7 reads it.
+- **`cleanup <file>` — splitting is opt-in and per-file.** It measures, prints the cost, and
+  stops for an interview; `cleanup-apply` runs only after `labels.json` exists with exactly
+  one `core:true` theme. The core page keeps the original basename and lands back in the
+  original document's own directory; only non-core theme pages stay under `docs/wiki/`. The
+  original is always archived byte-identical (sha verified before and after), never edited.
+- **`search`** — zero-dependency BM25 over the corpus. Measured against reading the split
+  corpus whole on real data: a **tie** (~73K tokens either way), so splitting is justified by
+  recall, not by cost — the README says so rather than implying a saving that isn't there.
+- **The first behavioural test suite this tool has ever had** — 472 tests in throwaway git
+  repos, including negative controls that assert the gates can actually fail. It was written
+  after four rounds of hand-found bugs kept recurring with nothing in the repo able to catch
+  them. `tests/run-all-tests.js` now treats `expectedTests` as an enforced floor: a breach
+  exits 1 (it used to print the number and pass regardless).
+
+### Fixed
+- **One chokepoint for a doc move, and all three of its guards now live there.** `moveDoc` is
+  the single path a doc changes location through. Three defects, each reproduced against the
+  shipped script before being fixed: a plan row containing `../` could move — and **delete** —
+  a file from outside the repo via the copy+unlink fallback; `archive README.md` archived the
+  README because `PROTECTED_NAMES` was enforced at two call sites but not at the chokepoint;
+  and `cleanup-apply` died mid-split because `archive()` called `process.exit(2)` on a
+  follow-up failure while running in-process, leaving the original archived, the core page
+  stranded, and no index — silently. Path confinement and the protected-name check now sit in
+  `doArchive`; `archive` split into `archiveOrThrow` plus a CLI wrapper.
+- **One index.** The themed per-split index used to write the same path as the whole-corpus
+  map: on a real corpus a split's index step overwrote a 37-row map with its own 7 rows, and
+  the file still claimed completeness. `index-flat` is now the sole writer of `docs/index.md`;
+  the themed variant was removed outright.
+- **`FROZEN` dropped from the archive trigger words** — on a real 37-file corpus it caused
+  ~10 of 12 archive calls to be false positives, because in that corpus `FROZEN` means
+  "locked, still current". Precision over recall, with no replacement heuristic.
+- **Relative links are rewritten when a file moves**, fence-aware *and* inline-code-span-aware
+  for the relative passes (a `` `map[key](arg)` `` span was being corrupted into a link), and
+  inbound-link repair now covers untracked-but-not-ignored files — a split's brand-new pages
+  were invisible to it before.
+- **The commit advisory prints one recipe per run that actually runs.** It used to name files
+  at their pre-move paths (`git add` is atomic — one stale pathspec exits 128 and stages
+  *nothing*), print once per internal step, and omit files the run itself generated, including
+  `docs/log.md`. Found on a cold field run where the operator quietly hand-repaired it.
+- **`/remember`: one conversation counts once.** A fork or resume writes the same conversation
+  to several session files, and the ledger was counting files — an antigen rendered "3
+  sessions" that was really one conversation. Sessions are now unioned on shared message
+  uuids (`sessions` is authoritative; `session_ids` is evidence), reactions deduped on
+  (conversation, anchor timestamp, anchor signal), and the scan restricted to anchor-bearing
+  sessions — 84.1s → 53.0s per run on the real corpus with identical clustering.
+- **`/remember`: the ledger seeds only on recurrence.** New entries are minted at `sessions
+  >= 2`; three prior runs had produced 30 / 0 / 10 singleton entries. Quiet runs now also run
+  the length-gate check before the "nothing to consolidate" exit, and that gate's exemption is
+  mechanical (a >100-char backtick literal) rather than a judgement call the model could talk
+  itself past.
+- **`friction.cjs` skips task-notification blocks** in both signal detection and context
+  capture — their boilerplate was matching as false curses/corrections — and warns on stderr
+  when a uuid's fan-out exceeds the cap instead of dropping the union silently.
+
+### Changed
+- **`/remember` now compresses hot memory instead of accumulating it.** `MEMORY.md` is loaded
+  into every session, so its size is the cost that matters — and both Facts and Episodes were
+  append-only, so it only ever grew. Four changes, all in the command spec (no script):
+  - **Facts are rewritten every run, not appended to.** The merge step returns the whole
+    section rewritten — new replaces old, near-duplicates fold into one line, and anything
+    that can be shorter is made shorter. A fact is now **one line, ≤160 chars, stating a rule
+    that changes future behaviour**: current truth only, no version history, no `supersedes`,
+    no narrative. Events belong in episodes. Nothing is pruned on age — an old rule that still
+    holds must never be dropped for being old; the bar sits at *entrance*, not on a timer.
+  - **Episodes keep the 10 most recent; older ones are folded, then deleted.** An aging
+    episode's *lesson* is handed to the fact rewrite, then the narrative is removed. No
+    archive file: git holds the history, and a file that is never loaded is not memory.
+  - **Stashes are batched, ≤5 per agent, using as few agents as possible.** One agent reading
+    several sessions sees a lesson recur and writes it once; one agent per stash writes it
+    once per stash and leaves the merge to catch the duplicates. Fewer agents, better
+    extraction, less to dedup downstream.
+  - **A mechanical length check runs in the report** — a one-line `awk` naming every fact over
+    the cap. It reports; it never fails the run and never hand-edits. Counting is a script's
+    job, compression is the model's: on this project model-driven bookkeeping measured **27%**
+    reliable against **~100%** for the same work done mechanically.
+
+  Measured on this toolkit's own bareloop corpus: `MEMORY.md` **168 KB → 48 KB** — 348 facts
+  averaging 254 chars became 249 averaging ~130, and 73 episodes became 10. Roughly **30k
+  tokens off every session** in that project. Antigens and the 10 retained episodes came
+  through byte-identical.
+
+  Mirrored across all four packages; `docs/product/remember-README.md` updated to match.
+
+## [2.16.0] - 2026-08-22
+
+### Added
+- **`/docs-builder` with no argument now asks instead of guessing.** It runs `due` for
+  context, then offers exactly three options via `AskUserQuestion` — **First run** (sort the
+  whole corpus, then split what's too big), **Docs drift** (rebuild index, re-run lint,
+  nothing moves), **Clean archive** (destructive prune). Passing an argument skips the
+  question, so the flow stays scriptable. Same explicit-over-auto-detect call `live-canvas`
+  made: the three modes differ in cost and destructiveness, so a wrong guess is expensive in
+  one direction and irreversible in the other. "First run" carries two stops — one guarding
+  correctness (review the classification before anything is `git mv`'d), one guarding cost
+  (see the oversized list and its price before any split runs).
+- **docs-builder v2** — rebuilt so the *script* does the bookkeeping and the model does only
+  synthesis. New `docs-builder.cjs` with `scan`/`propose`/`assign`/`validate`/`plan`/`write`/
+  `index`/`search`/`archive`/`lint`/`ledger`/`due` subcommands, plus **Mode 0 reorg**
+  (`discover` / `apply-reorg`) that classifies a whole corpus into product / archive /
+  oversized instead of one file at a time.
+- **`/remember` step 7 — docs reconcile check (detect only).** Runs `docs-builder.cjs due`,
+  crash-isolated like the friction step; nudges at >=5 changed docs and never edits a page.
+  Now present in all four packages.
+- **`search`** — BM25 ranking over the doc corpus, with `N` result clamping.
+
+### Changed
+- **docs-builder moved from a Claude skill to a Claude command** — Claude Code is now
+  11 subagents + **8 skills + 10 commands** (was 9 + 9). The other three tools keep 18
+  commands; only the docs-builder entry's description and usage changed.
+- **docs-builder v2 mirrored to droid / opencode / ampcode.** `docs-builder.cjs` hardcodes
+  no tool paths, so it is byte-identical across all four packages; only the command doc's
+  config-file reference differs. (`friction.cjs`, by contrast, does hardcode tool paths and
+  stays per-package.)
+- **Per-tool config filename swept through the non-Claude packages.** `CLAUDE.md` ->
+  `AGENT.md` (ampcode) / `AGENTS.md` (droid, opencode) in the `quality-assurance` agent, the
+  `context-builder` catalog row, the `AGENT_RULES.md` stub section, and `friction.cjs`'s
+  recommendation output. The `docs-builder` never-move list still names all three on purpose
+  — the code protects every variant regardless of which tool is running.
+- Removed the stale v1 `docs-builder/templates.md` from the three non-Claude packages.
+
+### Fixed
+- **Reorg could move files it promised never to move.** The never-move list is now enforced
+  in code (`PROTECTED_NAMES`), matched at **any depth** rather than only at the top of
+  `docs/`: `README.md`, `index.md`, `log.md`, `CHANGELOG.md`, `LICENSE.md`,
+  `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `CLAUDE.md`, `AGENTS.md`,
+  `AGENT.md`. Previously a `README.md` one directory down was a move candidate.
+- **Reorg walked into dot-dirs and `node_modules/`.** `walkMd` now skips every dot-dir
+  (`.git/`, `.github/`, `.claude/`, `.factory/`, `.opencode/`, `.amp/`, `.docs-builder/`)
+  and `node_modules/`, matching what the command doc already claimed.
+- **`REPO` vs cwd path split (8 fixes).** `rewriteArchivedPath`, `checkCitations`' tasks dir,
+  `failures.json`, and `applyReorg`'s plan path all resolved against `REPO` while their
+  writers wrote cwd-relative. Running from outside the repo silently no-opped the archive
+  key-sync, LOUD-SKIPped the citations gate (so `validate` returned PASS on bad citations),
+  split the failure ledger across two directories, and made `apply-reorg` die right after a
+  successful `discover`. All now resolve cwd-relative.
+- `logOp` creates `docs/` before appending to `log.md` (was ENOENT, masked only by call order).
+- `bm25Rank` skips and warns on a missing source file instead of dying with a raw ENOENT.
+- `search` clamps `N` to a positive integer (`N=-3` silently dropped the last 3 results).
+- `friction.js` -> `friction.cjs` in all four packages — a `.js` file fails to load via
+  `require()` in any repo whose `package.json` declares `"type": "module"`.
+- Command-doc examples for `validate`, `plan`, and `search` now include `REPO=<repo>`.
+- **`/docs-builder` showed no argument hint.** Its frontmatter had `usage:` but not
+  `argument-hint:` — the key Claude Code actually renders — and no `allowed-tools:`, while
+  every sibling command had both. Added in all four packages, with `AskUserQuestion` in the
+  tool list so the new mode picker can run.
+- **`/docs-builder` did not load on opencode at all.** `opencode.jsonc` registered it as
+  `./command/docs-builder/SKILL.md` — a path that never existed in that package (opencode
+  uses a flat `docs-builder.md`, like every other command). Now points at the real file, with
+  the v2 description.
+- Removed a stale `subagent-spawning` entry from `opencode.jsonc` — the command file was
+  deleted long ago but stayed registered. opencode.jsonc now registers exactly the 18
+  commands and 11 agents that exist on disk.
+- `AGENT_RULES.md` footer pointed at `.claude/memory/AGENT_RULES.md`, a location that no
+  longer exists (the dir was renamed to `remember/`). Now the correct per-tool path in each
+  package. Only affects newly bootstrapped copies — an existing project-local
+  `AGENT_RULES.md` is user-owned and never overwritten.
+
+### Removed
+- **Guardrails section dropped from `AGENT_RULES.md`** (all four packages). It documented a
+  `PreToolUse` hook and pointed at `.claude/hooks/guardrails.py` as "ships in this repo" —
+  the file never shipped here. The section was also Claude-Code-only: droid, opencode, and
+  ampcode have no hook system, so it was unusable guidance in three of four packages. The
+  Always / Ask / Never rules it justified stay, restated as binding prose plus a pointer to
+  mirror them into whatever allow/ask/deny list your tool provides.
+
+### Documentation
+- `subagentic-manual.md` catalog corrected — it claimed Ampcode shipped a `skills/` directory
+  (it does not) and under-counted Droid/OpenCode at 17 commands. All four platforms ship
+  11 subagents; only Claude Code splits capabilities into skills + commands.
+- `package.json` description 17 -> 18 commands (drives the installer banner), root
+  `CLAUDE.md` 20 -> 18.
+
+---
+
 ## [2.15.3] - 2026-08-04
 
 ### Security

package/README.md

@@ -45,7 +45,7 @@ liteagents
 
 ### Supported Tools
 
-- **Claude Code** - 11 subagents + 9 skills + 9 commands (+ optional live-canvas channel plugin)
+- **Claude Code** - 11 subagents + 8 skills + 10 commands (+ optional live-canvas channel plugin)
 - **Opencode** - 11 agent references + 18 commands
 - **Ampcode** - 11 subagents + 18 commands
 - **Droid** - 11 agent references + 18 commands
@@ -135,14 +135,14 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 
 *Hot Memory Pipeline (2)* — see the [Hot Memory](#hot-memory--project-local-learning-from-your-own-sessions) section above for the full walkthrough:
 - **stash** - Snapshot session context to `.claude/stash/` before compaction, handoff, or ending complex work
-- **remember** - Consolidate stashes + friction antigens into `.claude/remember/MEMORY.md`; auto-injected via `@MEMORY.md`
+- **remember** - Consolidate stashes + friction antigens into `.claude/remember/MEMORY.md`; auto-injected via `@.claude/remember/MEMORY.md`
 
 *Design*:
 - **live-canvas** - Design UI variations with click-to-annotate feedback in the browser; ships a companion MCP channel plugin for Claude Code so Saves stream into the session in real time. Other tools use batch mode.
 
 *Workflow & analysis*:
 - **brainstorming** - Structured brainstorming sessions
-- **docs-builder** - Project documentation generation
+- **docs-builder** - Reorg a docs corpus, split an oversized doc, search it, keep pages current, index them
 - **trace-back** - Trace bugs backward through call stack
 - **skill-creator** - Guide for creating new skills
 - **debug-method** - Four-phase debugging framework
@@ -162,9 +162,10 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 
 | Document | Description |
 |----------|-------------|
-| **[INSTALLER_GUIDE.md](docs/INSTALLER_GUIDE.md)** | Complete installation guide, troubleshooting, and FAQ |
+| **[INSTALLER_GUIDE.md](docs/product/INSTALLER_GUIDE.md)** | Complete installation guide, troubleshooting, and FAQ |
 | **[subagentic-manual.md](packages/subagentic-manual.md)** | Detailed agent/command reference |
-| **[remember-README.md](docs/remember-README.md)** | How hot memory works — the `/stash` → `/remember` pipeline, the friction sensor, and the antigen ledger |
+| **[remember-README.md](docs/product/remember-README.md)** | How hot memory works — the `/stash` → `/remember` pipeline, the friction sensor, and the antigen ledger |
+| **[docs-builder-README.md](docs/product/docs-builder-README.md)** | How `/docs-builder` works — the reorg/cleanup modes, what it measurably costs, and the ledger that tracks doc drift |
 
 ---
 
@@ -198,7 +199,7 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 ## Stats
 
 - **11** Specialized Agents
-- **22** Workflow Commands & Skills
+- **18** Workflow Commands & Skills
 - **4** Supported Tools (Claude, Opencode, Ampcode, Droid)
 - **Apache-2.0** License
 
@@ -218,4 +219,4 @@ Apache-2.0 © 2026 hamr0 — see [LICENSE](LICENSE).
 
 ---
 
-**Need help?** See the [Installer Guide](docs/INSTALLER_GUIDE.md) or [open an issue](https://github.com/hamr0/liteagents/issues)
+**Need help?** See the [Installer Guide](docs/product/INSTALLER_GUIDE.md) or [open an issue](https://github.com/hamr0/liteagents/issues)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "liteagents",
-  "version": "2.15.3",
-  "description": "AI development toolkit with 11 specialized agents and 17 commands including live-canvas UI design with click-to-annotate feedback. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
+  "version": "2.17.1",
+  "description": "AI development toolkit with 11 specialized agents and 18 commands including live-canvas UI design with click-to-annotate feedback. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
   "main": "index.js",
   "bin": {
     "liteagents": "./installer/cli.js",

package/packages/ampcode/AGENT.md

@@ -14,7 +14,7 @@ These subagents are available when using Ampcode CLI.
 | 2-generate-tasks | 2-Generate Tasks | Detailed Planning - use to break down the PRD into a granular, actionable task list |
 | 3-process-task-list | 3-Process Task List | Iterative Implementation - use to guide the AI to tackle one task at a time, allowing you to review and approve each change |
 | code-developer | Full Stack Developer | Use for code implementation, debugging, refactoring, and development best practices |
-| context-builder | Context Initializer | Use to initialize project context for new/existing projects, discover and organize documentation, create CLAUDE.md and KNOWLEDGE_BASE.md for optimal token-efficient memory |
+| context-builder | Context Initializer | Use to initialize project context for new/existing projects, discover and organize documentation, create AGENT.md and KNOWLEDGE_BASE.md for optimal token-efficient memory |
 | feature-planner | Product Manager | Use for creating epics and user stories, prioritization, backlog navigation, story refinement, and retrospectives |
 | market-researcher | Business Analyst | Use for market research, brainstorming, competitive analysis, project briefs, and initial project discovery |
 | orchestrator | Master Orchestrator | Use for workflow coordination, multi-agent tasks, role switching guidance, and when unsure which specialist to consult |
@@ -27,7 +27,7 @@ These subagents are available when using Ampcode CLI.
 | ID | Description | Usage | Auto |
 |---|---|---|---|
 | brainstorming | Refines rough ideas into fully-formed designs through collaborative questioning | /brainstorming <session-type> <topic> | false |
-| docs-builder | Create comprehensive project documentation with structured /docs hierarchy | /docs-builder | false |
+| docs-builder | Reorg a docs corpus, split an oversized doc, search it, keep pages current, index them | /docs-builder [reorg \| cleanup <file.md>] | false |
 | live-canvas | Design UI variations and collect click-to-annotate feedback from the browser (batch mode only on Amp) | /live-canvas | false |
 | trace-back | Systematically traces bugs backward through call stack to identify source | /trace-back <issue-description> | false |
 | skill-creator | Guide for creating effective skills and extending Claude capabilities | /skill-creator <skill-type> <skill-description> | false |

package/packages/ampcode/agents/quality-assurance.md

@@ -58,7 +58,7 @@ digraph QualityAssurance {
 ## Project Discovery
 
 Before any analysis, read (if exists):
-- `CLAUDE.md` - Project instructions, patterns, conventions
+- `AGENT.md` - Project instructions, patterns, conventions
 - `AGENT.md` / `AGENTS.md` - Agent configurations
 - `README.md` - Project overview
 - Test config files (`jest.config`, `pytest.ini`, etc.)