v0.2.0 — capability/permission vocabulary split + manifest hardening (#3)

* refactor(rename): FeatureManifest -> CapabilityManifest (wave A.1 — manifest type)

* refactor(rename): Feature{Status,Record,Store} -> Capability* (wave A.2 — approval)

* refactor(rename): FeatureCapabilityRegistry -> PermissionRegistry (wave A.3 — registry)

* fix(rename): clean up remaining Feature* leftovers in fixture manifest + fixHint string

* refactor(rename): update agent-facing fixHint wording from 'feature' to 'capability' (wave A.5 — vocabulary follow-up)

* refactor(wave-b): rename inner-permission field `capabilities[]` -> `permissions[]` and error codes `capability.*` -> `permission.*`

- CapabilityManifest.capabilities -> .permissions (the Permission[] array)
- ActionManifest.capabilities -> .permissions (the PermissionId[] grant list)
- broker fields: capabilityId -> permissionId (NetworkBroker, StorageBroker, ClockBroker, AuditBroker, UiBroker)
- AuditTransport.emit envelope: capabilityId -> permissionId
- replay envelope: capabilityId -> permissionId
- CapabilityError -> PermissionError
- error code rename (inner-permission concerns):
    manifest.capabilities.* -> manifest.permissions.*
    action.capabilities.*   -> action.permissions.*
    action.capability_ref.* -> action.permission_ref.*
    capability.{not_object,type,duplicate_id,undeclared,denied,no_broker,action.*} -> permission.*
    capability.network.{hosts,host_value,methods,method_value,no_transport,bad_url,host_denied,method_denied} -> permission.*
    capability.storage.{mode,no_transport,read_denied,write_denied} -> permission.*
    capability.audit.no_transport -> permission.audit.no_transport
- fixHints updated to match new vocab
- fixture manifest.ts, smoke.ts, end-to-end.ts updated for field + code assertions

The outer 'capability' identifier (capabilityId, capabilityVersionHash, AuditEventKind 'capability_emit') is unchanged — that remains the manifest-level identifier per the v0.2 vocab split.

Breaking change: manifest hashes change (new shape). Existing approvals will fall back to 'submitted' on first run; require re-approval.

Gate: tsc=0, tests=737/737, demo=24/24.

* test(hardening): add failing tests for 5 manifest hardening checks (TDD red)

* feat(hardening): add manifest hardening checks (5 rules, errors + warnings)

- permission.reason.too_short: reason must be >=5 words
- action.description.too_short: action description must be >=5 words
- permission.network.host_wildcard: no '*' in network hosts
- permission.storage.scope_wildcard: no '*' in storage scope
- permission.reason.no_action_ref (warning): reason should mention a referencing action id

hardenManifest() lives in capability-manifest.ts alongside validateCapabilityManifest().

* feat(approval): wire hardenManifest() into submit(); add SubmitResult.warnings

submit() now runs hardening after structural validation. If any hardening
errors exist it throws ApprovalError on the first one. Warnings are
surfaced on the new SubmitResult shape (CapabilityRecord + warnings[]).

* chore(fixture): name referencing actions in each permission.reason

Clears the 7 permission.reason.no_action_ref warnings the hardening
checks would otherwise surface on the suspicious-transaction-triage demo.
Each reason now opens with 'Used by <action.id>' so an approver can trace
every grant to its caller.

* docs(readme): rewrite for v0.2 — show-by-failing 4-beat opener

- Locks the tagline: 'Writmint is a verifier for capabilities an author
  can't author past.'
- 4-beat opener: agent writes manifest with a wildcard host -> submit fails
  with the verified-real permission.network.host_wildcard error -> fix and
  resubmit -> run; every brokered call lands in the audit sink.
- Updates every API name to v0.2: CapabilityManifest, permissions[],
  MemoryCapabilityStore, createPermissionRegistry, PermissionError,
  permission.* error codes, capabilityId (outer wrapper field), scope.cap().
- Mentions hardenManifest() under pillar 1.
- Updates test count 737 -> 750.

* release: 0.2.0

CHANGELOG entry documents the inner/outer vocabulary split
(feature -> capability outer, capabilities[] -> permissions[] inner),
manifest hardening (5 rules), and the resulting hash shift requiring
re-submit + re-approve for any manifest carried over from v0.1.

package.json: version 0.1.0 -> 0.2.0; description rewritten around the
locked tagline; keywords swap feature-manifest/capability-scoping for
capability-manifest/permission-scoping and add manifest-hardening.

---------

Author: razukc

CHANGELOG.md

@@ -4,6 +4,102 @@ All notable changes to Writmint will land here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] — 2026-05-15
+
+A **breaking** release. The public API splits its vocabulary into an outer
+identity layer (the *capability* — the manifest as a unit of governance)
+and an inner permission layer (the individual grants the manifest
+declares). Adds manifest hardening that runs at submit-time so an agent
+gets a structured rejection before approval, not after.
+
+### Breaking changes
+
+#### Outer identity layer renamed: feature → capability
+
+The manifest itself, the lifecycle around it, and the audit envelope all
+move to *capability* vocabulary.
+
+| v0.1 | v0.2 |
+|---|---|
+| `FeatureManifest` | `CapabilityManifest` |
+| `MemoryFeatureStore` | `MemoryCapabilityStore` |
+| `FeatureStore` interface | `CapabilityStore` |
+| `FeatureRecord` | `CapabilityRecord` |
+| `FeatureStatus` | `CapabilityStatus` |
+| `ApproveInput.featureId` | `ApproveInput.capabilityId` |
+| `AuditEvent.featureId` / `featureVersionHash` | `AuditEvent.capabilityId` / `capabilityVersionHash` |
+| `AuditEventKind` value `feature_emit` | `capability_emit` (and `capability_call` / `capability_denied`) |
+| error code `approval.unknown_feature` | `approval.unknown_capability` |
+| `src/feature-manifest.ts` | `src/capability-manifest.ts` |
+
+#### Inner permission layer renamed: capabilities[] → permissions[]
+
+Inside the manifest, what v0.1 called *capabilities* (one per permission
+grant) is now *permissions*. The error vocabulary follows.
+
+| v0.1 | v0.2 |
+|---|---|
+| `CapabilityManifest.capabilities[]` (was on FeatureManifest) | `permissions[]` |
+| `ActionManifest.capabilities[]` | `permissions[]` |
+| `CapabilityError` class | `PermissionError` |
+| broker envelope field `capabilityId` (inner) | `permissionId` |
+| `AuditTransport.emit({capabilityId,…})` | `AuditTransport.emit({permissionId,…})` |
+| `createFeatureCapabilityRegistry()` | `createPermissionRegistry()` |
+| `src/capabilities.ts` | `src/permissions.ts` |
+| `capability.*` error codes (`capability.denied`, `capability.network.host_denied`, `capability.storage.write_denied`, `capability.undeclared`, `capability.action.unknown`, `capability.audit.no_transport`, …) | `permission.*` (same suffixes) |
+| `manifest.capabilities.type` validator code | `manifest.permissions.type` |
+| `action.capability_ref.type` / `.unknown` | `action.permission_ref.type` / `.unknown` |
+
+The outer `capabilityId` on `AuditEvent` is the manifest identity; the
+inner `permissionId` (also on `AuditEvent`, and on the broker emit
+envelope) is the specific permission entry the event came through. Both
+fields ride on every event.
+
+#### Hash shift
+
+`hashManifest()` is unchanged in algorithm, but every shipped manifest
+will produce a different `versionHash` under v0.2 because the renamed
+object keys (`permissions[]`, etc.) are part of the canonical hash input.
+**Re-submit and re-approve any manifest carried over from v0.1.**
+
+### Added
+
+- **`hardenManifest()`** (`src/capability-manifest.ts`) — runs after
+  structural validation. Enforces five strictness rules that an approver
+  would otherwise have to check by eye:
+  - `permission.reason.too_short` — every `reason` must be ≥ 5 words.
+  - `action.description.too_short` — every action `description` must be
+    ≥ 5 words.
+  - `permission.network.host_wildcard` — no `*` in any allowed host.
+  - `permission.storage.scope_wildcard` — no `*` in any storage scope.
+  - `permission.reason.no_action_ref` (warning) — every permission's
+    reason should mention at least one action that references it.
+- **`ApprovalLifecycle.submit()`** now runs `hardenManifest()` and throws
+  `ApprovalError` on the first hardening error. The new return shape
+  `SubmitResult` extends `CapabilityRecord` with a `warnings:
+  ManifestWarning[]` field carrying non-blocking signals (e.g. the
+  no-action-ref warning).
+- 13 new tests covering each hardening rule (positive + negative) and
+  `submit()` wiring. Total test count: **737 → 750**.
+- README rewritten around a *show-by-failing* opener: the agent writes a
+  manifest with a wildcard host, `submit()` rejects it with a verified
+  structured error, the agent fixes and resubmits. Locks the tagline:
+  *"Writmint is a verifier for capabilities an author can't author past."*
+
+### Changed
+
+- `fixtures/suspicious-transaction-triage/manifest.ts` — every
+  `permission.reason` now opens with "Used by `<action.id>`…" so the
+  fixture passes hardening with **0 errors, 0 warnings**.
+
+### Notes
+
+- Pre-stable. Public API surface may change before v1.0.
+- Requires Node ≥ 22.
+- All 24 demo phases still pass.
+
+[0.2.0]: https://github.com/razukc/writmint/releases/tag/v0.2.0
+
 ## [0.1.0] — 2026-05-01
 
 Initial release. Five pillars + the canonical triage demo.