Rewrite ecc-setup-guide.md for ECC v2.0.0: the new `ecc` selective-install
CLI (profiles, auto-update, doctor/repair/plan/catalog/consult), the
skills/ecc + rules/ecc namespaced layout, updated install/model-tier and
Continuous-Learning-v2 sections, and the `--dry-run auto-update` footgun
(it performs a real install). Note 2 of 3 Windows CL-v2 bugs are now fixed
upstream.
Index the guide in README.md and bump the Last updated date.
Clarify the two git-history depth knobs and how to keep indexing fast on
repos with thousands of commits:
- vex history --depth N — query-time walk, per file (caps latency)
- vex index --history-depth N — one-time build, global newest-N (like git log -nN)
Added to the setup example, the .vex.toml history comment, and the command
reference in vex.md.
Step 9 post-merge cleanup is opt-in and easy to miss (session ends after the merge push, manual merge, or interruption). Once PLAN.md is set to Complete, the folder became invisible to the session-start check, so a skipped cleanup orphaned plans/<feature>/ forever.
Add a session-start reconciliation pass in references/resumability-and-abort.md that detects already-merged features whose plan folder still exists (via Status Complete, 'git branch --merged', or a 'Merge feature/<name>' commit) and re-offers the Step 9 cleanup choices. Cross-referenced from SKILL.md (Key Rule #1, workflow-at-a-glance, Step 9 line) and references/final-review-and-merge.md. Rebuilt the feature-planner.skill bundle.
Add a super-intensive, adversarial plan-reviewer agent that runs after the plan
is drafted and BEFORE the approval gate, to catch wasteful or wrong design
before any implementation effort is spent. Verdict can be REDESIGN REQUIRED;
findings are sorted into Critical Gaps (block) vs Suggestions (non-blocking) so
the two never get conflated at the approval gate. It must open the codebase to
verify claims (files exist, "no existing impl" holds, "parallel" phases are
disjoint). Conditional trigger: 4+ phases / Orchestrator / Automated /
security|data-sensitive. Wired into SKILL.md, discovery-and-planning (Step 5.5),
agent-spawning (spawn pattern + opus model profile + cost), and
modes-and-strategies (most valuable in Automated mode, the only human gate).
Review hardening also addressed:
- test-writer derives assertions from acceptance criteria, not the diff, so a
failing test is signal (impl bug) rather than something to "fix" to match
buggy behavior
- early per-phase security/data pass for sensitive phases (not only final review)
- Outstanding Warnings ledger in PLAN.md so non-blocking warnings can't
accumulate invisibly across phases
- Automated-mode global circuit breaker (cost / agent-count cap)
- new `data` domain tag carrying a migration-safety addendum
Bump README Last updated date.
- Re-bench on 2026-05-26 against vex 1.9.1 and ast-index 3.41.0.
- Flag findings that flipped vs the 2026-05-18 snapshot:
- ast-index Python call graph now populated (was empty in 3.27)
- vex implementations now handles generic-parameterized subclasses (v1.7.0)
- vex usages is now AST-precise on T1 languages; ast-index is now the
textual-match tool, inverting the old precision finding
- vex now has diff --base <rev>, making the "only ast-index has
changed --base" finding obsolete
- vex now ships prebuilt Windows binaries; vex self-update works
- Document new vex 1.5 -> 1.9 commands: diff, paths, reachable, check,
bundle (symbol/pr-impact/project), eval, self-update, capabilities.
- Add README entry for the doc; it was previously missing from the index.
- Bump README "Last updated" to 2026-05-26.
Add caveat bullet in the vex section listing known quirks observed during
benchmarking: implementations misses generic-parameterized subclasses,
usages is text-flavored (matches comments/docstrings), Windows install
requires building from source. Recommend cross-checking against ast-index
or Grep for high-stakes queries.
Point-in-time comparison of vex 1.5.0 vs ast-index 3.27.0 on a mixed-language
repo (Python/Kotlin/TS/JS, ~553 files, ~15-17k symbols). Documents:
- Indexing time, footprint, query latency for both tools
- Quality differences on real queries (usages, callers, symbol, semantic)
- Notable findings: ast-index's Python call graph was empty for this repo,
vex's implementations misses generic-parameterized subclasses, vex usages
catches comments/docstrings (text-flavored), ast-index uniquely has
'changed --base <branch>' with no vex equivalent
- Re-run instructions for validating on a different repo or newer versions
Linked from claude-code-tools.md at the end of the vex section so readers
encounter the comparison right after learning about vex. Not surfaced as a
top-level README entry since it's narrower than the other root-level guides.
The vex README already maintains a canonical CLAUDE.md integration
snippet, so embedding it here would duplicate and drift. Instead, link
to upstream and list the five additions worth keeping locally: MCP
server line, skip-vex rule, subagent reminder, auto_update accuracy
fix, and the --semantic ONNX download caveat.
Documents install on macOS/Linux (Homebrew) and Windows (cargo build
from source — no prebuilt Windows binary in v1.5.0). Includes per-project
bootstrap (.vex.toml with semantic + auto_update, vex index) and the
vex-mcp registration at user scope so it covers all projects.
Two real failures hit during notify-bridge v0.8.1 release that section 1
and section 10.1 didn't cover:
1. New section 1.1 — backend pytest in a per-run /tmp/venv. Single-package
ephemeral runners get away with pip install -e into the toolcache;
monorepos on persistent Gitea Act Runners (TrueNAS) hit
"error: uninstall-no-record-file" the second time a broken wheel
install leaks across runs. Venv per run, fresh site-packages, no leak.
2. New section 10.1.1 — pip wheel --no-deps on hatchling has been
observed to produce wheels with METADATA missing the Version field.
importlib.metadata.version() returns None and the UI advertises
0.0.0+unknown. Defense-in-depth: also expose __version__ from
__init__.py and pick the max of (metadata, __version__, source
pyproject) in the resolver. Documented when it's needed and when
section 10.1 alone is fine.
3. New section 14 troubleshooting entry — quotes the exact pip error
message and points at section 1.1 (prevention) and a one-shot
site-packages cleanup recipe (recovery on a stuck runner).
Substantial revision of dolgolyov-git-release-publisher SKILL.md.
New steps:
- Step 2: pre-flight guards (branch, remote sync, duplicate tag, dirty tree)
- Step 4: pre-release checks - detect project type, inspect CI config, run
tests/lint/typecheck/build locally before tagging
- Step 15: post-tag CI watch (link-only or poll until run finishes)
Improvements:
- SSH remote support in Step 1
- Detect prerelease tags separately in Step 3
- NUL-separated git log + BREAKING CHANGE: body scan in Step 5
- Prerelease version bumps (-rc.N / -beta.N / -alpha.N) in Step 8
- Mode A (RELEASE_NOTES.md overwrite) vs Mode B (CHANGELOG.md prepend) in Step 11
- Signed-tag detection in Step 14
New edge cases: redo-after-CI-failure flow, signed tags, tag-already-on-HEAD.
Also updates the one-line description in claude-code-tools.md and bumps
README last-updated date.
The step uses a generic DOCKER_REDEPLOY_WEBHOOK_URL secret and is not
Portainer-specific — any redeploy webhook endpoint works. Rename the step
label, echo line, and warning to reflect the generic nature.
Three separate things sink portable-Python-on-Windows VBS launchers,
all learned from a debugging session where a wled-screen-controller
shortcut silently did nothing:
1. wscript parses .vbs as ANSI — any UTF-8 byte (em-dash, smart quote,
even in a comment) triggers a dialog that lies about the cause:
"Not enough memory resources are available to complete this
operation." It's actually an encoding parse failure.
2. LF line endings parse inconsistently across WSH versions. Always
normalize to CRLF.
3. pythonw.exe has null stdout/stderr; libraries that touch those at
startup (uvicorn, structlog) can crash silently before the first
log line. python.exe with WshShell.Run cmd, 0, False gives real
stream handles attached to a hidden window — same visual result,
reliable startup.
Also added a build-script snippet that normalizes the VBS
automatically so nobody has to remember these rules.
Two cooperating bugs we hit in production caused a Pillow version
mismatch error on in-place upgrades. Documenting both so future
projects do not reproduce them.
- Section 4.3: removed the "delete .py, keep .pyc" snippet (no
compileall step ever ran, so the dist shipped with no .py and no
.pyc — every package's submodules were unimportable). Added a
warning box and the correct compileall -b pattern.
- Section 6: NSIS Core section now shows explicit RMDir /r of payload
dirs before File /r. NSIS File /r is a merge, not a replace, so
upgrades produce half-old/half-new site-packages.
- Section 14: new troubleshooting entry "Pillow / package version
mismatch on upgrade" with the symptom, both root causes, and a
file-state table showing how the mismatch arises.
Bare labels like 'dev' or 'nightly' break pip/setuptools when
stamped into pyproject.toml. Add a regex check that falls back
to 0.0.0.dev0 with a warning, plus a callout explaining the
gotcha.
Describes a workflow_dispatch-triggered build.yml that produces
CI artifacts without creating a Gitea release. Useful for testing
builds before tagging.
Standalone workflow: push v* tag → create Gitea release with
optional RELEASE_NOTES.md. No builds or artifacts — just the
release entry. Links to full CI/CD guide for extensions.
LocalRepos.md stores paths to local repos that should be kept in
sync when CI/CD documentation is updated. Added mandatory rule
to CLAUDE.md to propagate relevant changes.
- Section 10: Single source of truth via pyproject.toml + importlib.metadata,
CI version stamping, Docker build args, updated fallback chain
- Section 11: Release provider abstraction, PEP 440 version normalization,
install type detection, update service pattern, NSIS silent install,
portable ZIP/tarball swap scripts, API endpoints, frontend integration
Document the VBS wrapper approach for launching Windows apps
without console window flash. Update NSIS example to prefer
VBS over direct bat execution.
- Move ECC setup guide reference from README to claude-code-tools.md
- Add CLAUDE.md with mandatory README sync rule
- Add "Last updated" date to README
- README is now a clean index of repo contents
alexei.dolgolyov