@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/AGENT_COMPATIBILITY.md

@@ -15,6 +15,14 @@ The canonical integration contract is:
 These expectations apply to any compatible harness even though this filename is
 retained as a deprecated compatibility stub:
 
+## Portable Agent Skill
+
+The generated [`skills/forgeloop/SKILL.md`](./skills/forgeloop/SKILL.md) is a
+portable bootstrap and instruction surface. It does not replace native harness
+shims, certify a harness, or own lifecycle, completion, evidence, or claims.
+Its canonical source hierarchy and freshness rules are documented in
+[`docs/AGENT_SKILL.md`](./docs/AGENT_SKILL.md).
+
 - Feature-detect capability versions from `protocol-info --json` or the stable
   Integration API; do not infer support from a package version.
 - Do not auto-recall advisory context, execute advisory text, or treat it as

package/DOCS_INDEX.md

@@ -18,6 +18,7 @@ integration and guide context. Use this map before editing documentation.
 | Getting started tutorial | [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md) | First-time walkthrough from init to completion |
 | Cross-harness continuity | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) | Operational resume guidance, immutable handoffs, and multi-tool resumption |
 | Agent bootstrap summary | [`docs/AGENT_PROTOCOL_SUMMARY.md`](./docs/AGENT_PROTOCOL_SUMMARY.md) | Generated concise navigation aid for protocol invariants and commands |
+| Agent Skill integration | [`docs/AGENT_SKILL.md`](./docs/AGENT_SKILL.md) | Generated portable, non-authoritative agent guidance and freshness contract |
 | CLI command reference | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Full syntax, options, and JSON examples for all commands |
 | Repository Index and Search | [`docs/REPOSITORY_INDEX.md`](./docs/REPOSITORY_INDEX.md) | Mandatory managed engine, indexed search contract, lifecycle, resource, security, and benchmark behavior |
 | Persistent CLI search transport | [`docs/PERSISTENT_SEARCH_TRANSPORT.md`](./docs/PERSISTENT_SEARCH_TRANSPORT.md) | CLI-only local IPC, host lifecycle, ownership, recovery, bounds, privacy, and direct API/MCP boundary |
@@ -34,12 +35,30 @@ integration and guide context. Use this map before editing documentation.
 | Revision and signing providers | [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md) and [`docs/SIGNING_PROVIDERS.md`](./docs/SIGNING_PROVIDERS.md) | Provider-neutral extension contracts |
 | Platform adapters | [`docs/PLATFORM_ADAPTERS.md`](./docs/PLATFORM_ADAPTERS.md) | Generic CI boundary and platform mapping guidance |
 | Universal integration API | [`docs/UNIVERSAL_INTEGRATION.md`](./docs/UNIVERSAL_INTEGRATION.md) | Programmatic integration subpath, envelope semantics, and consumer map |
+| Audit UX read model | [`docs/AUDIT_UX.md`](./docs/AUDIT_UX.md) | Bounded read-only task timeline, health, verification, ownership, and completion projection |
 | Advisory context providers | [`docs/ADVISORY_CONTEXT.md`](./docs/ADVISORY_CONTEXT.md) | Optional external host context, non-evidence trust boundary, allowlist normalization, and safety rules |
+| Provider extension architecture | [`docs/PROVIDER_ARCHITECTURE.md`](./docs/PROVIDER_ARCHITECTURE.md) | Provider-neutral architecture, invocation lifecycle, strict snapshots, cancellation, trust, and authority boundaries |
+| Provider extension reference | [`docs/PROVIDERS.md`](./docs/PROVIDERS.md) | Capability discovery, provider kinds, common contract, limits, errors, and maintainer checklist |
+| Security Review provider | [`docs/SECURITY_REVIEW.md`](./docs/SECURITY_REVIEW.md) | Bounded host-injected observation API, strict findings, timeout/cancellation, and non-authority boundary |
 | Ripwire advisory adapter | [`docs/RIPWIRE_ADAPTER.md`](./docs/RIPWIRE_ADAPTER.md) | Ripwire-specific registration, process contract, JSON mapping, limits, and verification |
+| OpenSrc advisory adapter | [`docs/OPENSRC_ADAPTER.md`](./docs/OPENSRC_ADAPTER.md) | OpenSrc-specific registration, version qualification, cache containment, deterministic search, limits, and verification |
+| Agent Browser verification adapter | [`docs/AGENT_BROWSER_ADAPTER.md`](./docs/AGENT_BROWSER_ADAPTER.md) | Optional host-owned browser executable, bounded observation mapping, isolation, exact origins, screenshots, and trust boundary |
 | Local-first MCP adapter | [`docs/MCP.md`](./docs/MCP.md) | stdio default, optional strict loopback HTTP; server modes/capabilities and canonical resources |
 | Adaptive execution-profile benchmarks | [`docs/EXECUTION_PROFILE_BENCHMARKS.md`](./docs/EXECUTION_PROFILE_BENCHMARKS.md) | Measured provider/host runs, robust statistics, paired/distribution deltas, tail status, outliers, and profile-aware host context |
 | Knowledge integration gap analysis | [`docs/KNOWLEDGE_INTEGRATION_GAP_ANALYSIS.md`](./docs/KNOWLEDGE_INTEGRATION_GAP_ANALYSIS.md) | Repository-only research audit of candidate coverage, proven gaps, canonical homes, context cost, and intentional skip/defer decisions |
 | Knowledge sources and provenance | [`docs/KNOWLEDGE_SOURCES.md`](./docs/KNOWLEDGE_SOURCES.md) | Snapshot, licensing observations, source roles, accepted/skipped concepts, and reuse boundaries |
