akm-cli 0.9.30 → 0.9.31

package/docs/architecture/specs/okf-support.md

@@ -0,0 +1,148 @@
+# OKF format support
+
+**Status:** DECIDED (0.9.0). OKF is a first-class format supported by AKM
+through the built-in `okf` adapter. First-class means every applicable case in
+the conformance runbook passes end to end; adapter-local recognition alone is
+not sufficient.
+
+## The decision
+
+OKF is AKM's least-common-denominator format for Markdown concepts and generic
+read behavior. AKM can install, recognize, index, search, and show conformant
+OKF bundles without converting them to an AKM-native layout. OKF support is
+held to the observable conformance contract in the
+[OKF v0.2 conformance runbook](../testing/okf-v0.2-conformance-runbook.md).
+
+That baseline does not make OKF AKM's database schema or force non-Markdown
+formats through Markdown. In particular, OKF is **not**:
+
+- an AKM asset type;
+- a serialization imposed on scripts, YAML tasks, environment files, secrets,
+  Agent Skills, or other native non-Markdown assets;
+- a replacement for adapter-owned capability, validation, redaction, placement,
+  or execution rules.
+
+The core provides path identity, open descriptive types, generic Markdown
+content/fragment reads, and a normalized search projection. Adapters add
+behavior to that baseline. They never narrow the core by rejecting an item only
+because its `type` is unfamiliar.
+
+## First-class support contract
+
+For a bundle selected as `adapter: okf`, AKM must provide all of the following:
+
+1. Every conformant non-reserved Markdown concept is recognized with its OKF
+   path-minus-`.md` concept ID.
+2. `type`, `title`, `description`, `tags`, and `timestamp` are read according
+   to OKF rules. Unknown types and unknown frontmatter fields remain valid.
+3. `index.md` and `log.md` retain their OKF structural meaning and are not
+   indexed as concepts.
+4. OKF links are retained as relationships. A dangling link does not prevent
+   indexing.
+5. A ref emitted by search for an OKF concept is accepted by show and other
+   applicable ref-consuming commands. Adapter-owned concept IDs such as
+   `tables/customers` must not be rejected merely because they do not use an
+   AKM bundle placement directory.
+6. Markdown heading fragments are accepted as input-only selectors and never
+   become part of durable identity.
+7. An OKF target without adapter-owned authoring rejects AKM-native write
+   commands before touching disk. AKM must never silently place native files in
+   an OKF bundle.
+
+The shipped `okf` adapter is consumer-only. Its supported behavior is the
+portable content/fragment baseline; it does not infer task, command, script,
+environment, or secret capabilities from an arbitrary OKF `type` value.
+
+## Progressive enhancement
+
+AKM Markdown is an OKF-compatible superset. Newly authored AKM Markdown emits a
+non-empty native `type` plus any AKM-specific frontmatter required by its asset
+kind. The `akm` adapter still derives native identity and capability from its
+directory, extension, filename, and content rules; frontmatter `type` does not
+override those rules. Existing legacy Markdown without `type` remains readable
+and is upgraded when AKM creates or semantically rewrites it rather than during
+indexing.
+
+The result is progressive enhancement:
+
+1. Any OKF type gets path identity, indexing, search, content show, and heading
+   fragments through the `okf` adapter.
+2. The `akm` adapter recognizes AKM-owned types and adds their specialized
+   behavior: command prompts, runnable scripts, workflows, tasks, redacted
+   environment/secret views, memories, lessons, and other native capabilities.
+3. Unknown `type` values remain valid data. They get generic behavior unless
+   the selected adapter explicitly adds more.
+
+`akm bundle create` records `adapter: akm`. `akm bundle add` records the detected adapter, and an
+explicit configured adapter always wins over probing. Strong native AKM layout
+evidence wins before the broader OKF probe because AKM Markdown is an OKF
+superset. An index-less bundle containing conformant typed Markdown can still be
+recognized as OKF.
+
+The normalized `IndexDocument` is the additive cross-format projection. Its
+basic Markdown fields align with OKF, while adapters may project additional
+metadata and capabilities without changing identity.
+
+## v0.2 update (#730)
+
+OKF v0.2 (Google Cloud) adds a trust/provenance frontmatter family
+(`generated`/`verified`/`sources`) and a lifecycle family
+(`status`/`stale_after`), standardizes an actor convention
+(`<producer>/<version>` / `human:<id>` / `process:<id>`), and makes one
+breaking-with-fallback change: `timestamp` is superseded by `generated.at`,
+with consumers permitted (and expected) to fall back to the legacy
+`timestamp` field when `generated`/`generated.at` is absent. The decision
+above is unchanged by this update — the `okf` adapter remains **consumer-only**
+and the read/write split stays exactly where §5/§5.1 already drew it:
+
+- **Read side (any OKF bundle, third-party or AKM-authored):** the `okf`
+  adapter parses the full v0.2 family — `generated.at` (with the `timestamp`
+  fallback), `verified` (a list, or v0.2's permitted single-mapping
+  shorthand), `sources` (an object list), `status`, `stale_after`, and
+  `okf_version` — leniently, exactly like every other optional OKF field
+  (missing, malformed, or foreign values never reject a document). These land
+  on new, NAMESPACED `IndexDocument` fields (`provenance`, `lifecycleStatus`,
+  `staleAfter`, `okfVersion`) rather than overloading the three AKM-native
+  fields that already occupy adjacent names: `sources?: string[]` (wiki
+  citation strings), `generation?: number` (consolidation merge depth), and
+  the existing `quality: "generated"` enum value. See
+  `akm-0.9.0-bundle-adapter-spec.md` §0.1 for the full mapping.
+- **Write side (AKM-native assets only, through the proposal path):** since
+  AKM Markdown is already an OKF-compatible superset (the progressive-
+  enhancement contract above), the new provenance fields are *written* only
+  to AKM-native assets, at proposal-promotion time (`promoteProposal`) —
+  never through the `okf` adapter, which stays consumer-only. Accepting a
+  proposal stamps the v0.2 families using the existing
+  `source`/`sourceRun`/`gateDecision`/`review` provenance the proposals system
+  already tracks in `state.db`.
+
+  The on-disk shape is deliberately **hybrid**:
+
+  - `generated: {by, at}` and `verified: [{by, at}]` are written **bare at the
+    top level**, exactly as OKF v0.2 spells them. Neither key has any
+    pre-existing AKM consumer, so spelling them the spec's way costs nothing
+    and makes the OKF-superset claim above true *for trust metadata* — a
+    third-party OKF v0.2 reader pointed at an AKM bundle sees conformant
+    provenance rather than one unrecognized `provenance:` key.
+  - `sources` alone stays namespaced as `provenance: {sources: [...]}`,
+    because a bare top-level `sources:` genuinely collides with the
+    pre-existing wiki citation-**string** convention noted above.
+
+  Every AKM-native markdown type is stamped. `workflow` is the only type whose
+  frontmatter is parsed against a closed allowlist, and that allowlist admits
+  these keys; a re-validation fallback (promote unstamped, warn) is retained
+  only as a backstop should a future type add a closed allowlist.
+
+  `stale_after`-driven re-verification and trust-tier ranking are explicitly
+  out of scope for 0.9.0 (an 0.9.x improve-tuning track).
+
+OKF is a month-old, single-vendor **Draft** with no governance body; AKM
+vendors a frozen copy of the spec rules it implements rather than tracking
+upstream live. See the conformance runbook for the pinned upstream reference.
+
+## See also
+
+- [`akm-0.9.0-bundle-adapter-spec.md`](./akm-0.9.0-bundle-adapter-spec.md)
+  defines the concrete `okf` and `akm` adapter boundaries.
+- [`ref.md`](./ref.md) defines the cross-format ref grammar.
+- [`0.9.0-decisions.md`](./0.9.0-decisions.md) records this positioning as D11.

