External/ECC
1
0
Fork 0
mirror of https://github.com/affaan-m/ECC.git synced 2026-09-08 07:37:48 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into maint/pr-2871-current

Browse Source
This commit is contained in:
haelyra
2026-08-28 16:02:33 -04:00
parent 60e27fe51e 5eddf1a3ff
commit 00b9aacce4
70 changed files with 3215 additions and 302 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ANTIGRAVITY-GUIDE.md
+10 -8
View File
@@ -8,16 +8,18 @@ Native Antigravity 2.0 installation requires ECC 2.2.0 or newer. ECC 2.1.0 uses
the legacy `.agent/` adapter and does not provide the native layout described
below.
> [!IMPORTANT]
> **Temporary release status:** npm latest is currently `ecc-universal@2.1.0`.
> ECC 2.2.0 has not been published to npm yet. Until it is published, use a
> current source checkout of `main` for native `.agents` support or wait for the
> release.
<!-- Temporary: remove this release-status paragraph only after `ecc-universal@2.2.0` is published and registry readback succeeds. -->
## Quick start
Verify that 2.2.0 is readable from the registry, then run the pinned package
from the project you want to configure:
```bash
npm view ecc-universal version
npx ecc-universal@2.2.0 install --profile minimal --target antigravity
```
### Source checkout alternative
```bash
# Run every command below from the project you want to configure.
# Keep the ECC source checkout separate and use its absolute path.
docs/releases/2.2.0/launch-runbook.md
+133
View File
@@ -0,0 +1,133 @@
# ECC 2.2 launch and rollback runbook
Affaan is the only release operator for ECC 2.2. Everyone else may prepare,
review, and verify the release candidate, but must not merge the release PR,
create or push `v2.2.0`, change npm dist-tags, or publish the GitHub Release.
## Availability model
The default npm install remains `ecc-universal@2.1.0` until the final promotion
step succeeds. The release workflow publishes 2.2.0 under the `staged` tag,
reads its registry integrity back, compares those bytes with the exact archive
that passed the three-platform lifecycle, and only then moves `latest` to
2.2.0. There is no interval where `latest` points at an unpublished version.
The native Claude marketplace install remains an independent install path
throughout the npm rollout:
```text
/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc
```
Never unpublish 2.1.0 or 2.2.0. npm dist-tags provide the reversible switch.
## Current fallback baseline
Before merge, confirm all of these:
```bash
npm view ecc-universal dist-tags --json
npm view ecc-universal@2.1.0 dist.integrity
curl -fsSIL https://registry.npmjs.org/ecc-universal/-/ecc-universal-2.1.0.tgz
gh release view v2.1.0 --repo affaan-m/ECC
```
Expected:
- `latest` is `2.1.0`.
- The 2.1.0 tarball returns HTTP 200 and immutable caching headers.
- A clean `npm install ecc-universal@2.1.0` succeeds.
- A disposable managed install and uninstall succeed.
The published 2.1 Cursor adapter can report one non-blocking doctor warning for
an adapted Markdown link. This does not prevent installation or uninstall. ECC
2.2 corrects the packed lifecycle and doctor behavior.
## Preflight before Affaan merges
1. PR #2863 must be mergeable and all required hosted checks must pass.
2. The full local suite, npm audit, IOC scan, and exact packed lifecycle must
pass at the PR head.
3. The packed README must describe 2.2 as available and contain no unpublished
2.2 warning.
4. The Nasiko surface must say experimental CLI lifecycle bridge.
5. `npm view ecc-universal@2.2.0 version` must return E404. Any other registry
error blocks the release.
6. `npm view ecc-universal dist-tags --json` must still show `latest: 2.1.0`.
## The release switch
After Affaan merges PR #2863, wait for CI on the exact `origin/main` commit.
From a clean, current `main` checkout:
```bash
git fetch origin main --tags
git switch main
git pull --ff-only origin main
git status --short
git rev-parse HEAD
git rev-parse origin/main
```
The two commit IDs must match and `git status --short` must print nothing.
Affaan then creates and pushes the signed release tag:
```bash
git tag -s v2.2.0 -m "ECC 2.2.0" HEAD
git tag -v v2.2.0
git push origin refs/tags/v2.2.0
```
That tag push is the only launch switch. The workflow then:
1. Requires the tag commit to equal `origin/main`.
2. Packs and hashes the npm archive once.
3. Runs the exact archive on Linux, macOS, and Windows.
4. Publishes the archive to the npm `staged` tag.
5. Reads back and verifies registry integrity.
6. Atomically promotes the verified version to `latest`.
7. Creates the GitHub Release from the reviewed notes.
## Immediate canary
After the workflow succeeds:
```bash
npm view ecc-universal dist-tags --json
npm view ecc-universal@2.2.0 version dist.integrity
gh release view v2.2.0 --repo affaan-m/ECC
npx --yes ecc-universal@2.2.0 setup --help
npx --yes ecc-universal@latest setup --help
```
Expected:
- Both exact-version and `latest` resolve to 2.2.0.
- Registry integrity matches the workflow output.
- The GitHub Release exists and uses the reviewed notes.
- Both package invocations return the guided setup help.
- The native Claude marketplace remains installable.
Keep watching npm and GitHub install paths during the launch window. Treat an
HTTP failure, integrity mismatch, missing public binary, or failed disposable
install as critical.
## Rollback
If 2.2.0 has an install-critical regression, Affaan or another authorized npm
owner restores the known installable fallback immediately:
```bash
npm dist-tag add ecc-universal@2.1.0 latest
npm view ecc-universal dist-tags --json
ECC_ROLLBACK_ROOT=$(mktemp -d)
npm install --ignore-scripts --prefix "$ECC_ROLLBACK_ROOT" ecc-universal@2.1.0
node "$ECC_ROLLBACK_ROOT/node_modules/ecc-universal/scripts/ecc.js" --help
gh release edit v2.1.0 --repo affaan-m/ECC --latest
```
Then open a release incident, state that 2.2.0 remains available only by exact
version while the incident is investigated, and repair forward with a new patch
version. Do not unpublish either package version and do not reuse the `v2.2.0`
tag.
docs/releases/2.2.0/release-notes.md
+42
View File
@@ -0,0 +1,42 @@
# ECC 2.2.0
ECC 2.2.0 makes the universal installer a first-class, cross-harness distribution path. It adds native Antigravity 2.0 support, repairs cumulative install ownership, aligns OpenCode with its canonical configuration directory, and strengthens the exact-artifact release gate.
## Installer and harness reliability
- Antigravity installs natively to `.agents/{rules,workflows,skills,agents}`. Do not manually rename a legacy `.agent` directory. Re-run ECC 2.2.0 so the installer can apply its ownership-aware migration rules.
- Repeated selective installs retain the complete managed ownership ledger. A later module install no longer causes previously installed ECC files to survive uninstall.
- OpenCode home installs use `~/.config/opencode`. Reinstall or repair discovers legacy `~/.opencode` ownership, migrates unchanged ECC-managed files, and preserves modified files for review. Bundled agent definitions inherit the user's selected model provider.
- Legacy Codex sync cleanup requires ownership evidence by default and preserves untracked or modified user files.
- The experimental Nasiko CLI lifecycle bridge recovers locks only when their recorded owner is confirmed dead. Its pinned archive parser rejects malformed boundaries, and incomplete uninstall cleanup returns an error with retained-file guidance. ECC does not connect or operate a Nasiko control plane, enable telemetry, or provide a supported end-to-end Nasiko workflow.
- `skill-comply` is included in both the install graph and npm archive. Python bytecode and pytest caches remain excluded.
## New capabilities
- Guided multi-harness setup and stronger doctor, repair, status, and uninstall flows.
- Native Antigravity 2.0 documentation for Bash and PowerShell.
- Expanded Itô, agent-evaluation, multi-model council, dev-team, living-docs, secure terminal, Pi, and TasteForge workflows, plus the experimental Nasiko CLI lifecycle bridge.
- Improved Plan Canvas, memory vault, continuous learning, skill evolution, hook stability, session handling, and Discord delivery.
## Release assurance
- The release workflow requires the tagged commit to equal `origin/main` exactly.
- npm registry failures stop the release instead of being treated as an unpublished version.
- The exact packed archive is hashed once and exercised on Linux, macOS, and Windows before publication.
- Stable npm releases publish first to a staging dist-tag, verify byte-for-byte registry integrity, and only then promote `latest`. The matching GitHub Release is created after promotion.
- The prior 2.1.0 package remains immutable and installable as the immediate dist-tag rollback target.
## Upgrade
Install or update the published package, then run the same ECC install command you used previously:
```bash
npm install -g ecc-universal@2.2.0
ecc install --target antigravity --profile full
```
Use `ecc doctor --target <target>` after installation. For Antigravity, start a new conversation and verify workspace skills under Settings > Customizations.
## Scope audited
The pre-release audit covered the complete delta from `v2.1.0`: 108 commits, 530 changed files, 40,299 insertions, and 4,679 deletions before the final readiness patch.
docs/testing/ecc-2.2-release-readiness.tdd.md
+87
View File
@@ -0,0 +1,87 @@
# ECC 2.2 release-readiness TDD evidence
Date: 2026-08-25
## Scope
This pass covers the release blockers found in the delta from `v2.1.0`: cumulative selective-install ownership, native Antigravity packaging, canonical OpenCode installation and conservative legacy migration, provider-neutral OpenCode agents, `skill-comply` distribution, conservative legacy Codex uninstall, release-workflow safety, guided-install filesystem boundaries, npm availability during promotion, and accurate Nasiko release boundaries.
## RED
Commit `6e66dfba` added release regressions before the repairs. All six focused commands exited nonzero on the `origin/main` baseline:
- A second selective install retained only the second module in install-state.
- OpenCode resolved to `~/.opencode` instead of `~/.config/opencode`.
- Managed preflight accepted a plan without an install-state path.
- `skill-comply` was absent from the npm archive.
- Release workflows lacked registry-error discrimination, an exact-main gate, reviewed notes, and npm-first publication ordering.
- The packed lifecycle did not exercise Antigravity or OpenCode.
Commit `528dbea0` added a security regression proving guided preflight accepted an identical copy source through a symbolic link. It failed before the no-follow snapshot repair.
Commit `a504b194` added a release regression after review proved both workflows reused the literal 2.2.0 notes path for later valid versions. Both workflow cases failed before the version-derived notes repair.
Commit `55a2d482` added five OpenCode upgrade regressions. Discovery, uninstall, canonical reinstall, repair migration, and no-follow symlink preservation all failed before the legacy managed-root repair.
Commit `7d9f70c5` changed both workflow contracts to require the repository's established lowercase `release-notes.md` convention. Both cases failed against the uppercase 2.2-only path before the filename repair.
Commit `01779a4a` added final-review regressions for OpenCode configuration overrides, retained content digests, failed non-Claude install checkpoints, and reviewed-only GitHub Release notes. All four areas failed before the corresponding repairs.
Commit `dac154ef` added an end-to-end OpenCode override regression covering discovery, doctor, and uninstall through the same explicit configuration root. It failed before environment-aware lifecycle routing.
The full suite then exposed three guided Kimi collision checks that rejected ECC's own new bridge checkpoint before reaching the protected destination. Commit `15815eca` advanced the expected fingerprint only for ECC-authored state writes while preserving every external state and destination collision check.
Commit `2331afbf` reproduced the hosted-runner failure where ambient OpenCode configuration overrides escaped into callers that supplied an explicit temporary home. Both adapter-root and MCP-inventory regressions failed before invocation contexts were isolated.
Commit `85673326` added legacy OpenCode regressions for custom configuration roots, non-file managed operations, canonical repair routing, and provider-specific auto-update guidance. The migration and guidance cases failed before the final legacy-root repair.
Commit `5aa66021` moved ambient-override checks into isolated child processes and added a regression requiring invocation environments to be immutable snapshots. The snapshot assertion failed before the environment-copy repair.
The final independent audit found a recovery race in legacy OpenCode cleanup: a
clobbering rename could overwrite a user file created after quarantine. A
deterministic injected-filesystem regression now proves recovery fails closed,
keeps the new user file, and retains the old managed file in quarantine.
The same audit found prerelease wording in the immutable npm README, temporary
Antigravity guidance, and wording that overstated the Nasiko feature. Focused
copy regressions now reject those stale statements and require the implemented
surface to be described as an experimental Nasiko CLI lifecycle bridge.
## GREEN
- Focused installer, lifecycle, packaging, release-workflow, manifest, OpenCode, Antigravity, and uninstall tests passed.
- Full repository suite: 3,992 passed, 0 failed.
- `npm audit --audit-level=high`: 0 vulnerabilities.
- Supply-chain IOC scan: 207 files inspected, no findings.
- Both release workflow YAML files parsed successfully.
- Both release workflows derive reviewed notes from the validated tag and fail clearly when that version's notes are absent.
- Release-note selection follows the lowercase filename convention shared by prior release directories.
- Exact packed archive lifecycle passed on macOS with Node 24.9.0 using SHA-256 `019547d032e63ee169abb2f92695dee25d6e60ed64c4085142225d75fb7a76c8`.
- The packed lifecycle covered npm installation, public CLI setup, cumulative Cursor install, drift detection, repair, uninstall, user-file preservation, Antigravity install/doctor/uninstall, and OpenCode install/doctor/uninstall.
- Simulated hosted-runner `OPENCODE_CONFIG_DIR` and `XDG_CONFIG_HOME` overrides passed the adapter, MCP inventory, lifecycle, legacy migration, doctor, repair, list, and uninstall suites while explicit CLI environments continued to honor those overrides.
- The stable workflow publishes 2.2.0 to `staged`, verifies the public registry
SHA-512 against the exact tested archive, and only then promotes `latest`.
- The live npm `latest` tag remained on 2.1.0. A clean exact 2.1.0 package
install and disposable Cursor install/uninstall passed, and its tarball
remained publicly readable with immutable caching.
- A launch and rollback runbook assigns the merge, signed tag, and release to
Affaan and uses the npm dist-tag as the reversible availability switch.
## Focused coverage
All six changed core modules exceeded the 80 percent line target:
| Module | Lines | Functions | Branches |
| --- | ---: | ---: | ---: |
| `scripts/lib/multi-harness-setup.js` | 89.01% | 83.87% | 74.30% |
| `scripts/lib/install/claude-skill-migration.js` | 95.20% | 100% | 88.78% |
| `scripts/lib/install-targets/opencode-home.js` | 86.66% | 100% | 78.94% |
| `scripts/lib/opencode-paths.js` | 100% | 100% | 90.90% |
| `scripts/lib/invocation-environment.js` | 100% | 100% | 87.50% |
| `scripts/lib/install/opencode-legacy-migration.js` | 81.89% | 100% | 70.00% |
Coverage commands used `c8 --check-coverage --lines 80` against the corresponding focused test files.
## Release boundary
No merge, release tag, GitHub Release, or npm publication was performed during this pass.