+| Semantic decision plane | [`docs/SEMANTIC_DECISION_PLANE.md`](./docs/SEMANTIC_DECISION_PLANE.md) | Mandatory bounded Jev/TypeSafe System One decisions, typed non-authoritative results, freshness, and fail-closed boundaries |
+| Model routing | [`docs/MODEL_ROUTING.md`](./docs/MODEL_ROUTING.md) | Model-route tiers, host-model selection, deterministic safety floors, and ForgeLoop authority boundaries |
+| Jev benchmarks | [`docs/JEV_BENCHMARKS.md`](./docs/JEV_BENCHMARKS.md) | Offline fixtures, live interoperability smoke, live benchmark calls, usage, latency, and non-generalized claims |
+| Test intelligence | [`docs/TEST_INTELLIGENCE.md`](./docs/TEST_INTELLIGENCE.md) | Bounded test utility analysis, protected-test rules, semantic classification, and non-evidence status |
+| Test pruning | [`docs/TEST_PRUNING.md`](./docs/TEST_PRUNING.md) | Keep/probe/block planning, isolated probes, and deterministic proof before any removal or rewrite |
+| Repository Index | [`docs/REPOSITORY_INDEX.md`](./docs/REPOSITORY_INDEX.md) | Managed engine, index lifecycle, CLI/API/MCP behavior, privacy, recovery, and search boundaries |
+| Persistent search transport | [`docs/PERSISTENT_SEARCH_TRANSPORT.md`](./docs/PERSISTENT_SEARCH_TRANSPORT.md) | CLI-only local IPC, host ownership, recovery, limits, and direct API/MCP differences |
+| Provider architecture | [`docs/PROVIDER_ARCHITECTURE.md`](./docs/PROVIDER_ARCHITECTURE.md) and [`docs/PROVIDERS.md`](./docs/PROVIDERS.md) | Provider-neutral invocation, strict normalization, cancellation, trust, and non-authority boundaries |
+| Structural quality | [`docs/STRUCTURAL_QUALITY.md`](./docs/STRUCTURAL_QUALITY.md) | Optional provider-neutral baseline, delta policy, and evidence boundaries |
+| Security review | [`docs/SECURITY_REVIEW.md`](./docs/SECURITY_REVIEW.md) | Host-injected bounded security observations and non-authoritative findings |
+| Agent Browser verification | [`docs/AGENT_BROWSER_ADAPTER.md`](./docs/AGENT_BROWSER_ADAPTER.md) and [`docs/AGENT_BROWSER_VERIFICATION.md`](./docs/AGENT_BROWSER_VERIFICATION.md) | Optional browser adapter, exact-origin observations, screenshots, and non-evidence limits |
+| Documentation history | [`docs/history/README.md`](./docs/history/README.md) | Archived audits, release evidence, and completed validation records with current-owner links |
 | Documentation guide | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) | Rules and checklist for modifying documentation |
 | Current release checklist | [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md) | Package, protocol, attestation, integration, and publication gates |
 | Core npm package contents | [`docs/PACKAGE_CONTENTS.md`](./docs/PACKAGE_CONTENTS.md) | Published consumer surface, intentional inclusions, exclusions, and clean-room verification |
@@ -75,8 +94,13 @@ is historical evidence and is not part of the published core package.
 | --- | --- |
 | **First-time user or developer** | [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md) |
 | **AI coding agent / harness** | [`docs/AGENT_PROTOCOL_SUMMARY.md`](./docs/AGENT_PROTOCOL_SUMMARY.md) → [`AGENTS.md`](./AGENTS.md) → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) |
+| **Understanding mandatory semantic decisions** | [`docs/SEMANTIC_DECISION_PLANE.md`](./docs/SEMANTIC_DECISION_PLANE.md) |
+| **Selecting a model route** | [`docs/MODEL_ROUTING.md`](./docs/MODEL_ROUTING.md) |
+| **Evaluating test utility or pruning** | [`docs/TEST_INTELLIGENCE.md`](./docs/TEST_INTELLIGENCE.md) → [`docs/TEST_PRUNING.md`](./docs/TEST_PRUNING.md) |
+| **Reviewing historical repository evidence** | [`docs/history/README.md`](./docs/history/README.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) |
+| **Audit or operator UI integrator** | [`docs/AUDIT_UX.md`](./docs/AUDIT_UX.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) |
 | **Looking up CLI commands** | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) |
