AIWG 2026.7.1 - "Fortemi Core index migration preview"

AIWG 2026.7.1 - "Fortemi Core index migration preview"

Released: 2026-07-03 Channel: stable (`npm install -g aiwg`)

This release note tracks the Fortemi Core index/search migration. AIWG now uses the static Fortemi Core cache path as the default artifact search/traversal backend while preserving the existing `.aiwg/.index` local backend behind `--backend local` for the phase-out window.

What changed

v2 AIWG -> Fortemi export contract

`aiwg index export --format fortemi` still defaults to the v1 compatibility contract. The new `--schema-version v2` option emits AIWG domain records for skills, agents, commands, rules, flows, project-local bundles, research REF/PROF records, KB pages, memory entries, issues, and project artifacts.

The v2 records include search projections, typed relationships with direction, privacy locality, source-body chunks, and embedding metadata slots for the shared Fortemi Core semantic path.

AIWG also keeps a tested v2-to-v1 projection for older Fortemi React consumers. The active `@fortemi/[email protected]` contract validates the v2 export directly, including v2 relationship fields, chunk metadata, SKOS metadata, and provenance-event metadata.

Default Fortemi Core static cache

`aiwg index sync` materializes a v2 static export and manifest under `.aiwg/.index/fortemi-core/<graph>/`. Artifact search, discovery, traversal, hybrid/static semantic query, and research source selection use this cache by default. Operators can pass `--backend local` to use the legacy local index during the deprecation window.

The npm release package now also carries a prebuilt `framework` graph cache under `prebuilt/fortemi-core/framework/`. If no compatible local framework cache exists, default discovery can use that packaged fallback. The packaged cache is a compact metadata/capability projection; local sync remains the source-body/fulltext path.

A synced Fortemi Core cache with zero items is valid, not stale. Queries return empty result sets, `aiwg discover` reports a Fortemi static-cache no-match hint, and `aiwg show` does not fall back to the local AIWG corpus unless operators explicitly select `--backend local`.

Supported Fortemi-backed commands in this preview include:

  • `aiwg discover` / `aiwg show`
  • `aiwg index query`, including static semantic and filtered hybrid query modes
  • `aiwg index deps`
  • `aiwg index neighbors`
  • `aiwg index set`
  • `aiwg research-query` source selection

Boundary clarifications

Two existing Fortemi-adjacent surfaces remain separate from the Fortemi Core static index/search backend:

  • The `fortemi` storage backend in `.aiwg/storage.config` is the Fortemi MCP

persistence adapter. It can route KB or memory storage through Fortemi MCP tools, but it does not switch AIWG discovery, query, graph traversal, or research-query away from the Fortemi Core static cache.

  • Local issue search remains served by the local issue provider and

`.aiwg/issues/index/issues.index.json`. The v2 export can include `aiwg.issue` records, but `aiwg issue list --search` does not require or use the Fortemi Core cache in this preview.

Related tracker items #1551 and #1508 remain open unless maintainers explicitly decide otherwise. #1551 tracks body-level embedding behavior that may be subsumed by a later Fortemi v2 acceptance gate; #1508 stays deferred until a provider-neutral corpus-to-storage/index boundary is approved. Direct Fortemi REST import and hardcoded-token patterns remain out of scope for this preview.

No-regression parity fixtures

The migration includes static parity fixtures that compare the current local backend against the Fortemi static cache for discovery, show, metadata query, fulltext query, static semantic/hybrid query, graph traversal, research REF/PROF retrieval, KB traversal, and v1/v2 export behavior. The `research-query` executable wrapper now makes source-selection parity testable with the Fortemi Core default while leaving GRADE-aware answer synthesis in the research-query skill workflow.

The suite intentionally keeps equal-score ordering tolerances explicit: exact where behavior is deterministic, membership-only where the current scorer produces equivalent ties.

The release gate also runs `npm run ci:fortemi-index`, which exercises the discovery matrix against local and Fortemi Core backends, invokes `npm pack` through `prepack`, verifies the prebuilt files, manifest checksum, and size ceiling inside the tarball, and proves packaged fallback discovery from an empty local cache.

Fallback

If a Fortemi-backed command reports a missing or stale cache, run `aiwg index sync` to refresh it, or use `--backend local` for the legacy fallback:

aiwg index query "retrieval"
aiwg index query "retrieval architecture" --hybrid --type adr --tags search --json
aiwg index query "retrieval" --backend local

To reset the cache:

rm -rf .aiwg/.index/fortemi-core
aiwg index sync --graph project

Do not remove `.aiwg/.index/<graph>/`; it remains the rollback source.

Fortemi Core 2026.7.1 baseline

`@fortemi/[email protected]` is now published with the `@fortemi/core/aiwg-index` subpath, direct v2 AIWG export validation, relationship traversal APIs, chunked-index helpers, and static semantic/hybrid helper contracts. AIWG can use it as the released baseline for the next migration slice.

The Fortemi v2 package-adoption gate is satisfied for the current static export contract. AIWG still keeps package-independent static semantic/hybrid fixtures over the v2 cache so required CI does not depend on optional embedding packages.

Still Gated

Removing the legacy local backend remains gated until the deprecation window closes and rollback evidence is reviewed. Live Fortemi integration tests remain optional and must skip cleanly without credentials.

The legacy `fortemi` MCP storage adapter remains available for persistence migrations but is deprecated for discovery/search routing. Search callers should use the Fortemi Core default and reserve `--backend local` for legacy fallback.