Assay 0.14.0

Assay 0.14.0

Assay 0.14.0 removes the immutability ceremony from the evidence loop, gives
every Source one home reachable from any workspace, prunes Source adoption to a
traceability record, and teaches the CLI to explain its own semantics. The
workspace envelope is 0.14.0+s4+l8: it breaks record formats on purpose, and
assay update migrates a 0.13.0 workspace in place; there are no compatibility
shims behind it.

This note covers the full change set since v0.13.0.

Breaking

• The workspace envelope is now 0.14.0+s4+l8. A 0.13.0+s4+l8 workspace is
  refused by every command except assay update, which migrates it and says what
  it rewrote. Anything older still requires the external cutover tool. The refusal
  for a migratable workspace now names assay update and carries an
  assay-update:<observed>-><required> locator instead of the cutover locator.
• source add --mode living|frozen and source add --capture checkout|archive
  are gone, along with the living, frozen, and archive concepts. A source's
  shape follows the material: a Git repository or URL is checkout-backed, and
  anything else is copied once into content/. Scripts passing either flag will
  fail on an unknown option.
• source.yaml replaces mode and default_capture_mode with a single
  content_mode of checkout or copy. Both retired fields are rejected on read.
• Source observations are now cheap append records: {observation_id, observed_on, lineage_id, source_path, previous_observation, kind, change_class, note, advisories} plus vcs for a Git source and capture for an observation that
  preserved bytes. The fingerprint, manifest, capture_mode, materials_path,
  checkout_path, and capture_path fields are gone, and a record still carrying
  them is rejected on read. No default path computes a sha256-tree any more.
• Per-observation manifests under sources/<alias>/manifests/ are no longer
  written or read. A capture keeps its integrity manifest beside its bytes, at
  captures/<id>/manifest.json.
• source sync and source switch apply only to checkout-backed sources. Calling
  either on copied content is a teaching error that names source import and
  source capture instead.
• sync and switch no longer refuse a dirty checkout, an unrecorded local
  commit, or checkout bytes that differ from the last observation. They proceed and
  record an observed with local modifications advisory on the observation. Refresh
  is non-destructive: git fetch plus merge --ff-only, never reset --hard or
  clean -fd. An upstream that cannot fast-forward is recorded and left alone.
  Byte-loss protection is delegated to Git, which already declines to overwrite
  uncommitted work.
• SourceObservationResolution returns contentMode, contentPath, and
  capturePath in place of manifestFile, materialsPath as observation state,
  and checkoutPath.
• SourceStatusEntry returns contentMode, latestAdvisories, and captures in
  place of mode and captureMode. assay status counts sources as checkouts
  and copies rather than living and frozen.
• assay source add no longer prints a Manifest: line; it prints Checkout: or
  Content: depending on the content mode.
• The frozen source alias is no longer reserved, since there is no sources/frozen
  namespace to protect.
• The Source adoption command surface is take, list, show, remove. The
  register, update, status, inspect, evidence add, verify, decide,
  history, and rollback record subcommands are gone, along with the whole
  inspection, evidence, decision, and rollback workflow behind them: its storage,
  its schemas, the SOURCE_ADOPTION_POLICY_BLOCKED, SOURCE_ADOPTION_STALE, and
  SOURCE_ADOPTION_BUSY error codes, and its tests. A single-user workbench
  records decisions in analysis close --exit and in the adoption's note; the
  adoption record's job is traceability — where did this material land — not an
  approval pipeline.
• A Source adoption is now one mapping: source alias and path, target system and
  path, an optional note, an optional tier-1 identity pin, and mode. An intent
  that moved several paths is several records. The assay.source-adoption/v1
  schema replaces the assay.source-adoption-definition/v1,
  -state/v1, -inspection/v1, -evidence/v1, and -decision/v1 family, and
  each record is a single file at .assay/source-adoptions/<id>.json rather than
  a per-adoption directory. --mode adapt|copy stays, as descriptive metadata for
  upstream-drift review.
• Per-adoption .lock files are gone. One record is one atomic file write, so
  there is nothing to serialize; adoption writes still pass through the workspace
  mutation gate that fences a conversion.