@@ -86,6 +110,8 @@ is historical evidence and is not part of the published core package.
 | **Looking for quick recipes** | [`docs/RECIPES.md`](./docs/RECIPES.md) |
 | **Configuring structural quality feedback** | [`docs/STRUCTURAL_QUALITY.md`](./docs/STRUCTURAL_QUALITY.md) |
 | **Configuring Ripwire advisory context** | [`docs/RIPWIRE_ADAPTER.md`](./docs/RIPWIRE_ADAPTER.md) |
+| **Configuring OpenSrc advisory context** | [`docs/OPENSRC_ADAPTER.md`](./docs/OPENSRC_ADAPTER.md) |
+| **Understanding provider extensions** | [`docs/PROVIDER_ARCHITECTURE.md`](./docs/PROVIDER_ARCHITECTURE.md) → [`docs/PROVIDERS.md`](./docs/PROVIDERS.md) |
 | **Understanding verification trust** | [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope) |
 | **Understanding attestation trust** | [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md#trust-levels) |
 | **Maintaining generated diagrams** | [`docs/diagrams/README.md`](./docs/diagrams/README.md) |
@@ -112,12 +138,17 @@ is historical evidence and is not part of the published core package.
 - **Measure structural quality without replacing tests**: [`docs/STRUCTURAL_QUALITY.md`](./docs/STRUCTURAL_QUALITY.md)
 - **Read the normative protocol specification**: [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md)
 - **Integrate a new AI environment**: [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
+- **Build a task audit view**: [`docs/AUDIT_UX.md`](./docs/AUDIT_UX.md)
 - **Map ForgeLoop state into an external runtime/orchestrator**: [`ORCHESTRATOR_INTEGRATION.md`](./ORCHESTRATOR_INTEGRATION.md)
 - **Edit documentation safely**: [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md)
 - **Audit the npm package boundary**: [`docs/PACKAGE_CONTENTS.md`](./docs/PACKAGE_CONTENTS.md)
 - **Verify source-content attestations**: [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md)
 - **Understand narrow verification and checker binding**: [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope)
 - **Inspect the governed diagrams**: [`docs/diagrams/README.md`](./docs/diagrams/README.md)
+- **Understand mandatory Jev semantics**: [`docs/SEMANTIC_DECISION_PLANE.md`](./docs/SEMANTIC_DECISION_PLANE.md)
+- **Understand model routing**: [`docs/MODEL_ROUTING.md`](./docs/MODEL_ROUTING.md)
+- **Review test utility and pruning safety**: [`docs/TEST_INTELLIGENCE.md`](./docs/TEST_INTELLIGENCE.md) and [`docs/TEST_PRUNING.md`](./docs/TEST_PRUNING.md)
+- **Review historical validation evidence**: [`docs/history/README.md`](./docs/history/README.md)
 
 `README.md` is intentionally a catalog and quickstart. Do not copy the full
 process into adapters or README sections; link to the canonical source.
@@ -125,7 +156,7 @@ process into adapters or README sections; link to the canonical source.
 ## Lifecycle reading order
 
 1. Read [`README.md`](./README.md) for scope and quickstart.
-2. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) for the process gates.
+2. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) for the process gates and [`docs/SEMANTIC_DECISION_PLANE.md`](./docs/SEMANTIC_DECISION_PLANE.md) for mandatory bounded semantic checkpoints.
 3. Read [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) for the active
    runtime or harness boundary.
 4. Inspect [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) and confirm facts from
@@ -152,8 +183,9 @@ 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 uses the approved exact `smol-toml` runtime dependency for bounded
-Cargo manifest parsing. Development dependencies remain limited to c8, ESLint,
+The package uses the approved exact `@typesafe-ai/sdk` dependency for the pinned
+semantic decision plane and `smol-toml` for bounded Cargo manifest parsing.
+Development dependencies remain limited to c8, ESLint,
 TypeScript, and YAML 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

package/ENG/nodejs-backend-development-eng.md