package/docs/architecture/specs/ref.md

@@ -0,0 +1,329 @@
+# Ref Format
+
+A `ref` is the identifier that `akm search` returns for items and `akm show`
+consumes.
+
+Agents should not parse refs or construct them by hand. The intended flow is:
+
+```text
+search -> pick a hit -> pass its ref to show
+```
+
+> **Status.** This document is normative for 0.9.0 and is the target the
+> implementation is being brought to. Sections marked **[0.9.0 change]**
+> describe decisions taken during the 0.9.0 surface review that the code does
+> not yet fully implement; see
+> [`0.9.0-release-surface-review.md`](./0.9.0-release-surface-review.md) and
+> [`0.9.0-decisions.md`](./0.9.0-decisions.md).
+
+## Item Refs
+
+Item refs use this wire format:
+
+```text
+[bundle//]conceptId[#fragment]
+```
+
+| Part | Required | Description |
+| --- | --- | --- |
+| `bundle` | no | Workspace bundle slug (e.g. `personal`, `team-catalog`) that owns the item. Separated from the rest of the ref by `//`. When omitted, the ref resolves against the containing bundle (content-internal refs) or, for CLI/API input, against `defaultBundle` and then the remaining bundles in installation-priority order. |
+| `conceptId` | yes | Adapter-defined path within the bundle, `/`-separated and canonicalized by that adapter. Examples: `knowledge/http-caching`, `skills/code-review`, `scripts/db/migrate/run.sh`, `tables/customers`. |
+| `fragment` | no | Selector for a part of the item. For markdown-document items the core interprets it as a **section selector**; for every other item kind it is an adapter-owned selector, opaque to the core. See [Fragments](#fragments). |
+
+`type` is **no longer part of a ref**. Identity is a path, not a `type:name`
+pair, and a conceptId is an **opaque path** — akm does not parse meaning out of
+its segments. `skills/deploy` and `workflows/deploy` are distinct concepts that
+never collide because their paths differ, not because their first segment is a
+recognized word.
+
+An item's `type` is an **attribute of the resolved item**, supplied by the
+selected adapter, never a predicate parsed out of the ref string. The `okf`
+adapter reads it from OKF frontmatter; the `akm` adapter derives it from its
+native matcher and placement rules. This is why a ref into any bundle —
+`okfbundle//tables/customers`, `wiki//pages/attention` — is just as addressable
+as `personal//memories/vpn-note`. See
+[`okf-support.md`](./okf-support.md).
+
+Refs are parsed by `parseBundleRef` in `src/core/asset/asset-ref.ts`. The
+grammar (normative spec §11.1) is:
+
+```text
+ref        := [ bundle "//" ] concept-id [ "#" fragment ]
+bundle     := any run of non-space chars excluding : . # /
+concept-id := adapter-canonical path within the bundle, / -separated, NFC, case-sensitive
+fragment   := section slug (markdown-document items) | adapter-owned selector
+```
+
+The bundle slug excludes `:`, `.`, `#`, `/`, and whitespace so a `bundle//conceptId`
+token is lexically distinct from a URL (whose scheme carries a `:` before `//`) and
+so the first `//` unambiguously bounds the bundle.
+
+### AKM concept ids and adapter layouts
+
+The subdirectory prefix is the item's placement directory:
+
+| Subdir | Holds | Example conceptId |
+| --- | --- | --- |
+| `scripts/` | Executable scripts | `scripts/deploy.sh` |
+| `skills/` | Skill directories (`SKILL.md`) | `skills/code-review` |
+| `commands/` | Slash-command templates | `commands/release` |
+| `agents/` | Agent definitions | `agents/reviewer` |
+| `knowledge/` | Reference documents | `knowledge/api-guide` |
+| `workflows/` | Workflow documents / programs | `workflows/ship-release` |
+| `memories/` | Recalled context fragments | `memories/deployment-notes` |
+| `lessons/` | Distilled feedback lessons | `lessons/retry-backoff` |
+| `facts/` | Durable bundle-level facts | `facts/team/tool-stack` |
+| `sessions/` | Indexed agent sessions | `sessions/claude/2026-07-24-abc` |
+| `env/` | `.env` configuration groups | `env/prod` |
+| `secrets/` | Single sensitive values | `secrets/deploy-token` |
+| `tasks/` | Scheduled / on-demand tasks | `tasks/nightly-sync` |
+
+These are the subdirs the **`akm` adapter** places into and interprets according
+to its own matcher rules. Other bundles use whatever paths their adapters
+declare — an OKF bundle emits `tables/customers`, an LLM wiki emits
+`pages/attention`, and a website snapshot emits its crawled path. Every one of
+those is an equally valid conceptId; the core does not require the leading
+segment to be an AKM placement directory.
+
+### Examples
+
+- `scripts/deploy.sh`
+- `skills/code-review`
+- `knowledge/api-guide`
+- `commands/release`
+- `agents/reviewer`
+- `memories/deployment-notes`
+- `env/prod`
+- `personal//knowledge/http-caching`
+- `team-catalog//workflows/release`
+- `knowledge/api-guide#authentication` (section selector)
+
+### Rejected
+
+- `viking://skills/deploy` (URI scheme — a `:` before `//` is not a bundle slug)
+- `skills/../../../etc/passwd` (path traversal)
+- `github:owner/repo` (this is an install ref, parsed elsewhere)
+- the pre-0.9.0 `<type>:<name>` grammar (e.g. the old colon-typed spelling) — dead;
+  parsed only by the frozen migrator
+
+## Fragments
+
+**Scope: `show` only in 0.9.0 (ruled 2026-07-26, Q-06).** `parseRefInput`
+still rejects any `#fragment` outright; `show` is the only command that
+accepts one, by bypassing that shared parser. Every other ref-consuming
+command (graph, tasks, improve, proposals, the utility repo, the indexer
+walk) routes through `parseRefInput` and does not accept fragments yet.
+Wider rollout is post-0.9.0.
+
+**[0.9.0 change]** Before 0.9.0 the fragment production existed in the grammar
+and in this document, but every input boundary rejected it
+(`parseRefInput` threw `INVALID_FLAG_VALUE` for any `#fragment`) and nothing
+consumed it. It was stable on paper and unusable in practice. 0.9.0 resolves
+that by giving it one concrete meaning the core implements, and keeping the
+adapter-owned meaning for everything else.
+
+**Markdown-document items — section selector (core-implemented).** For an item
+whose adapter presents it as a markdown document, the fragment names a section:
+
+```text
+akm show knowledge/api-guide#authentication
+```
+
+Resolution is: slugify each heading in the document (lowercase, non-alphanumeric
+runs collapsed to `-`, trimmed) and match the fragment against those slugs;
+fall back to a case-insensitive match against raw heading text. The selected
+region runs from that heading to the next heading of the same or higher level.
+A fragment that matches no heading is an error that **lists the available
+fragment slugs** — that error is the discovery mechanism, replacing the removed
+`toc` view mode.
+
+**Every other item kind — adapter-owned selector.** Per normative spec §11.3,
+when one item exposes multiple exports the adapter MAY append a stable
+fragment (`team//tools/toolbox#deploy`). The fragment is adapter-owned and
+opaque to the core. The two meanings coexist because the core only interprets
+fragments for items whose adapter declares them markdown documents; for
+everything else it passes the fragment through untouched.
+
+**Fragments are input-only.** Durable state — index rows, state keys, proposal
+targets, bindings — never stores a fragment. A stored ref carrying one is
+invalid.
+
+### Superseded: the `akm show` view-mode grammar
+
+**[0.9.0 change]** `akm show <ref> toc|section "H"|lines A B|frontmatter|full`
+is removed. It was a second argv parser (`normalizeShowArgv` rewrote
+`process.argv` and injected hidden `--akmView` / `--akmHeading` / `--akmStart` /
+`--akmEnd` flags), and its view keywords were reserved words in ref position.
+
+| Old | New |
+| --- | --- |
+| `akm show X section "Auth"` | `akm show X#auth` |
+| `akm show X full` | `akm show X` (no fragment = whole item) |
+| `akm show X toc` | `akm show X#<unmatched>` lists available fragment slugs |
+| `akm show X lines 10 30` | removed — every response carries `path`; slice the file |
+| `akm show X frontmatter` | removed — if a raw-YAML projection proves necessary it returns as a `--shape` value, the designated projection axis |
+
+## Ref-prefix enumeration (browse)
+
+**[0.9.0 change]** Browsing a subtree uses a **conceptId prefix**, matching the
+grammar refs are actually emitted in:
+
+```text
+akm search "memories/"                 # every memory in scope
+akm search "memories/projecta/"        # one subtree
+akm search "team-catalog//"            # every item in one bundle
+akm search "team-catalog//skills/"     # one subtree of one bundle
+```
+
+A trailing `/` is required for a non-empty prefix, giving exact `/`-boundary
+subtree semantics (`projecta/` cannot match a sibling `projectalpha/`). A query
+with interior whitespace is prose, not a prefix — it stays an ordinary keyword
+search.
+
+This replaces the pre-0.9.0 `akm search "<type>:"` / `"<type>:<prefix>/"`
+grammar, which had three defects: it resurrected the singular `type:` spelling
+the release removed; it validated against the `akm` adapter's placement types,
+so items from every other adapter could not be enumerated at all; and it
+matched against item *names* while every displayed ref is a conceptId — so
+copying a ref prefix out of search output and pasting it back in silently
+degraded to a keyword search.
+
+Because enumeration is now prefix-matching over conceptIds, it covers every
+adapter's items uniformly, and `bundle//` enumeration replaces the removed
+`akm bundle items` command.
+
+## Asset types are free-form
+
+`type` is adapter-supplied metadata that presents, ranks, and filters — it
+never executes and never identifies. The OKF adapter reads the open OKF `type`
+field and defaults it according to OKF adapter rules; other adapters derive a
+type from their native formats. `IndexDocument.type` is an open string by
+contract, and adapters emit types outside the `akm` adapter's placement set
+(`website`, `wiki-source`, an LLM-wiki page's `pageKind`, `instruction`, and
+anything an OKF bundle author writes).
+
+Consequently `akm search --type <t>` is an **exact string match against an open
+set, deliberately unvalidated**: an unrecognized type returns zero hits rather
+than an error, because "unrecognized" is not a decidable property. Callers that
+want a closed set should filter on conceptId prefix instead (see above).
+
+The closed set still applies where a type must select a *write placement* —
+`akm proposal new <type> <name>`, `placeNew` — because those need a directory to write to.
+
+## Reserved structural files
+
+For the OKF adapter, `index.md` (directory listing / progressive disclosure)
+and `log.md` (update history) are reserved structural files at every level and
+are never concepts. The `akm` and `llm-wiki` adapters independently reserve
+the same names as part of their own format contracts. Other adapters own their
+reserved-name rules; the cross-format ref grammar does not impose OKF
+structure on them. Item writes must follow the selected adapter's rules.
+
+## Install Refs (distinct grammar)
+
+`akm add` and one-shot `akm clone` accept a different ref grammar. Install
+refs locate an upstream kit to fetch; they are **not** item refs and are
+parsed by `parseRegistryRef` in `src/registry/resolve.ts`.
+
+```text
+install-ref := github-ref | git-url | npm-pkg | https-url | skills-sh-slug | local-path
+```
+
+Examples: `github:owner/repo#v1.2.3`, `git+https://gitlab.com/org/kit`,
+`@scope/kit`, `https://docs.example.com`, `skills.sh:code-review`,
+`./path/to/kit`.
+
+The two parsers are intentionally distinct — each rejects the other's inputs.
+Item refs never carry URI schemes; install refs are not addressable through
+`akm show`.
+
+## Bundle prefix
+
+When a ref includes a bundle prefix, `akm show` narrows lookup to that bundle:
+
+```text
+team-catalog//scripts/deploy.sh
+personal//knowledge/my-notes
+```
+
+When absent, a short ref from CLI/API input resolves to `defaultBundle` if the
+conceptId exists there, otherwise to the first bundle containing it in installation
+priority order (first match wins, deterministically). A short ref inside bundle
+content resolves against its **containing** bundle. To pin lookup to a single
+bundle programmatically, use `resolveRef(input, { only: bundleId })` — there is no
+ref spelling for "primary only".
+
+## Refs in prose
+
+Refs embedded in prose MUST use the fully-qualified `bundle//conceptId` form —
+the bundle-slug charset makes such a token lexically anchored — or a native
+link form owned by the adapter (OKF links, wiki links). **Bare short refs in
+prose are not refs**: `memories/foo` in a sentence is ordinary text, and no
+tool may rewrite it.
+
+Only lint's missing-ref scan honours this rule today. The other consumer,
+`akm mv`'s inbound-ref rewriting, was defective: it implemented the rule
+exactly inverted (it rewrote bare conceptIds and matched no `bundle//` pattern
+at all), so it rewrote prose that is not a ref while leaving real anchored
+refs dangling. That defect is why `akm mv` shipped **Experimental** earlier in
+the 0.9.0 cycle and was never covered by the stability contract.
+
+**Amended 2026-07-30.** `akm mv` was removed outright before the 0.9.0
+release (no alias, no stub — see [`0.9.0-decisions.md` §D3](./0.9.0-decisions.md#d3--renames-are-delete--create-akm-mv-ships-experimental)).
+There is no tool today that rewrites inbound refs on rename; see "Renames and
+moves" below for the current procedure.
+
+## Renames and moves
+
+**[0.9.0 change]** A rename or move is **delete plus create**. The destination
+is a new identity: it gets a fresh index row, and learned state (utility,
+salience, outcomes, usage history) does not follow it.
+
+```sh
+mv ~/akm/memories/old-note.md ~/akm/memories/new-note.md
+# update any intentional refs to it
+akm index
+akm lint          # confirms nothing dangles
+```
+
+Moving an item **between bundles** is copy/import followed by deletion from the
+source. Both the bundle and the concept identity change; there is no
+identity-preserving cross-bundle move.
+
+This supersedes the pre-0.9.0 rule that a rename "MUST use an explicit
+state-rekey transaction". That rule was a product choice made during the bundle
+refactor, not a constraint the architecture imposes. `akm mv`, which implemented
+the superseded rule, shipped briefly as an **Experimental** surface outside
+the stability contract, because its inbound-ref rewriting was inverted (above),
+then was removed outright before the 0.9.0 release. The procedure above —
+plain filesystem move, then `akm index`, then `akm lint` — is the only
+supported path today. If preserving learned state through renames later proves
+materially valuable, a narrow same-bundle `akm rename` can return — resolving
+through the index, using adapter-owned placement, accepting qualified refs,
+rewriting only anchored prose refs, applying one qualified old→new state
+mapping, and rebuilding derived index data rather than preserving row IDs.
+
+**Amended 2026-07-30.** Carrying learned state (utility, salience, usage
+history) across a rename is opt-in and out-of-band: run
+`bun scripts/rekey-asset-ref.ts <old-ref> <new-ref>` from a source checkout
+**before** `akm index`, and it re-keys the `entries` row plus
+`asset_salience`/`asset_outcome`/`usage_events` in place rather than letting
+`akm index` mint a fresh row. Automated garbage collection of orphaned rows
+left by renames that skip this script is tracked as issue #733; until it
+lands, the script is the only path. See
+[`v0.9.0-troubleshooting.md`](../../migration/v0.9.0-troubleshooting.md) for
+the full walkthrough.
+
+## Usage Notes
+
+Consumers should use structured fields like `conceptId` and `bundle` for display,
+and pass the full `ref` string back to `show` as the lookup token.
+
+## Canonical Form
+
+Refs are emitted in canonical form: the bundle slug (when qualified), the
+adapter-canonical conceptId, and an optional `#fragment`. The adapter decides
+whether an on-disk extension is stripped: OKF and AKM Markdown items strip
+`.md`, scripts retain executable extensions, and directory-items such as
+skills resolve on the directory path (`skills/<dir>`, not
+`skills/<dir>/SKILL`).

package/docs/architecture/specs/reviews/task-workflow-unification/README.md

@@ -0,0 +1,72 @@
+# Review corpus — task/workflow format unification
+
+Reference record for
+[`../../task-workflow-format-unification.md`](../../task-workflow-format-unification.md).
+Every revision of that spec from v8 onward was shaped by these reviews; the
+spec's §11 cross-references findings by the ids used here.
+
+## Round 0 — three independent adversarial reviews of spec v7
+
+Three reviewers, identical briefs, no shared context — overlap between
+reports is therefore independent confirmation, and unanimous findings
+(3/3) were treated as settled facts.
+
+| File | Contents |
+|---|---|
+| [`opus-review-1.md`](./opus-review-1.md) | Reviewer 1 full report |
+| [`opus-review-2.md`](./opus-review-2.md) | Reviewer 2 full report |
+| [`opus-review-3.md`](./opus-review-3.md) | Reviewer 3 full report |
+| [`findings-consolidated.md`](./findings-consolidated.md) | Deduplicated findings (C1–C5, M1–M13, minors) with per-reviewer attribution — the ids the spec's §11 uses |
+
+Outcome: v7 → v8 full redesign (IR v4 invocation union, hashVersion 5,
+two output schemas, cascade built-not-exposed, `with:`, env provenance
+split, migration rebuilt).
+
+## Round 1 — four-lens panel on spec v8
+
+| File | Lens |
+|---|---|
+| [`panel-r1-coverage.md`](./panel-r1-coverage.md) | Findings-coverage audit: does §11 resolve each round-0 finding, or just name it |
+| [`panel-r1-architecture.md`](./panel-r1-architecture.md) | Module boundaries and seams against the codebase's own idioms |
+| [`panel-r1-adversarial.md`](./panel-r1-adversarial.md) | Fresh defect hunt on what v8 itself introduced |
+| [`panel-r1-security.md`](./panel-r1-security.md) | Script-execution policy, env/redaction contracts, migration mechanics |
+
+Outcome: v8 → v9. Headline: the per-bundle script-execution grant was
+withdrawn (contradicted `activation-policy.ts`'s no-new-trust-machinery
+decision) in favor of exact 07 P1-D ceiling inheritance; persona snapshot
+added to the hash preimage; `with:` merge defined; tombstone read-only
+carve-out and interruption-safe conversion ordering.
+
+## Round 2 — verification on spec v9
+
+| File | Lens |
+|---|---|
+| [`panel-r2-verification.md`](./panel-r2-verification.md) | Every round-1 critical/major re-checked against v9 and code — verdict: **all fixes hold** |
+| [`panel-r2-adversarial.md`](./panel-r2-adversarial.md) | Cold pass, no prior context — verdict: no design flaws; two evidence corrections (the real placeholder filler; indexer-classifier recognition), both applied |
+
+## Library evaluations — buy-vs-build investigation
+
+Three independent investigations into replacing the hand-rolled engine
+with a third-party library, all verified against live artifacts rather
+than training knowledge. Decision record:
+[`../../workflow-engine-buy-vs-build.md`](../../workflow-engine-buy-vs-build.md).
+
+| File | Scope |
+|---|---|
+| [`library-eval-bunqueue.md`](./library-eval-bunqueue.md) | bunqueue — full rubric + source read |
+| [`library-eval-openworkflow.md`](./library-eval-openworkflow.md) | OpenWorkflow — full rubric, **executed** (SIGKILL durability probe, reproduced schema collision) |
+| [`library-eval-alternatives.md`](./library-eval-alternatives.md) | Landscape survey — 25+ candidates against the no-server / SQLite / Bun+Windows / license constraints |
+
+Outcome: **build**. ~6% of `exec`+`ir` is the generic durable-execution
+concern libraries sell; the best candidate deletes 8–12% while removing
+cancellation, concurrency caps, and transactional atomicity.
+
+## Reading notes
+
+- Reports cite `file:line` against the branch state they reviewed
+  (`claude/release-0-9-0-polish-d6sycl` @ `71bb686` + this spec's branch);
+  lines drift as the base moves.
+- Not every claim in the raw reports survived verification — e.g. round 1's
+  "the `tools:` ceiling doesn't exist" was disproven (`show.ts:433-445`).
+  Where a report and the spec disagree, the spec's §11 records the
+  adjudication and is authoritative.