• assay status reports Source adoptions as adoptions, systems, and pinned
  in place of targets, acceptedTargets, and draftTargets. FrameworkStatus
  and --json output change with it.
• assay check reports Source adoption structure only: whether each record parses
  and validates, whether its filename still matches its id, and whether the system
  it names is still registered.

Added

• Cross-workspace Source references. assay source link <target-workspace> <target-source> [--alias <local-alias>] writes a thin pointer at
  sources/<local-alias>/source.ref.yaml — schema assay.source-reference/v1,
  fields workspace and source, nothing else — so a Source that already has a
  home is reached instead of cloned again. assay source home <alias> says where
  an alias actually lives, for owned and referenced Sources alike, and
  assay source unlink <alias> forgets the local name. See
  docs/source-reference.md.
• Read operations on a referenced alias always show the relation. source status
  appends ref -> ../shared-research#qiskit to the row; source log,
  source diff, and source sync print Relation: and Home: lines. A
  reference is never displayed as if the workspace owned the material.
• Write operations through a reference — sync, capture, import, switch —
  land in the home. They print the home's path before starting the work, run
  under the home workspace's mutation coordination rather than the consumer's,
  and add no confirmation gate. --json callers get the same fact from the
  result's reference block. assay status counts references and
  broken references alongside checkouts and copies.
• Deletion stays asymmetric. unlink removes the pointer file and the directory
  it was alone in, never recursively and never through to the home; a shell that
  somehow holds content keeps it. Aiming unlink at a Source this workspace owns
  is a teaching error, not a delete. Removing an owned Source is only possible in
  its home workspace.
• link resolves a chain of references at creation time and records the workspace
  that actually owns source.yaml, so runtime resolution is exactly one hop.
  Linking a target that is already linked is a notice rather than a failure;
  passing --alias explicitly creates a second local name for the same home and
  reports the existing one.
• A reference whose home cannot be reached fails locally. source status lists it
  as broken with the recorded target and the reason, commands on that alias fail
  with an error naming the repair, assay check reports it as a structure finding
  without scanning for the home or repairing it, and every other object in the
  workspace keeps working. A reference shell holding its own checkout/,
  content/, observations/, or captures/ is refused the same way, because a
  pointer plus material is two answers to where the Source lives.
• A rebuildable clone registry at ~/.assay/clone-registry.json
  (ASSAY_CLONE_REGISTRY overrides the location): entries of normalized origin
  URI, home workspace root, alias, and last_seen. source add, source link,
  and source sync write to it best-effort — a write that fails never affects the
  command. It buys three hints and no decisions: source add of an origin that
  already has a home prints an advisory naming that home and suggesting
  source link, then proceeds; source link <target-source> with the workspace
  omitted links directly when exactly one home verifies and lists the exact paths
  and stops when several do; a broken-reference error appends the registry's
  current location when one verifies. Every read re-verifies the workspace and
  alias and drops stale entries, it stores absolute machine-local paths while ref
  shells prefer relative ones, and it records homes only — never a consumer's
  pointer. Deleting the file loses those three hints and no facts.
• assay source capture <alias> [--note <text>] preserves a source's current
  bytes at captures/<id>/source with a sha256-tree-v1 integrity manifest. It
  works for either content mode and is the only routine command that hashes a tree.
• assay source import <alias> <dir-or-archive> [--note <text>] replaces a copied
  source's content. The bytes it is about to replace are captured first, so an
  import adds a record rather than destroying one.
• Evidence tiers are named in the semantics registry and the bundled skill: tier 0
  is the default record (alias, date, commit when there is one), tier 1 is identity
  (commit and origin, or a tree hash computed on demand for copied content), tier 2
  is an explicit capture. analysis close --exit adopt|reject suggests recording a
  tier-1 pin; it never requires one.
• assay source adoption remove <adoption> forgets a mapping. It deletes the
  record and nothing else; the material in the target system is the target
  project's and was never Assay's to write.
• assay source adoption take gained --note <text> for the rationale worth
  re-reading, and records a tier-1 identity pin without being asked: the comm...

Assay 0.13.0