@@ -596,10 +596,10 @@ Useful primary references include:
   [NestJS](https://docs.nestjs.com/), [Koa](https://koajs.com/), and
   [hapi](https://hapi.dev/)
 - [TypeScript handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
-- [OWASP API Security Top 10](https://owasp.org/API-Security/editions/2023/en/0x11-t10/)
+- [OWASP API Security Top 10](https://owasp.org/projects/api-security-project)
 - [OWASP SSRF prevention](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html)
 - [OWASP Node.js security guidance](https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html)
-- [RFC 9110 HTTP semantics](https://www.rfc-editor.org/rfc/rfc9110)
+- [RFC 9110 HTTP semantics](https://datatracker.ietf.org/doc/html/rfc9110)
 
 These sources inform implementation decisions; they do not replace the
 repository's pinned runtime, local policy, tests, or ForgeLoop evidence.

package/ENG/sec-code-eng.md

@@ -677,11 +677,11 @@ data independently of that choice.
 
 ## Sources and References
 
-- OWASP ASVS 5.0.0: https://owasp.org/www-project-application-security-verification-standard/
+- OWASP ASVS 5.0.0: https://owasp.org/projects/asvs
 - Official OWASP ASVS 5.0.0 CSV: https://github.com/OWASP/ASVS/raw/v5.0.0/5.0/docs_en/OWASP_Application_Security_Verification_Standard_5.0.0_en.csv
 - OWASP Top 10:2025 (Web): https://owasp.org/Top10/2025/
 - OWASP Mobile Top 10:2024: https://owasp.org/www-project-mobile-top-10/
-- OWASP Mobile Application Security Verification Standard (MASVS) / MASTG: https://owasp.org/www-project-mobile-app-security/
+- OWASP Mobile Application Security Verification Standard (MASVS) / MASTG: https://owasp.org/projects/mobile-application-security
 - OWASP Cheat Sheet Series: https://cheatsheetseries.owasp.org/
 - OWASP SSRF Prevention: https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html
 - OWASP File Upload: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html
@@ -700,11 +700,11 @@ data independently of that choice.
 - Android Network Security Config and Certificate Transparency: https://developer.android.com/privacy-and-security/security-config
 - Android cryptography and Keystore: https://developer.android.com/privacy-and-security/cryptography
 - Android `EncryptedSharedPreferences` (deprecated): https://developer.android.com/reference/androidx/security/crypto/EncryptedSharedPreferences
-- OAuth 2.0 Security Best Current Practice, RFC 9700: https://www.rfc-editor.org/rfc/rfc9700
-- JWT Best Current Practices, RFC 8725: https://www.rfc-editor.org/rfc/rfc8725
-- Web Origin, RFC 6454: https://www.rfc-editor.org/rfc/rfc6454
-- OAuth 2.0 Token Introspection, RFC 7662: https://www.rfc-editor.org/rfc/rfc7662
-- ChaCha20-Poly1305, RFC 8439: https://www.rfc-editor.org/rfc/rfc8439
+- OAuth 2.0 Security Best Current Practice, RFC 9700: https://datatracker.ietf.org/doc/html/rfc9700
+- JWT Best Current Practices, RFC 8725: https://datatracker.ietf.org/doc/html/rfc8725
+- Web Origin, RFC 6454: https://datatracker.ietf.org/doc/html/rfc6454
+- OAuth 2.0 Token Introspection, RFC 7662: https://datatracker.ietf.org/doc/html/rfc7662
+- ChaCha20-Poly1305, RFC 8439: https://datatracker.ietf.org/doc/html/rfc8439
 - GitHub Actions: use full-length commit SHA: https://docs.github.com/en/actions/reference/security/secure-use
 - GitHub artifact attestations: https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations
 - Apple Platform Security Guide: https://support.apple.com/guide/security/

package/EXECUTION_STATE.md

@@ -31,6 +31,18 @@ task-bound `COMPLETION_VALIDATED` event and coherent state) is required, and a
 forged or unproven COMPLETE state is `INCONSISTENT` with historical claims
 retained.
 
+For an intentional active-task stop, use the explicit canonical command:
+
+```bash
+forgeloop task-abandon --task <id> --acknowledge-abandonment --json
+```
+
+It appends `TASK_ABANDONED`, writes a matching recovery boundary classified
+`ABANDONED`, keeps the current phase unchanged, and resolves ownership to
+`RELEASED_BY_RECOVERY`. It never emits `COMPLETION_VALIDATED` and never grants
+publication authority. `clear-state` only clears a checkpoint and must not be
+used to release claims.
+
 The file is local, ignored by Git, schema-versioned, and never a replacement
 for the manifest or the target project profile (installed as
 `.forgeloop/kit/PROJECT_PROFILE.md`). It contains no secrets and is untrusted

package/LOOP_ENGINEERING.md

@@ -541,6 +541,21 @@ forgeloop preflight
 
 `preflight` validates local ForgeLoop artifacts only. It does not invoke the model, run project commands, or treat a prose declaration as evidence. A `READY` result is required before `EXECUTING` in standard and strict workflows. A non-empty `current-contract.unresolvedDecisions[]` causes `forgeloop preflight` to return `BLOCKED` with `E_CONTRACT_UNRESOLVED_DECISION`; a valid `current-contract.assumptions[]` list does not block preparation.
 
+Required gates are recorded only through `forgeloop gate-record`. The command
+accepts only gates required by the active route or policy, computes artifact
+hashes itself, rejects traversal and symlink escapes, and permits mutation only
+in `ROUTED`, `DESIGNING`, or `PLANNED`. It rejects gate writes after execution
+starts. A satisfied gate requires a meaningful decision and no unknowns.
+Caller-provided evidence remains descriptive local input and cannot assert
+`HOST_ATTESTED`, `FORGELOOP_EXECUTED`, or remote attestation.
+
+Built-in contract preset references are limited to the canonical
+`contract-preset:documentation`, `contract-preset:bug`,
+`contract-preset:feature`, and `contract-preset:release` values. These values
+do not require `.forgeloop/sources.json`; mixed contracts still validate every
+non-built-in reference against the source registry, and unknown preset names
+are rejected.
+
 ### Resumable activation and artifact reconciliation
 
 `PREFLIGHT_READY` is a durable checkpoint, not only a status value. A persisted
@@ -864,6 +879,15 @@ proportional phases, but:
 - `REVIEWING` cannot claim independent review when reviewer and implementer
   identities are equal.
 
+Immediately after `task-create`, a task may have a valid descriptor and
+hash-linked `TASK_RECEIVED`/transaction history without `work-state.json`.
+ForgeLoop derives `RECEIVED` from that canonical early artifact set. `next`
+returns `DISCOVER`, and `discover` appends the initial discovery milestone
+without creating synthetic work state. `next` then returns `CREATE_CONTRACT`;
+`contract-create` persists and validates the real contract and materializes the
+first work-state checkpoint with its actual contract fingerprint. Invalid,
+contradictory, or unexpected early history remains inconsistent.
+
 Resume rules are conservative: revalidate branch, HEAD, contract fingerprint,
 protocol version, and required artifacts before continuing; never rerun a
 completed destructive or publication action automatically; rerun cheap
@@ -989,8 +1013,10 @@ tooling, the agent must verify the capability boundary before using it:
 3. Reuse an existing callable capability when it is sufficient for the task.
 4. If the required capability is missing and a keyless Qwen path exists,
    install only the smallest matching capability, normally
-   `qwen-mm-plugins-core` for multimodal reading. Use the active harness's
-   native installation mechanism or the official
+   `qwen-mm-plugins-core` for multimodal reading, when the host or operator has
+   explicitly granted task-scoped installation authority. Without that
+   authority, keep the capability unavailable and report the limitation. Use
+   the active harness's native installation mechanism or the official
    [Qwen-MM-Plugins](https://github.com/QwenLM/Qwen-MM-Plugins) instructions.
 5. If the operation is API-backed, check the required environment variable or
    configured service endpoint before enabling it. Without that prerequisite,

package/ORCHESTRATOR_INTEGRATION.md

@@ -183,7 +183,8 @@ Attestation Chain](./docs/CODE_ATTESTATION.md#completion-flow).
 
 ## Serializable interfaces
 
-The following JSON Schemas define the boundaries a host may implement:
+The following core lifecycle JSON Schemas define boundaries a host may implement;
+the complete current inventory is generated in `docs/ARTIFACT_REFERENCE.md`:
 
 - `schemas/routing-input.schema.json` and
   `schemas/routing-result.schema.json` define deterministic guide selection
@@ -203,6 +204,9 @@ The following JSON Schemas define the boundaries a host may implement:
   `schemas/config.schema.json`, `schemas/policy.schema.json`, and
   `schemas/task-bundle.schema.json` define chronology, mode, policy, and
   handoff boundaries.
+- `schemas/semantic-decision.schema.json`, `schemas/context-plan.schema.json`,
+  and `schemas/test-utility.schema.json` define bounded semantic inputs and
+  test-intelligence projections without lifecycle or evidence authority.
 
 `src/core/conformance.js` validates relationships that individual schemas
 cannot express: route/state protocol versions, route/state guide sets,
@@ -224,10 +228,10 @@ tool objects, credentials, hidden prompts, or remote database references.
 ## Host responsibilities
 
 The compatible harness owns model execution, tool execution, scheduling,
-parallelism, lifecycle, isolation, and any remote services. It must pass
-validated inputs to the protocol, preserve file ownership, report unavailable
-capabilities, and never turn local success into an unverified publication
-claim.
+parallelism, verification isolation, and any remote services. It must invoke
+lifecycle transitions through ForgeLoop, pass validated inputs, preserve file
+ownership, report unavailable capabilities, and never turn local success into an
+unverified publication claim.
 
 ## No-runtime boundary
 

package/PROTOCOL_INTEGRATION.md

@@ -181,6 +181,16 @@ authority, provenance, and safety-floor decisions remain unchanged.
 validator-backed completion remains unchanged.
 ```
 
+The capability handshake also advertises the versioned, read-only `auditUx`
+resource feature. `task/audit-view` is a bounded presentation projection
+composed from canonical status, audit, report, history, trace, ownership,
+next-action, approval, and recovery resolvers. It exposes no lifecycle,
+evidence, completion, mutation, or external-execution authority; hosts must
+use the canonical command/API path for mutations. Timeline pagination is
+sequence-based and bounded, and the projection omits raw event payloads,
+commands, environment values, credentials, provider output, and absolute
+paths. See [`docs/AUDIT_UX.md`](./docs/AUDIT_UX.md).
+
 ## Capability negotiation
 
 The public capability handshake exposes additive capability families separately
@@ -190,6 +200,7 @@ from Protocol v1, schema v1, and Integration API v1:
 | --- | --- | --- |
 | `canonicalHandoffs` | v2 | Immutable handoff snapshots with ledger-backed exactly-once operational acceptance |
 | `advisoryContextProviders` | v1 | Lazy, opt-in, provider-neutral Integration API injection only |
+| `providerExtensions` | v1 | Experimental provider-neutral capability vocabulary; generic registry remains internal and unexported |
 
 `repositoryIndex` v1 is a mandatory provider-neutral discovery capability for
 Git repositories. ForgeLoop currently implements it with a managed, pinned
@@ -223,6 +234,40 @@ instructions. `protocol-info` may advertise the capability, but advisory
 recall remains a programmatic Integration API operation; there is no stock
 `context-recall` CLI command.
 
+<a id="FL-PROVIDER-001"></a> **FL-PROVIDER-001 — `providerExtensions` MUST remain provider-neutral and experimental and MUST NOT imply a public generic provider registry API.**
+
+<a id="FL-PROVIDER-002"></a> **FL-PROVIDER-002 — Every advertised provider kind MUST deny lifecycle, completion, and evidence authority.**
+
+<a id="FL-PROVIDER-003"></a> **FL-PROVIDER-003 — Provider results MUST cross a strict JSON snapshot boundary before consumer use.**
+
+<a id="FL-PROVIDER-004"></a> **FL-PROVIDER-004 — The generic provider registry MUST remain absent from public package subpath exports.**
+
+`providerExtensions` v1 is provider-neutral and experimental. It advertises
+five provider kinds, strict JSON result normalization, cooperative cancellation,
+and false lifecycle, completion, evidence, and auto-install authority. This
+capability advertisement does not imply a generic public provider registration
+API or a supported `./providers` package subpath. Protocol version remains 1,
+Schema version remains 1, and Integration API version remains 1.
+
+The dedicated `browserVerificationProviders` runtime-context option is a
+separate explicit Integration API boundary. It is host-injected, provider
+neutral, lazy, and inert during context construction. `runBrowserVerification`
+is the only public operation; it does not run from lifecycle commands and does
+not persist observations. ForgeLoop owns the shared deadline, cooperative
+cancellation, strict result snapshot, exact origin/redirect validation, and
+overall assertion-status derivation. Browser observations cannot directly
+create evidence, completion authority, claims, receipts, or next actions. The
+origin allowlist is not a network sandbox and no browser vendor is canonical.
+
+The dedicated `securityReviewProviders` runtime-context option is another
+explicit, host-injected Integration API boundary. `runSecurityReview` is
+lazy, inert during context construction, and observation-only: it does not
+install or discover scanners, mutate lifecycle artifacts, create evidence,
+authorize completion, or issue commands. ForgeLoop bounds and freezes the
+request, shares one deadline and cooperative abort signal across factory and
+review, and normalizes the result into a strict immutable observation. Findings
+must not be treated as canonical evidence or lifecycle authority.
+
 A consumer that understands `canonicalHandoffs` v1 but not v2 may disable the
 handoff-specific UI while keeping Protocol v1 core functionality available.
 Consumers must feature-detect the capability family and must not mark the
@@ -394,6 +439,12 @@ only a compatibility alias and has identical caller-acknowledgement semantics.
 a trusted grant reference through a boundary the active actor cannot mint or
 replace. The standalone CLI does not expose such a self-attestation option.
 
+Explicit active-task abandonment is a distinct caller-acknowledged operation:
+`task-abandon --task <id> --acknowledge-abandonment` releases validated claims
+through the same canonical ownership resolver, project/task serialization, and
+append-only recovery history. It does not change the phase or create completion,
+publication, or host authority. `clear-state` is not an abandonment substitute.
+
 Claim ownership is a validated relationship, not an artifact preference.
 <a id="FL-CLAIM-001"></a> **FL-CLAIM-001 — Every harness MUST consume the canonical claim-state resolver**
 over the descriptor, work state, recovery artifact, and complete validated
@@ -488,8 +539,10 @@ installing a package.
 
 The installed loop directs the active actor to inspect native model and harness
 capabilities. When a task requires a missing capability (e.g. multimodal vision),
-the actor may install the smallest task-scoped capability (such as `Qwen-MM-Plugins`)
-through native mechanisms or upstream installers, then verify it before use.
+a host or operator may provision the smallest task-scoped capability (such as
+`Qwen-MM-Plugins`) only when installation authority has been explicitly
+granted. Use native mechanisms or upstream installers, then verify it before
+use. Without that authority, keep it unavailable and report the limitation.
 
 API credentials, system packages, and unrelated environment changes remain
 separately gated.

package/README.md

@@ -1,7 +1,7 @@
 # ForgeLoop — Verifiable Engineering Protocol
 
 <p align="center">
-  <img src="./docs/assets/eng_readme_forgeloop.png" alt="ForgeLoop — Loop Engineering for AI Agents" width="100%">
+  <img src="./docs/assets/forgeloop-architecture.svg" alt="ForgeLoop Architecture" width="100%">
 </p>
 
 [![CodeQL](https://github.com/cassiomc1/forgeloop/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/codeql.yml)
@@ -11,10 +11,10 @@
 [![Package smoke](https://github.com/cassiomc1/forgeloop/actions/workflows/package-smoke.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/package-smoke.yml)
 [![Release notes](https://github.com/cassiomc1/forgeloop/actions/workflows/release-notes.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/release-notes.yml)
 
-ForgeLoop is a protocol CLI for AI-assisted development.
-It turns outcomes into contracts, deterministic routing, resumable state,
-evidence-backed verification, recovery, cross-harness continuity, repository
-discovery, and validator-backed completion—not an agent or LLM runtime.
+ForgeLoop is the deterministic governor for AI-assisted engineering. Jev is the
+mandatory bounded System One semantic input; the host coding model is System Two
+implementation. ForgeLoop alone owns lifecycle, claims, gates, evidence,
+completion, recovery, and publication truth.
 
 Operational sources are indexed in [`DOCS_INDEX.md`](./DOCS_INDEX.md).
 [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) is canonical;
@@ -29,7 +29,9 @@ Operational sources are indexed in [`DOCS_INDEX.md`](./DOCS_INDEX.md).
 - **Full protocol specification** → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md)
 - **Integrating an AI harness** → [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
 - **Optional advisory context providers** → [`docs/ADVISORY_CONTEXT.md`](./docs/ADVISORY_CONTEXT.md)
+- **Provider extension architecture** → [`docs/PROVIDER_ARCHITECTURE.md`](./docs/PROVIDER_ARCHITECTURE.md) and [`docs/PROVIDERS.md`](./docs/PROVIDERS.md)
 - **Agent bootstrap summary** → [`docs/AGENT_PROTOCOL_SUMMARY.md`](./docs/AGENT_PROTOCOL_SUMMARY.md)
+- **Portable ForgeLoop Agent Skill** → [`skills/forgeloop/SKILL.md`](./skills/forgeloop/SKILL.md) and [`docs/AGENT_SKILL.md`](./docs/AGENT_SKILL.md)
 - **Continuing another harness's task** → [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md)
 - **CLI command reference** → [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
 - **Artifact & schema reference** → [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md)
@@ -113,20 +115,18 @@ npx @cassiomc1/forgeloop doctor
 
 ### 60-second demonstration
 
-In a disposable directory, initialize the kit and create an isolated task. The
-result is deterministic and can be inspected by any compatible harness:
+In a disposable directory, initialize the kit and create an isolated task.
+Semantic checkpoints require a host-configured `TYPESAFE_API_KEY`; ForgeLoop never persists it.
 
 ```bash
 npx @cassiomc1/forgeloop init
 forgeloop task-create --task demo --claim src --json
-forgeloop route --task demo --work clean-code --json
+forgeloop contract-create --task demo --preset documentation --json
+forgeloop route --task demo --work code --json
 forgeloop preflight --task demo --json
 forgeloop next --task demo --json
 ```
 
-The last command reports the next safe action; it does not execute code or
-schedule agents.
-
 ### Optional code attestation
 
 Projects may opt into source-content attestation after a valid completion. The
@@ -152,7 +152,9 @@ results. Provider output is never lifecycle state, evidence, authority,
 completion truth, or next-action authority, and it is never executable as a
 protocol command. The optional Ripwire adapter follows the same boundary; see
 [`docs/ADVISORY_CONTEXT.md`](./docs/ADVISORY_CONTEXT.md) and
-[`docs/RIPWIRE_ADAPTER.md`](./docs/RIPWIRE_ADAPTER.md).
+[`docs/RIPWIRE_ADAPTER.md`](./docs/RIPWIRE_ADAPTER.md). The optional OpenSrc
+adapter exposes external package source context through the same boundary; see
+[`docs/OPENSRC_ADAPTER.md`](./docs/OPENSRC_ADAPTER.md).
 
 ### Optional task boundaries and differential verification
 
@@ -178,8 +180,8 @@ raising `VERIFIED` to `ATTESTED`. See [`docs/REVISION_PROVIDERS.md`](./docs/REVI
 
 Generic CI provides a platform-neutral revision-range boundary; thin GitHub,
 GitLab, local, or enterprise adapters may translate revisions without adding
-trust rules to the protocol core. The CLI and integration API remain usable
-across supported platforms, with MCP as an optional local adapter.
+trust rules to the protocol core. CLI and Integration API remain cross-platform;
+MCP is optional.
 
 ### Durable external actions
 
@@ -363,20 +365,20 @@ ForgeLoop supports isolated, concurrent tasks within the same repository via det
 # Create an isolated task claiming specific directories
 forgeloop task-create --task auth-feature --claim src/auth --claim tests/auth --json
 
-# List active and completed tasks
 forgeloop task-list --json
 
-# Ask for deterministic conflict/recovery guidance
 forgeloop next --task auth-feature --json
 
-# Only for a task classified STALE or ABANDONED: release effective claims
+# Release claims only for a STALE or ABANDONED task
 forgeloop task-recover --task auth-feature --acknowledge-recovery --json
 
-# Reacquire conflict-free claims before mutating a recovered task again
+# Explicitly abandon an active non-terminal task when its objective is no longer valid
+forgeloop task-abandon --task auth-feature --acknowledge-abandonment --json
+
+# Reacquire conflict-free claims before mutating a recovered task
 forgeloop task-resume --task auth-feature --json
 
-# Run standard lifecycle commands targeting the task
-forgeloop route --task auth-feature --work clean-code --surface backend
+forgeloop route --task auth-feature --work code --surface backend
 forgeloop preflight --task auth-feature --json
 forgeloop advance --task auth-feature --to EXECUTING
 forgeloop complete --task auth-feature --json
@@ -395,6 +397,12 @@ disabled. The standalone acknowledgement flag is not host-attested authority.
 settlement, normal claim-overlap, and clean-checkout checks succeed. Never
 create, edit, or delete `recovery.json` manually.
 
+`task-recover` is reserved for canonical `STALE`/`ABANDONED` classification.
+`task-abandon` is the separate explicit path for an active non-terminal task:
+it records `TASK_ABANDONED`, releases claims as `RELEASED_BY_RECOVERY`, keeps
+the phase unchanged, and never implies completion or publication. `clear-state`
+only removes a checkpoint and is not a claim-release or abandonment mechanism.
+
 ### Executable policy verification & brownfield baselines
 
 ForgeLoop enforces automated, non-interactive verification rules (`rules.json`) with zero interactive dependencies:
@@ -431,12 +439,20 @@ See [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) and [`LOOP_SYSTEM_DESIGN.
 
 ## Architecture flow
 
+<a href="./docs/assets/diagrams/forgeloop-engineering-flow.html">
+  <img src="./docs/assets/forgeloop-lifecycle-animated.svg" alt="Animated ForgeLoop evidence-first loop: Contract, Route, Preflight, Execute, Evidence, Review, VALID, with an evidence-only correction loop" width="100%">
+</a>
+
+*Animation: the rail pulses through each step in order. It loops forever and
+respects reduced-motion settings. Select the image to open the full animated
+interactive explorer.*
+
 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 traces it. The
-animated, self-contained SVG fallback is
+detailed, 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).
@@ -449,8 +465,6 @@ The broader architecture and the CLI-only search boundary are in
 
 [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)
-
 Two focused, source-bound workflow
 diagrams complement it. The [Verification Trust Flow source](./docs/diagrams/forgeloop-verification-trust-flow.workflow.json),
 [animated explorer](./docs/assets/diagrams/forgeloop-verification-trust-flow.html),
@@ -516,8 +530,9 @@ it must not infer current ownership from `task.json` or `recovery.json` alone.
 
 ## Security and dependency boundary
 
-Runtime uses Node built-ins and approved exact `smol-toml`; it installs no
-agents, providers, plugins, services, or telemetry. Paths, symlinks, JSON,
+Runtime uses Node built-ins and the approved exact `@typesafe-ai/sdk` and
+`smol-toml` dependencies; it installs no agents, providers, plugins, services,
+or telemetry. Paths, symlinks, JSON,
 manifests, schemas, receipts, and secret-like values are bounded or checked.
 Install-capable verification requires trusted host authority; see
 [`THREAT_MODEL.md`](./THREAT_MODEL.md).

package/TERMINOLOGY.md

@@ -33,6 +33,8 @@
 | Integration level | The capability tier of an execution environment (`INSTRUCTION_DISCOVERED`, `PROTOCOL_CAPABLE`, `PROTOCOL_LIMITED`, `CONFORMANCE_VERIFIED`). |
 | Recovered task | A non-terminal task whose ordinary mutation authority is suspended and whose effective write claims are released by durable `recovery.json` state. |
 | Recovery acknowledgement | A caller declaration that it intends to recover a task classified `STALE` or `ABANDONED`; it is not a host-attested authority grant. |
+| Active-task abandonment | An explicit caller-acknowledged `task-abandon` operation that releases validated claims for a non-terminal active task without changing its phase or asserting completion. |
+| Abandonment event | The append-only `TASK_ABANDONED` recovery boundary and its transaction witness; it is distinct from automatic stale-task recovery and from completion. |
 | Historical claims | The write claims retained in `task.json` as task history, including while recovery releases their active ownership. |
 | Effective claims | The claims currently enforced for ownership conflicts: descriptor claims for an active task, or an empty set after validator-backed completion or active recovery. |
 | Claim reacquisition | The serialized `task-resume` operation that rechecks conflicts and checkout cleanliness before removing recovery state and restoring mutation authority. |