@cassiomc1/forgeloop 1.5.0 → 1.6.1

package/CONTRACT_COVERAGE.md

@@ -14,6 +14,7 @@ coverage.
 | Required artifact freshness | `readRequiredArtifactFingerprints`, `classifyLoadedWorkState` | `tests/checkpoint-freshness.test.js`, `tests/validate-protocol-cli.test.js` | matching hash, missing, and changed artifact cases |
 | Schema health | `inspectSchemaHealth` | `tests/schema-health.test.js` | missing, invalid, and unsupported-version schemas |
 | Evidence vocabulary | `src/core/evidence.js` | `tests/evidence.test.js` | unknown kind and incomplete record |
+| Verification execution isolation | `src/core/verification-execution.js`, `src/core/runtime-context.js` | adapter call binding, disposable cwd, timeout/termination/truncation preservation, and canonical isolation combinations in `tests/verification-execution-isolation.test.js` | missing adapter under required policy, malformed/contradictory isolation metadata, and live-root cwd claims in `tests/verification-execution-isolation.test.js` |
 | Receipt semantics | `src/core/receipt.js` | `tests/receipt-semantics.test.js` | unsupported publication, review, check, and completion claims |
 | Cross-artifact conformance | `src/core/conformance.js`, `src/commands/validate-protocol.js` | `tests/conformance.test.js`, `tests/validate-protocol-cli.test.js` | `stateClassification`, derived stale details, precedence, mismatch, incomplete, and incompatible fixtures |
 | Delegation conflicts | `src/core/delegation.js` | `tests/delegation-set.test.js` | WRITE/WRITE, WRITE/READ, unknown dependency, and cycle cases |

package/DOCS_INDEX.md

@@ -18,12 +18,16 @@ integration and guide context. Use this map before editing documentation.
 | Cross-harness continuity | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) | Operational handoff and multi-tool resumption |
 | CLI command reference | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Full syntax, options, and JSON examples for all commands |
 | Artifact and schema reference | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) | Purpose, mutability, and trust classifications of `.forgeloop/` |
+| Durable actions and trajectory evidence | [`docs/EXECUTION_TRACE.md`](./docs/EXECUTION_TRACE.md) and [`docs/RECIPES.md`](./docs/RECIPES.md) | Action provenance, reconciliation, metrics, and project-local evaluation |
 | Troubleshooting and recovery | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) | Symptom-first recovery and stable error code reference |
 | Operational recipes | [`docs/RECIPES.md`](./docs/RECIPES.md) | Short copy-paste recipes for daily workflows |
+| Diagnostic model | [`docs/DIAGNOSTIC_MODEL.md`](./docs/DIAGNOSTIC_MODEL.md) | Structured diagnostic cases, interventions, hypothesis dispositions, information gain |
+| Execution trace and observability | [`docs/EXECUTION_TRACE.md`](./docs/EXECUTION_TRACE.md) | `history`, `trace`, `reflect`, and task-level `inspect` read-only projections |
 | Universal integration API | [`docs/UNIVERSAL_INTEGRATION.md`](./docs/UNIVERSAL_INTEGRATION.md) | Programmatic integration subpath, envelope semantics, and consumer map |
 | Local-first MCP adapter | [`docs/MCP.md`](./docs/MCP.md) | stdio default, optional strict loopback HTTP; server modes/capabilities and canonical resources |
 | Documentation guide | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) | Rules and checklist for modifying documentation |
-| ForgeLoop 1.5/MCP release checklist | [`docs/RELEASE_CHECKLIST_1_5_MCP.md`](./docs/RELEASE_CHECKLIST_1_5_MCP.md) | Integration API v1, MCP package, and publication gates |
+| ForgeLoop 1.6.1 release checklist (current) | [`docs/RELEASE_CHECKLIST_1_6_1.md`](./docs/RELEASE_CHECKLIST_1_6_1.md) | Verification adapter boundary, isolation invariants, and publication gates |
+| ForgeLoop 1.5/MCP release checklist (historical) | [`docs/RELEASE_CHECKLIST_1_5_MCP.md`](./docs/RELEASE_CHECKLIST_1_5_MCP.md) | Integration API v1, MCP package, and publication gates |
 | ForgeLoop 1.4 release checklist | [`docs/RELEASE_CHECKLIST_1_4.md`](./docs/RELEASE_CHECKLIST_1_4.md) | Claim-recovery, compatibility, package, and publication gates |
 | Lifecycle, gates, planning, verification, and recovery | [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) | Normative process for agents and developer workflows |
 | Capability levels, discovery, and degradation | [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) | Vendor-neutral harness contract |
@@ -34,7 +38,9 @@ integration and guide context. Use this map before editing documentation.
 | Artifact and phase schemas | [`schemas/`](./schemas/) and [`CONTRACT_COVERAGE.md`](./CONTRACT_COVERAGE.md) | Versioned machine-readable contract |
 | CLI/package behavior | [`src/`](./src/) and [`tests/`](./tests/) | Executable implementation and regression evidence |
 | Guide content | [`ENG/`](./ENG/) | Context-specific, English-only operational guides |