Assay 0.13.0

Assay 0.13.0 replaces the 0.6 built-in workflow/runtime stack with a smaller,
local-first project evidence workbench. The release contract is exactly
0.13.0+s4+l8+r3: package 0.13.0, manifest schema 4, layout 8, and systems
registry schema 3.

This note covers the full change set since v0.6.0. Intermediate 0.7–0.13
candidates were never released and have no compatibility contract.

Native Project work

• Project is a native schema-1 object. project/project.yaml (or
  .assay/project/project.yaml in overlay mode) is the sole Project id/name
  authority.
• Task provides durable bounded-work identity with readable
  task-0001-<slug> ids, a closed task.json envelope, reader-owned prd.md,
  optional checkpoint/design/research material, explicit lifecycle and archive,
  exact host-context bindings, typed lineage relationships, and partial-health
  listing. Task does not own dispatch, permissions, project acceptance, or
  host runtime state.
• Roadmap provides readable roadmap-0001-<slug> ids, reader-owned outcome
  prose, independent state and horizon, validated dependency/replacement graphs,
  explicit Task links, revisions, archive, and partial-health reads. Roadmap and
  Task lifecycle never propagate into each other.
• Spec provides readable spec-0001-<slug> ids, a closed schema-1 envelope,
  reader-owned specification prose, draft/active/retired lifecycle, explicit
  replacement and archive, and digest-bound promotion provenance from an
  Analysis or approved Task file. Activation validates structure; it is not
  approval or Project acceptance.
• Readable ids are allocated across live and archived records, tolerate
  duplicate titles, and remain stable when titles change.

External Plugin metadata, not execution

• The former built-in plugin runtime is replaced by schema-1 external Plugin
  metadata under .assay/external-plugins.json.
• plugin register, observe, list, check, disable, enable, and
  remove validate and record descriptors, exact payload integrity, requested
  host surfaces, grants, observations, and Assay-owned contribution state.
• Assay does not fetch, install, activate, execute, supervise, or uninstall
  external payloads. Host execution and host-owned state remain outside Assay.
• The repository includes a descriptor-only generic fixture and an unpublished,
  metadata-only Ponytail adapter. Neither package contains executable Ponytail
  or host payload code.

Source convergence

• External evidence is consistently a Source. Living and frozen modes share
  the sources/<alias>/ namespace, observation/manifests/captures ledger, and
  Source-bound Analysis flow.
• The former Reference and Absorb command families, public schemas, templates,
  and help entries are removed. Layout 8 has no references path and current
  Templates do not scaffold Reference/Absorb records.
• Source observations no longer contain Analysis lifecycle state. Analysis
  close does not rewrite an observation; derived history.md and persisted
  comparison files are removed, while source diff derives comparisons from
  immutable manifests.
• status reports local upstream movement without network access; --fetch is
  explicit. source sync and switch preserve unrecorded managed-checkout work
  by failing before a destructive refresh.
• Adopted Source material is tracked only through assay source adoption ....
  Definitions, inspections, evidence, decisions, baselines, and rollback
  receipts use the assay.source-adoption-*/v1 schema family and lazy
  .assay/source-adoptions/ store.
• The earlier internal Donor module, diagnostics, schema tokens, and loose-state
  path are removed. No dual reader or migration writer exists for those
  unpublished candidate records.
• Overlay-to-standalone conversion preflights and preserves the current Source
  ledger and Source adoption receipt store without taking ownership of target
  System code.

Simpler Templates, manifest, and workspace index

• Built-in study, solve, and explore are one-shot Templates. A custom
  Template is an explicit YAML path with a closed schema; Template identity is
  not persisted or reloaded after expansion.
• Manifest schema 4 contains the literal framework version and exact layout-8
  resolver block. layout.entries stores only bounded paths expanded from the
  one-shot Template; fixed native/core paths are resolved rather than copied
  into the manifest.
• Retired manifest fields for minimum versions, Project identity, profiles or
  archetypes, capability modules, plugin declarations, and bindings are not
  accepted. External Plugin metadata has its own schema-1 store.