-| Diagram | [`docs/forgeloop-flow.mmd`](./docs/forgeloop-flow.mmd) | Canonical Mermaid source; SVG is generated output |
+| Diagram governance | [`docs/diagrams/manifest.json`](./docs/diagrams/manifest.json) | Authoritative taxonomy, renderer mapping, canonical purposes, artifact ownership, and references |
+| Diagram maintainer entrypoint | [`docs/diagrams/README.md`](./docs/diagrams/README.md) | Typed Archify source, animated HTML explorer, animated SVG fallback, review, and regeneration workflow |
+| Real Execution Proof of Concept (PoC) | [`poc/README.md`](./poc/README.md) | Non-normative, reproducible public engineering workload, audit evidence, and technical audit. Normative behavior remains owned by [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md). |
 
 ## Audience map
 
@@ -42,6 +48,7 @@ integration and guide context. Use this map before editing documentation.
 | --- | --- |
 | **First-time user or developer** | [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md) |
 | **AI coding agent / harness** | [`AGENTS.md`](./AGENTS.md) → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) |
+| **Technical auditor / Evaluator** | [`poc/README.md`](./poc/README.md) → [`poc/reports/poc-20260826-real-execution-technical-audit-v2.md`](./poc/reports/poc-20260826-real-execution-technical-audit-v2.md) |
 | **Harness integrator** | [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) |
 | **External runtime / orchestrator integrator** | [`ORCHESTRATOR_INTEGRATION.md`](./ORCHESTRATOR_INTEGRATION.md) |
 | **Resuming another tool / session** | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) |
@@ -50,7 +57,8 @@ integration and guide context. Use this map before editing documentation.
 | **Fixing a broken or stale state** | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) |
 | **Looking for quick recipes** | [`docs/RECIPES.md`](./docs/RECIPES.md) |
 | **Documentation contributor** | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) |
-| **Release maintainer (current)** | [`docs/RELEASE_CHECKLIST_1_5_MCP.md`](./docs/RELEASE_CHECKLIST_1_5_MCP.md) |
+| **Release maintainer (current)** | [`docs/RELEASE_CHECKLIST_1_6_1.md`](./docs/RELEASE_CHECKLIST_1_6_1.md) |
+| **Release maintainer (historical 1.5/MCP)** | [`docs/RELEASE_CHECKLIST_1_5_MCP.md`](./docs/RELEASE_CHECKLIST_1_5_MCP.md) |
 | **Release maintainer (historical 1.4)** | [`docs/RELEASE_CHECKLIST_1_4.md`](./docs/RELEASE_CHECKLIST_1_4.md) |
 | **Protocol architect / maintainer** | [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) + [`schemas/`](./schemas/) |
 | **Security auditor** | [`THREAT_MODEL.md`](./THREAT_MODEL.md) |
@@ -59,6 +67,7 @@ integration and guide context. Use this map before editing documentation.
 ## Task map
 
 - **Start my first task**: [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md)
+- **Inspect real execution PoC and audit evidence**: [`poc/README.md`](./poc/README.md)
 - **Resume after switching tools**: [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md)
 - **Check CLI options and syntax**: [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
 - **Understand what `.forgeloop/` stores**: [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md)
@@ -88,25 +97,26 @@ process into adapters or README sections; link to the canonical source.
 ## Verification and release
 
 The Node regression suite, ESLint, c8, dependency policy, package boundary,
-and Mermaid render are the local executable checks. Python validators remain
+and Archify diagram render are the local executable checks. Python validators remain
 frozen CI-only compatibility tools because they cover historical Markdown,
 loop, and secret-scanning contracts that have not been migrated to Node. Their
 scope, exact commands, and migration boundary are recorded in
 [`scripts/CI_VALIDATORS.md`](./scripts/CI_VALIDATORS.md).
 
 The package has no runtime dependencies. Development dependencies are limited
-to ESLint, c8, and Mermaid CLI and are checked by
+to ESLint and c8 and are checked by
 `npm run dependency:policy`. GitHub Actions use `npm ci`, pinned action SHAs,
 CodeQL, dependency review, and generated-release notes; npm publication still
 uses trusted OIDC publishing and is not implied by local verification.
 
 ## Editing rules
 
-- Keep lifecycle prose, the Mermaid source, and the text-only README fallback
-  synchronized.
-- Keep generated `docs/assets/forgeloop-flow.svg` synchronized with the Mermaid
-  source by running `npm run docs:flow` and `npm run docs:check`. CI validates
-  the source fingerprint instead of comparing renderer-specific SVG geometry.
+- Keep lifecycle prose, the typed Archify source, generated outputs, and the
+  text-only README fallback synchronized.
+- Keep the generated HTML, SVG, and receipt synchronized with the Archify
+  source by running `npm run docs:diagrams` and `npm run docs:check`. CI
+  validates the renderer pin, source fingerprint, artifact hashes, and SVG
+  safety constraints.
 - Preserve the distinction between implemented behavior, local evidence, and
   external publication or production state.
 - Run `npm run lint`, `npm run coverage`, `npm run pack:check`, and the Python

package/EXECUTION_STATE.md

@@ -179,3 +179,23 @@ repository context and is always operational context rather than evidence.
 | Stale | Any | Changed | Run `forgeloop route` and `forgeloop preflight` to revalidate |
 | Invalid / Corrupted | Any | Any | Fail closed; inspect errors via `forgeloop doctor --json` |
 | Different Task ID | Present | Any | Do not merge contexts; clear or finish previous task first |
+
+## Durable actions are a separate external-state checkpoint
+
+Action artifacts under `actions/` describe side-effect intent and its canonical
+state; they do not replace `work-state.json`. Approval artifacts bind a single
+decision to the exact action fingerprint, contract fingerprint, task revision,
+and capability. Capability policy is configuration, not host authority.
+
+`FORGELOOP_EXECUTED` means ForgeLoop launched exact argv through `run-action`;
+`HOST_REPORTED` means an external host performed the operation; and
+`EXTERNAL_OBSERVED` means a later observation supplied reconciliation evidence.
+If the external outcome is uncertain, the action is `COMMIT_UNKNOWN`. It must
+not be retried or used to satisfy required completion until
+`forgeloop action-reconcile` records `COMMITTED`, `NOT_COMMITTED`, or
+`UNKNOWN`. ForgeLoop does not claim universal exactly-once execution.
+
+`metrics` and `eval` read the canonical trace, reflection, action artifacts, and
+ledger events. They never mutate lifecycle truth, invent usage/cost data, or
+create a second execution history; reference efficiency is emitted only when a
+project-local scenario provides comparable steps.

package/LOOP_ENGINEERING.md

@@ -27,6 +27,7 @@
 - [Precedence & Stop Conditions](#precedence)
 - [Final Delivery](#final-delivery)
 - [Cross-Harness Continuity](#cross-harness-execution-continuity)
+- [Durable Actions and Trajectory Evidence](#durable-actions-and-trajectory-evidence)
 - [Multi-Task Concurrent Project State](#multi-task-concurrent-project-state)
 
 ## Protocol applicability
@@ -148,7 +149,7 @@ Every verification command path is classified by resolution mode:
 
 **Validator-enforced rule**: Any verification command executed via an installation-capable or explicit-installation resolution mode without a valid canonical installation authority grant is rejected by `record-check`, `audit`, and `complete` with error code `E_INSTALLATION_AUTHORITY_REQUIRED`, `E_AUTHORITY_INVALID`, `E_AUTHORITY_SCOPE_MISMATCH`, or `E_AUTHORITY_UNTRUSTED_SOURCE` and cannot contribute to `VALID` completion.
 
-Recognized command dispatchers (such as `npm test`, `npm start`, `npm stop`, `npm restart`, `npm run <script>`, `npm run-script <script>`, `npm rum <script>`, `npm urn <script>`) are classified by their effective package resolution behavior across recognized lifecycle scripts before process launch. npm invocation parsing recognizes options (e.g. `--silent`, `--loglevel=error`) before the subcommand. Recognized npm-script dispatch is resolved recursively before process launch. `npm restart` uses npm's restart-specific lifecycle semantics (`prerestart`, `prestop`, `stop`, `poststop`, `prestart`, `start`, `poststart`, `postrestart` when `restart` is absent; `prerestart`, `restart`, `postrestart` when `restart` is present) rather than generic pre/main/post handling. ForgeLoop fails closed (`mayInstall: true`) when recursive npm-script resolution encounters a cycle or exceeds its maximum resolution depth (16). ForgeLoop does not resolve npm workspace selection in `run-check` for `0.1.15`. npm script executions using `--workspace`, `-w`, `--workspaces`, or `--ws` fail closed (`E_COMMAND_RESOLUTION_AMBIGUOUS`) because the effective `package.json` execution context may differ from the current ForgeLoop target. Run ForgeLoop against the selected workspace directory directly instead. If any nested lifecycle script invokes an installation-capable command (such as `npx`, `npm exec`, or `pnpm dlx`), the execution is elevated to `INSTALL_CAPABLE_RESOLUTION` and blocked before launch without authority.
+Recognized command dispatchers (such as `npm test`, `npm start`, `npm stop`, `npm restart`, `npm run <script>`, `npm run-script <script>`, `npm rum <script>`, `npm urn <script>`) are classified by their effective package resolution behavior across recognized lifecycle scripts before process launch. npm invocation parsing recognizes options (e.g. `--silent`, `--loglevel=error`) before the subcommand. Recognized npm-script dispatch is resolved recursively before process launch. `npm restart` uses npm's restart-specific lifecycle semantics (`prerestart`, `prestop`, `stop`, `poststop`, `prestart`, `start`, `poststart`, `postrestart` when `restart` is absent; `prerestart`, `restart`, `postrestart` when `restart` is present) rather than generic pre/main/post handling. ForgeLoop fails closed (`mayInstall: true`) when recursive npm-script resolution encounters a cycle or exceeds its maximum resolution depth (16). ForgeLoop does not resolve npm workspace selection in `run-check`. npm script executions using `--workspace`, `-w`, `--workspaces`, or `--ws` fail closed (`E_COMMAND_RESOLUTION_AMBIGUOUS`) because the effective `package.json` execution context may differ from the current ForgeLoop target. Run ForgeLoop against the selected workspace directory directly instead. If any nested lifecycle script invokes an installation-capable command (such as `npx`, `npm exec`, or `pnpm dlx`), the execution is elevated to `INSTALL_CAPABLE_RESOLUTION` and blocked before launch without authority.
 
 **npm Classification Model**: npm classification is semantic and fail-closed. Unknown npm commands are not assumed safe. The classifier specifically identifies install-capable families including: `exec`/`x`, `install` aliases, `ci` aliases, `install-test` families, `install-ci-test` families, `update` aliases, `audit fix`, and conditional `init`/`create`/`innit` invocations. Unknown or ambiguous semantics fail closed (`E_COMMAND_RESOLUTION_AMBIGUOUS`).
 
@@ -161,6 +162,27 @@ resolution is rejected without a valid host-attested authority, while
 `npx --no-install` remains a non-installing path and may fail honestly when a
 tool is absent. `run-check` launches the supplied argv without a shell.
 
+### Verification execution isolation
+
+Without a trusted adapter, verification executes in the live project and is
+recorded as `NATIVE_PROJECT` (`isolated: false`, `liveProjectWritable: true`,
+inherited network and environment). A host may supply a trusted verification
+execution adapter and an isolation policy through the integration runtime
+context (`verificationExecutionAdapter`, `verificationExecutionPolicy`).
+The policy modes are `NONE`, `NATIVE_PROJECT`, `PROJECT_ISOLATED`
+(`isolated: true`, `liveProjectWritable: false`), and `SYSTEM_ISOLATED`
+(additionally `networkPolicy: DENIED`). `liveProjectWritable` is an enforced
+host guarantee reported by the adapter, not an inference from a different
+working directory, and a disposable copy alone does not satisfy filesystem
+isolation. Isolated execution must use a working directory separate from the
+protocol project root. Contradictory isolation metadata is intrinsically
+rejected before evidence persistence with `E_VERIFICATION_EXECUTION_INVALID`,
+and verification that cannot satisfy the required isolation boundary fails
+closed with `E_VERIFICATION_ISOLATION_UNAVAILABLE` instead of running in the
+live project. ForgeLoop owns the adapter contract and evidence semantics; the
+harness owns the concrete isolation backend and no specific backend is
+normative.
+
 `forgeloop record-check` is serialization-only. Its `--command` value is
 metadata and is never executed. A `kind: command`, `evidenceKind: OBSERVED`
 check must carry `provenance: FORGELOOP_EXECUTED` and a valid `executionRef`;
@@ -1278,6 +1300,86 @@ completion. `CONTINUITY_CANNOT_GRANT_AUTHORITY`: continuity cannot authorize an
 installation or external action. <a id="FL-CONT-001"></a> **FL-CONT-001 — A receiving harness MUST reconcile**
 continuity against the current work state and checkout before acting on it.
 
+## Durable Actions and Trajectory Evidence
+
+Durable actions extend the existing task protocol; they do not turn ForgeLoop
+into an agent runtime, scheduler, queue, or workflow engine. Action intent,
+approval, execution provenance, reconciliation, and evaluation are task-local
+artifacts whose chronology remains in the same hash-chained `events.ndjson`.
+
+Every side-effecting action declares an explicit capability, effect class,
+bounded target, immutable idempotency key, and provenance. Project capability
+policy is a decision input (`ALLOW`, `DENY`, `REQUIRE_AUTHORITY`, or
+`REQUIRE_APPROVAL`); it is never host authority. `HOST_ATTESTED` authority can
+only cross the existing host trust boundary, and `run-action` accepts exact
+argv with no shell mode.
+
+### Durable action trust boundaries (hardened)
+
+The following invariants are enforced in core code and are regression-tested:
+
+- **Authorization is canonical.** No caller-controlled surface (`action-record`,
+  CLI flags, MCP tool arguments, project files, environment) can mint
+  `AUTHORIZED`. Only the core authorization service may transition
+  `PROPOSED -> AUTHORIZED` — through `run-action`, or explicitly through
+  `forgeloop action-authorize`, which is a pure adapter over the same service —
+  and only after the current capability policy, the persisted policy lock, and
+  the task policy snapshot agree. Every modern
+  `ACTION_AUTHORIZED` event binds the capability decision, capability-policy
+  fingerprint, policy-lock digest, task-policy digest, and — for
+  `REQUIRE_AUTHORITY`/`REQUIRE_APPROVAL` — the exact host authority or
+  fingerprint-bound approval. Post-authorization mutation of a bound approval
+  artifact is readiness/audit-visible.
+- **Verification is canonical, independent, and requirement-bound.**
+  `COMMITTED != VERIFIED`. A command exiting 0 proves only local completion.
+  `VERIFIED` is produced exclusively by `forgeloop action-verify` (or the
+  equivalent core service) against a passed ForgeLoop execution artifact that
+  is independent of the action's own commit execution and whose immutable
+  `requirement` exactly equals the action's requirement. New required actions
+  must declare a non-empty requirement at proposal time; historical required
+  artifacts without one remain readable but can never become trusted-satisfied.
+- **Reconciliation has exactly one replay truth.** A trusted `COMMITTED`
+  settlement emits `ACTION_RECONCILED(outcome=COMMITTED)` (the transition) plus
+  a same-revision informational mirror `ACTION_COMMIT_RECORDED(reconciled=true)`
+  (corroboration only). Ledger replay applies the transition exactly once and
+  validates mirror identity; forged or orphaned mirrors invalidate the ledger.
+- **Completion consumes readiness.** Required-action completion truth comes
+  from the canonical action-readiness projection, never from raw state labels.
+  A forged or legacy `VERIFIED` label without trusted authorization and
+  canonical verification evidence yields `UNTRUSTED` and blocks completion.
+- **Settling ambiguity requires trust.** Recording an `UNKNOWN`
+  reconciliation observation is always safe. Settling `COMMIT_UNKNOWN` as
+  `COMMITTED` or `NOT_COMMITTED` requires a trusted out-of-band host authority
+  context plus bounded evidence references bound to the event. Trusted
+  `NOT_COMMITTED` returns the action to `PROPOSED`, so any retry re-evaluates
+  policy, approval, authority, and the task policy snapshot; stale
+  authorization can never be reused.
+- **STARTED marks the launch boundary.** Deterministic pre-launch checks
+  (argv normalization, command resolution, installation authority, policy
+  identity, approvals) all run before `ACTION_STARTED`; post-start outcomes
+  remain conservative: spawn failure without launch is `FAILED`; anything
+  unproven is `COMMIT_UNKNOWN`.
+- **Capability policy participates in policy identity.** When
+  `.forgeloop/policy/capabilities.json` exists, its digest participates in the
+  policy lock, the active task policy snapshot, and authorization evidence.
+  Drift blocks before any side effect (`E_ACTION_POLICY_DRIFT`).
+- **Host context is out-of-band.** Trusted authority travels as an execution
+  context object supplied by an embedding host (`executeForgeLoopCommand` /
+  `createForgeLoopMcpServer({ authorityContextProvider })`). CLI flags such as
+  `--authority HOST_ATTESTED` are requested kinds, never proof. MCP launch
+  flags expose transport surfaces only; tool arguments can never carry
+  `authorityContext`.
+- **Guidance never lies about authority.** `forgeloop next` returns a
+  structured `authorityRequired` requirement for host-bound approvals instead
+  of recommending a command that cannot satisfy the blocker.
+
+Trajectory metrics and reference evaluations are read-only projections over the
+canonical trace, reflection, actions, and events. Missing tokens, costs,
+provider, model, or optimal-path data remain `null`/`UNKNOWN`; a comparative
+efficiency ratio exists only when a project-local reference scenario supplies
+`reference.comparableSteps`. Existing information-gain, intervention, failure
+signature, and oscillation diagnostics remain canonical.
+
 ## Multi-task concurrent project state
 
 ForgeLoop supports isolated, concurrent tasks within the same repository workspace.

package/LOOP_SYSTEM_DESIGN.md

@@ -442,3 +442,35 @@ machine and not a general memory subsystem. Work state owns lifecycle truth;
 the checkout owns implementation truth; checks/executions own verification
 truth; completion owns certification. Continuity only narrows what a receiving
 executor should inspect and continue.
+
+## Durable action and trajectory boundary
+
+Durable actions are protocol-owned task artifacts (`actions/`, `approvals/`,
+and `evaluations/`) projected through the existing hash-chained event ledger.
+They record intent, capability policy, approval binding, execution provenance,
+commit uncertainty, reconciliation, and verification without introducing a
+workflow runtime, scheduler, queue, or second ledger.
+
+The external side-effect boundary is deliberately conservative: exact argv is
+launched only through `run-action` with no shell mode; project capability
+policy cannot manufacture `HOST_ATTESTED` authority, and trusted host context
+travels out-of-band only (never inside command input, CLI flags, or tool
+arguments). Authorization and verification are canonical core services:
+callers cannot mint `AUTHORIZED` or `VERIFIED`, verification requires an
+independent passed ForgeLoop execution artifact, and required completion
+consumes the canonical action-readiness projection rather than raw state
+labels. Capability policy participates in policy identity: its digest is bound
+into the policy lock, the task policy snapshot, and authorization evidence, so
+drift blocks before any side effect. A started action whose external result is
+uncertain becomes `COMMIT_UNKNOWN`, which forbids retry until explicit
+reconciliation; settling ambiguity as `COMMITTED`/`NOT_COMMITTED` requires
+trusted host attestation plus evidence, and a trusted `NOT_COMMITTED` returns
+the action to `PROPOSED` so stale authorization can never be reused. This
+reduces duplicate-effect risk but cannot provide a universal exactly-once
+guarantee for arbitrary external systems.
+
+Metrics and trajectory evaluation are deterministic read-only projections of
+canonical trace/reflection evidence. They preserve unknown usage values and
+only compare efficiency when a project-local reference scenario exists. The
+existing diagnostic and reflection model remains the authority for information
+gain, intervention effectiveness, failure signatures, and oscillation.

package/PROTOCOL_INTEGRATION.md

@@ -204,6 +204,50 @@ metadata. Invalid or missing references return `E_EXECUTION_REF_INVALID`; an
 observed command without ForgeLoop provenance returns
 `E_COMMAND_PROVENANCE_UNATTESTED`.
 
+### Verification execution adapter boundary
+
+Verification execution is separated from protocol state through a trusted
+adapter boundary. A host supplies both through the integration runtime
+context, and neither is accepted as CLI flags, input, or project files:
+
+```js
+createForgeLoopContext({
+  verificationExecutionAdapter: { execute: async (request) => { /* ... */ } },
+  verificationExecutionPolicy: { requiredIsolation: "PROJECT_ISOLATED" },
+});
+```
+
+The adapter receives a frozen request (`argv`, `protocolProjectRoot`, `taskId`,
+`checkId`, `requirement`, `timeoutMs`, `resolution`) and returns the execution
+result plus isolation metadata. Isolation modes are:
+
+| Mode | `isolated` | `liveProjectWritable` | Network/environment |
+| --- | --- | --- | --- |
+| `NATIVE_PROJECT` | `false` | `true` | Inherited |
+| `PROJECT_ISOLATED` | `true` | `false` | Adapter-declared policy |
+| `SYSTEM_ISOLATED` | `true` | `false` | `networkPolicy: DENIED` required |
+
+ForgeLoop owns the adapter contract and evidence semantics; the harness owns
+the concrete isolation backend, and no specific backend is normative in
+ForgeLoop core documentation. The boundary is fail-closed:
+
+- isolation metadata must be internally consistent with its declared mode
+  (`NATIVE_PROJECT` is never isolated; isolated modes are never
+  `liveProjectWritable`; `SYSTEM_ISOLATED` never inherits network access).
+  Contradictory metadata is rejected with `E_VERIFICATION_EXECUTION_INVALID`
+  before evidence persistence;
+- isolated execution must use a working directory separate from the protocol
+  project root;
+- verification that cannot satisfy the required isolation boundary fails with
+  `E_VERIFICATION_ISOLATION_UNAVAILABLE` and must never fall back to running
+  in the live project.
+
+`protocol-info --json` advertises this capability as
+`features.verificationExecutionIsolation` (version 1), including the supported
+modes and the `protocolProjectRootSeparateFromExecutionCwd` invariant. The
+modes, public error codes, and `createForgeLoopContext` are exported from
+`@cassiomc1/forgeloop/integration`.
+
 ## Missing tool capability
 
 A missing tool is a capability gap, not installation authority.
@@ -277,6 +321,31 @@ configuration
 trust
 ```
 
+For durable actions, trusted host authority travels **out-of-band** through the
+programmatic integration API:
+
+```js
+await executeForgeLoopCommand({
+  command: "approval-resolve",
+  projectPath,
+  input: { /* actor-controlled command input only */ },
+  authorityContext: trustedHostContext, // host-supplied, never from input
+});
+```
+
+`authorityContext` and `runtimeContext` are separate executor parameters; they
+are never merged into `input`, never accepted as tool arguments, and cannot be
+minted by CLI flags, project files, environment variables, or transport
+sessions. MCP embeddings supply an immutable provider instead:
+
+```js
+createForgeLoopMcpServer({
+  projectPath,
+  allowApprovalResolution: true,      // transport surface only
+  authorityContextProvider: async ({ command }) => trustedContextOrNull,
+});
+```
+
 The host-attested source must still resolve outside the actor-writable target. A
 project-local authority reference may identify a grant, but it does not create
 the root of trust.
@@ -396,3 +465,24 @@ hosts remain fully supported through the CLI and instruction adapters.
 requires ForgeLoop 1.4.0 or newer.
 <a id="FL-CLAIM-003"></a> **FL-CLAIM-003 — A reader without `validatedClaimProjection=true` MUST fail closed**
 and must not mutate claims.
+
+## Durable actions and authority boundary
+
+Durable action support is additive to the integration contract. Read-only
+resources may expose action, approval, metrics, evaluation, and capability
+policy projections, but an integration must not treat transport metadata,
+session IDs, project policy, or actor prose as host authority. `HOST_ATTESTED`
+is accepted only from the existing host trust boundary.
+
+`run-action` is an exact-argv surface with no shell mode. Hosts that perform an
+operation themselves must record it as `HOST_REPORTED`; external observations
+used to settle uncertainty are `EXTERNAL_OBSERVED`. A started action whose
+external outcome cannot be proven is `COMMIT_UNKNOWN`: integrations must surface
+`E_ACTION_RECONCILIATION_REQUIRED` and must not retry automatically. The only
+forward path is explicit `action-reconcile` with bounded evidence.
+
+Trajectory metrics and evaluations are read-only projections over canonical
+events and trace/reflection data. Missing token/cost/model data remains unknown,
+and efficiency is comparable only when a project-local scenario supplies a
+positive reference step count. ForgeLoop remains an evidence protocol, not an
+agent runtime or workflow engine.

package/QUALITY_SCORECARD.md

@@ -31,6 +31,8 @@ policy are all present.
 | Contextual frontend taste | Taste is routed only to applicable premium frontend work, remains advisory, respects accessibility/performance/evidence, and has attribution without runtime dependency. |
 | Multi-agent coordination | Self-contained briefs, write/write and write/read ownership checks, dependency-set validation, reviewer independence, normalized results, and inline fallback. |
 | Security boundaries | Realpath containment, bounded untrusted JSON, threat model, nested secret scanning, publication evidence, and explicit authority rules. |
+| Durable external actions | Immutable action identity, idempotency conflict rejection, capability policy, fingerprint-bound approvals, exact-argv provenance, `COMMIT_UNKNOWN` reconciliation, completion blocking, and audit evidence. |
+| Trajectory evaluation | Read-only trace/reflection metrics, unknown usage preservation, canonical comparable-step definition, and scenario-bound efficiency without an arbitrary overall score. |
 | Maintenance quality | Small modules, built-in runtime, deterministic JSON contracts, malformed/version fixtures, package gates, and backward-compatible protocol versions. |
 
 ## Score rules

package/README.md

@@ -28,6 +28,7 @@ relevant guides.
 ## Where should I start?
 
 - **New to ForgeLoop** → [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md)
+- **Inspect a real ForgeLoop execution** → [`poc/README.md`](./poc/README.md)
 - **Full protocol specification** → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md)
 - **Integrating an AI harness** → [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
 - **Continuing another harness's task** → [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md)
@@ -38,6 +39,21 @@ relevant guides.
 - **System architecture & safety** → [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) & [`THREAT_MODEL.md`](./THREAT_MODEL.md)
 - **Documentation index & ownership** → [`DOCS_INDEX.md`](./DOCS_INDEX.md)
 
+## Real execution proof
+
+ForgeLoop includes a public real-execution PoC with the workload,
+protocol artifacts, trusted command provenance, execution receipt,
+event history, cryptographic evidence manifest, and technical audit.
+
+The original task reached validator-backed `COMPLETE / VALID`.
+The evidence package also preserves a later
+`E_RECEIPT_PATH_MISMATCH`, detected after evidence publication itself
+changed the repository.
+
+- [PoC overview](./poc/README.md)
+- [Canonical technical audit](./poc/reports/poc-20260826-real-execution-technical-audit-v2.md)
+- [Evidence package](./poc/evidence/poc-20260826-real-execution/)
+
 ## Catalog
 
 | Topic | Guide |
@@ -75,6 +91,15 @@ forgeloop next --task demo --json
 O último comando informa a ação segura seguinte; ele não executa código nem
 agenda agentes.
 
+### Ações externas duráveis
+
+Para efeitos externos, registre a intenção com `action-propose`, aplique a
+política de capacidade e a aprovação vinculada ao fingerprint, e execute apenas
+com `run-action` usando argv exato. Um resultado `COMMIT_UNKNOWN` nunca é
+repetido automaticamente: observe o sistema externo e use `action-reconcile`.
+As métricas mantêm tokens/custos como desconhecidos quando o host não os
+fornece, e eficiência só existe quando um cenário de referência foi declarado.
+
 Antes de um harness criar ou retomar uma tarefa, ele pode confirmar a
 compatibilidade pública sem depender de detalhes internos:
 
@@ -260,12 +285,24 @@ See [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) and [`LOOP_SYSTEM_DESIGN.
 
 ## Architecture flow
 
-The canonical source is [`docs/forgeloop-flow.mmd`](./docs/forgeloop-flow.mmd),
-and the committed render is [`docs/assets/forgeloop-flow.svg`](./docs/assets/forgeloop-flow.svg).
+The canonical source is the typed Archify workflow
+[`docs/diagrams/forgeloop-engineering-flow.workflow.json`](./docs/diagrams/forgeloop-engineering-flow.workflow.json).
+The committed animated interactive explorer is
+[`docs/assets/diagrams/forgeloop-engineering-flow.html`](./docs/assets/diagrams/forgeloop-engineering-flow.html),
+which opens in the dark presentation stage and traces the workflow. The
+animated, self-contained SVG fallback is
+[`docs/assets/diagrams/forgeloop-engineering-flow.svg`](./docs/assets/diagrams/forgeloop-engineering-flow.svg),
+and the deterministic hash receipt is
+[`docs/assets/diagrams/forgeloop-engineering-flow.receipt.json`](./docs/assets/diagrams/forgeloop-engineering-flow.receipt.json).
+The governance source is [`docs/diagrams/manifest.json`](./docs/diagrams/manifest.json),
+and the source-bound visual approval is kept in
+[`docs/diagrams/reviews/forgeloop-engineering-flow.review.json`](./docs/diagrams/reviews/forgeloop-engineering-flow.review.json).
 The broader architecture and boundaries are in
 [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md).
 
-![ForgeLoop evidence-first engineering flow](./docs/assets/forgeloop-flow.svg)
+[Open the animated ForgeLoop evidence-first engineering flow](./docs/assets/diagrams/forgeloop-engineering-flow.html)
+
+![ForgeLoop evidence-first engineering flow (animated SVG fallback)](./docs/assets/diagrams/forgeloop-engineering-flow.svg)
 
 Text-only fallback: discovery creates the contract and route; required gates
 and `PREFLIGHT_READY` authorize execution; verification creates structured
@@ -305,9 +342,10 @@ values are checked; and install-capable verification requires trusted host
 authority. See [`THREAT_MODEL.md`](./THREAT_MODEL.md) for the full inventory.
 
 Development tooling is intentionally separate from runtime dependencies. The
-repository policy allows only ESLint, c8, and Mermaid CLI as development
-dependencies; `npm run dependency:policy` fails if runtime or unapproved
-dependencies appear.
+repository policy allows only ESLint and c8 as development dependencies;
+`npm run dependency:policy` fails if runtime or unapproved dependencies
+appear. The documentation renderer is vendored and pinned under
+`vendor/archify/v2.15.0/` rather than installed as a package dependency.
 
 Para reportar vulnerabilidades ou contribuir com alterações, consulte
 [`SECURITY.md`](./SECURITY.md) e [`CONTRIBUTING.md`](./CONTRIBUTING.md).
@@ -377,7 +415,7 @@ npm run lint
 npm run coverage
 npm run pack:check
 npm run dependency:policy
-npm run docs:flow
+npm run docs:diagrams
 npm run docs:check
 ```
 
@@ -387,8 +425,8 @@ npm run docs:check
 src/                    npm CLI and protocol implementation
 schemas/                versioned artifact schemas
 ENG/                    package-source engineering guides
-docs/forgeloop-flow.mmd canonical Mermaid source
-docs/assets/            committed diagram render
+docs/diagrams/          typed Archify diagram source and inventory
+docs/assets/diagrams/   committed HTML, SVG, and generation receipt
 scripts/                checks, renderer, release identity, CI notes
 tests/                  Node and Python regression coverage
 .forgeloop/             project-scoped ForgeLoop configuration

package/THIRD_PARTY_NOTICES.md

@@ -64,6 +64,21 @@ inclusion does not install, bundle, or declare any project as a dependency of
 this collection. Check the specific project's current license, terms,
 dependencies, version, and distribution conditions before adoption.
 
+### Archify v2.15.0 — vendored documentation renderer
+
+- Project/source: [tt-a1i/archify](https://github.com/tt-a1i/archify/tree/v2.15.0).
+- Pinned source commit: `e1ac748f19cf805e44bf74fb93c796662152e273`.
+- License declared by the upstream project: MIT; the vendored license is at
+  `vendor/archify/v2.15.0/archify/LICENSE`.
+- Use in this collection: deterministic generation and validation of the
+  typed workflow diagram under `docs/diagrams/`.
+- Boundary: this is a documentation-only vendored toolchain, not a ForgeLoop
+  runtime dependency. It is not installed from a registry, and its exact pin,
+  source, license, and raw-byte tree hashes are recorded in
+  `vendor/archify/v2.15.0/PIN.json`; output hashes are recorded in the receipt.
+  The vendor integrity check rejects modified, missing, extra, renamed, or
+  symlinked files before the renderer is trusted.
+
 ### Superpowers
 
 - Project: [Superpowers](https://github.com/obra/superpowers).