• Layout-8 path names describe the actual areas directly, including systems.
  No unpublished systems_contracts/systemsContracts alias remains.
• .assay/managed-files.json schema 1 is the independent no-clobber receipt for
  fixed core assets. It owns generator/asset identity, baseline hashes,
  protection, and executable metadata; the manifest does not.
• update reconciles only fixed core files. Template output and reader-owned
  Project artifacts remain outside managed overwrite behavior.
• Global workspace discovery is an explicit schema-1 index under
  ~/.assay/workspaces. Only workspace track, discover, and forget write
  it; lifecycle and read commands do not register, repair, or deduplicate
  workspaces implicitly. The former global projects store is not read or
  migrated.

Registry-canonical Systems

• .assay/systems-registry.json schema 3 is the sole Project-local System
  authority. The map key is the exact canonical selector; records hold only
  locator, lifecycle, VCS/version observations, and supersedes edges.
• Selectors are exact. Prefix fallback is removed.
• Assay does not create, parse, validate, refresh, move, or delete a
  system.yaml; such a file is ordinary System-owned content.
• system update --path changes only the registry locator. system archive --apply is a logical registry transition and never moves or deletes System
  bytes. The primary transition and supersedes graph remain registry operations.
• Standalone/overlay conversion preserves registered System content as opaque
  user/System bytes and rewrites only registry locators it owns.

Removed authorities and runtimes

• Native ADR is removed, including its index, commands, templates, provider
  responsibility, Source hints, and Intent-promotion target. Current normative
  contracts belong in native Specs; durable decisions and findings can remain
  in reader-owned Project prose, Analyses, and Knowledge.
• Iteration authority is removed: there is no layout path, command family, core
  API/type, template/profile module, status/check projection, Knowledge
  back-reference, conversion ownership, or root-discovery marker. Native Task
  owns bounded future work. solve attempts and explore trials remain
  Template-specific user work areas, not Iteration records.
• The native capability-module abstraction and product Intent are removed,
  including commands, manifest fields, archetype modules, scaffolds, gates,
  projections, events, capture/list/promotion/integrity, System authority,
  templates, zones, and conversion behavior. External descriptor capability
  requests remain opaque host metadata and grant no Assay authority. A manually
  created intent/ or .assay/intent/ directory is ordinary unowned content.
• The built-in Trellis runtime, protocols, channels, hooks, migrations, memory,
  plugin reconciliation, and execution surfaces are removed. Agent DAG,
  dispatch, permissions, and activation stay with the host; Relay retains its
  own fork/promotion semantics.
• Manual/freeform event commands and public event-append/capture exports are
  removed. Mutating core operations still append their automatic structured
  events internally.
• .assay/VERSION is removed. The exact framework version lives only in the
  schema-4 manifest envelope.
• There is no physical migration subsystem, native Intent compatibility layer,
  or host execution runtime hidden behind the retained commands.

Narrowed Analysis and Knowledge vocabularies

• analysis close --exit accepts exactly adopt, reject, or experiment;
  retired decision exits and ADR/Iteration coupling are absent.
• knowledge add accepts exactly pattern, guide, or troubleshooting;
  retired Knowledge types and Iteration back-references are absent.

Breaking cutover boundary

• Repository installation and the distributable core/CLI packages require
  Node.js >=22.13.0; repository workflows pin pnpm 11.3.0.
• Assay 0.13 reads only the exact current workspace tuple
  0.13.0+s4+l8; System operations additionally require registry r3.
• v0.6.0 workspaces and every unpublished intermediate candidate fail closed
  before semantic reads or writes. Core does not contain a legacy reader,
  in-place upgrader, dual writer, or downgrade path.
• Any retained workspace that must cross the boundary requires a separately
  reviewed external exact-pair cutover tool. This release does not claim that a
  real workspace migration was performed.
• Package metadata is set to 0.13.0. This repository note does not claim npm
  publication, tagging, deployment, or installation into a user environment.

Release verification

The repository release gate builds all packages, runs type checking, lint,
package tests, CLI smoke scenarios, disposable init/adopt flows, and the
committed public-example check. The public example is a sanitized generated
study workspace with no runtime ledgers or local systems registry.