@cassiomc1/forgeloop 1.6.2 → 1.6.4

package/src/integration.d.ts

@@ -0,0 +1,91 @@
+export type ForgeLoopRiskClass =
+  | "READ_ONLY"
+  | "LOOP_MUTATION"
+  | "CLAIM_REACQUISITION"
+  | "EXTERNAL_EXECUTION"
+  | "AUTHORITY_MUTATION"
+  | "EXTERNAL_STATE_ATTESTATION"
+  | "MAINTENANCE"
+  | "CLAIM_RELEASE_RECOVERY"
+  | "LEGACY_MIGRATION"
+  | "FORCE_DESTRUCTIVE";
+
+export interface ForgeLoopCommandInput {
+  [key: string]: unknown;
+  path?: string;
+  taskId?: string | null;
+  json?: boolean;
+  timeoutMs?: number | null;
+  commandArgv?: string[];
+}
+
+export interface ForgeLoopCommandEnvelope<T = unknown> {
+  ok: boolean;
+  command: string | null;
+  exitCode: number;
+  result: T | null;
+  error: { code: string; message: string; next?: string } | null;
+  metadata: {
+    protocolVersion: number;
+    integrationApiVersion: number;
+    packageVersion?: string;
+  };
+}
+
+export interface ForgeLoopCommandDefinition {
+  name: string;
+  category: string;
+  mutation: "READ_ONLY" | "MUTATING" | "EXTERNAL_EXECUTION";
+  options: Readonly<Record<string, Record<string, unknown>>>;
+  writes: readonly string[];
+  removes: readonly string[];
+  mayExecuteExternalProcess: boolean;
+  description: string;
+}
+
+export interface ForgeLoopInvocationClassification {
+  command: string;
+  riskClass: ForgeLoopRiskClass;
+  readOnly: boolean;
+  mutatesProtocol: boolean;
+  removesArtifacts: boolean;
+  executesExternalProcess: boolean;
+  affectsClaimAuthority: boolean;
+  destructive: boolean;
+  requiredCapability: string | null;
+}
+
+export interface ForgeLoopContext {
+  authorityContext: Record<string, unknown>;
+  verificationExecutionAdapter?: Record<string, unknown>;
+  verificationExecutionPolicy?: { requiredIsolation: string };
+}
+
+export declare const FORGELOOP_INTEGRATION_API_VERSION: number;
+export declare const FORGELOOP_INTEGRATION_RUNTIME_VERSION: number;
+export declare const CLI_COMMAND_DEFINITIONS: Readonly<Record<string, ForgeLoopCommandDefinition>>;
+export declare const INTEGRATION_LIMITS: Readonly<Record<string, number>>;
+export declare const INTEGRATION_RISK_CLASSES: Readonly<Record<string, ForgeLoopRiskClass>>;
+export declare const INTEGRATION_RESOURCE_DEFINITIONS: Readonly<Record<string, { scope: string; description: string }>>;
+export declare const VERIFICATION_EXECUTION_POLICY_MODES: readonly string[];
+export declare const VERIFICATION_ISOLATION_MODES: readonly string[];
+
+export declare function getForgeLoopPackageVersion(): string;
+export declare function defaultCommandInputValues(): ForgeLoopCommandInput;
+export declare function validateForgeLoopCommandInput(input: {
+  command: string;
+  input?: ForgeLoopCommandInput;
+  help?: boolean;
+}): void;
+export declare function executeForgeLoopCommand<T = unknown>(input: {
+  command: string;
+  projectPath?: string;
+  input?: ForgeLoopCommandInput;
+  authorityContext?: Record<string, unknown>;
+  runtimeContext?: Record<string, unknown>;
+}): Promise<ForgeLoopCommandEnvelope<T>>;
+export declare function getForgeLoopCapabilities(input?: { packageVersion?: string | null }): Record<string, unknown>;
+export declare function classifyForgeLoopInvocation(command: string, input?: ForgeLoopCommandInput): ForgeLoopInvocationClassification;
+export declare function readForgeLoopIntegrationResource(uri: string, input?: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function resolveForgeLoopProjectRoot(projectPath?: string, input?: { cwd?: string }): Promise<string>;
+export declare function createForgeLoopContext(input?: Record<string, unknown>): ForgeLoopContext;

package/AGENT_COMPATIBILITY.md

@@ -1,11 +0,0 @@
-# Deprecated filename
-
-> Deprecated since package `1.2.4`; retained as a repository compatibility stub.
-> It is not part of the public integration surface and is scheduled for removal
-> in the next compatibility-breaking release.
-
-ForgeLoop is vendor-neutral and does not use a supported-agent allowlist.
-
-The canonical integration contract is:
-
-[`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)

package/docs/RELEASE_CHECKLIST_1_4.md

@@ -1,38 +0,0 @@
-# ForgeLoop 1.4.0 release checklist
-
-This checklist prepares the validated claim-recovery capability for release. It does not authorize publication, tagging, or deployment.
-
-## Ownership and recovery gates
-
-- [ ] Fake, deleted, corrupt, schema-invalid, and mismatched `recovery.json` cases resolve to `INCONSISTENT`.
-- [ ] `INCONSISTENT` preserves historical claims, disables mutation, blocks overlapping acquisition, and is visible in list/show/status/audit/inspect/next.
-- [ ] Only a fully matched recovery artifact and append-only recovery history releases claims.
-- [ ] `task-recover` remains restricted to `STALE` and `ABANDONED`; `RECOVERABLE` keeps its canonical reconciliation path.
-- [ ] `task-resume` validates ownership, settles only an unchanged stale task lock, and reacquires claims under the project claims lock.
-- [ ] Project claim locks classify `NONE`, `LIVE`, `STALE`, `UNKNOWN`, and `CORRUPT`, with CAS-safe stale settlement.
-- [ ] Manually forged COMPLETE state cannot release claims.
-- [ ] Canonically completed task does release claims.
-- [ ] Corrupt/missing completion lifecycle proof retains historical claims.
-- [ ] Task locks with incomplete identity classify UNKNOWN.
-- [ ] Single COMPLETE/RECOVERED task can be inspected implicitly by READ commands.
-- [ ] Single COMPLETE/RECOVERED task cannot be selected implicitly for mutation.
-- [ ] Ownership ledger validation is not redundantly repeated inside one immutable snapshot.
-- [ ] Legacy recovery repair CAS-settles only unchanged stale task locks.
-- [ ] Legacy recovery repair refuses UNKNOWN/CORRUPT task locks.
-- [ ] alreadyRepaired requires a fully valid canonical recovery relationship.
-- [ ] No exported claim helper releases claims from COMPLETE phase alone.
-- [ ] Legacy recovery migration v1 accepts only CALLER_ACKNOWLEDGED authority.
-
-## Compatibility and package gates
-
-- [ ] `package.json` and `package-lock.json` agree on `1.4.0`.
-- [ ] `protocol-info --json` advertises `features.taskClaimRecovery.validatedClaimProjection=true` and task-recovery schema v1.
-- [ ] Documentation states that active task-recovery schema v1 requires a recovery-aware ForgeLoop reader (`>=1.4.0`).
-- [ ] The packed package contains the recovery schema, claim-state core, recovery-history core, and this checklist.
-- [ ] `npm test && npm run lint && npm run coverage && npm run docs:check && npm run pack:check && npm run pack:smoke && npm run dependency:policy` passes once on the release candidate.
-- [ ] `git diff --check` and the repository ForgeLoop audit pass.
-
-## Publication boundary
-
-- [ ] A separately authorized release workflow verifies the final commit, `v1.4.0` tag, npm metadata, tarball digests, and GitHub release identity.
-- [ ] No actor treats caller acknowledgement as `HOST_ATTESTED` authority.

package/docs/RELEASE_CHECKLIST_1_5_MCP.md

@@ -1,78 +0,0 @@
-# ForgeLoop 1.5.0 + MCP release checklist
-
-Preparation checklist for the `@cassiomc1/forgeloop` 1.5.0 and
-`@cassiomc1/forgeloop-mcp` releases. It does not authorize publication.
-
-## Core integration gates
-
-- [ ] Core package version is `1.5.0`; integration API version is `1`.
-- [ ] `exports` map exposes only `.` and `./integration`.
-- [ ] Executor registry is in parity with canonical command definitions.
-- [ ] `bundle` is MAINTENANCE-gated; hidden in readonly/safe.
-- [ ] `resolveForgeLoopProjectRoot` applies CLI target semantics (symlinks rejected).
-- [ ] Integration limits bound strings, arrays, argv, and structured inputs.
-
-## MCP package gates
-
-- [ ] Official SDK v2; target protocol generation `2026-07-28`.
-- [ ] stdio works with clean stdout (protocol-only) and JSON stderr diagnostics.
-- [ ] HTTP is strict modern (`legacy: "reject"`) and loopback-only
-      (`E_MCP_REMOTE_NOT_SUPPORTED` for any other bind).
-- [ ] Transport bounds active: header/request/keepalive timeouts, 4 MiB body cap,
-      POST-only, in-flight ceiling (503 `E_MCP_HTTP_BUSY`).
-- [ ] Tool/resource catalogs are deterministic and identical across transports.
-- [ ] Task-aware mutation tools require explicit `taskId`.
-- [ ] Capability gates re-checked per invocation; tool input cannot elevate policy.
-- [ ] `task-recover`, legacy repair, and force unlock are separately gated;
-      legacy repair hidden by default; `operatorAuthorized` absent from schemas.
-- [ ] No generic shell/exec tool exists.
-
-## Ownership/recovery parity
-
-- [ ] `task/ownership` derives exclusively from the canonical claim resolver.
-- [ ] Forged COMPLETE stays INCONSISTENT with retained claims on every surface.
-- [ ] RECOVERED tasks block ordinary mutation; `task-resume` reacquires canonically.
-- [ ] Concurrent resume yields exactly one winner.
-
-## Safety
-
-- [ ] `maxExecutionTimeMs` enforced: missing→max, zero/negative/float rejected,
-      over-max rejected.
-- [ ] Error payloads preserve canonical codes; secrets redacted; stacks stripped;
-      messages bounded.
-- [ ] Oversized tool/resource output refused with `E_MCP_RESULT_TOO_LARGE`.
-
-## Packaging/docs
-
-- [ ] Core tarball contains integration modules and both integration docs.
-- [ ] MCP tarball contains both bins, src, README; core tarball never ships
-      `integrations/`.
-- [ ] Server `serverInfo.version` equals MCP package.json version.
-- [ ] MCP README documents stdio-default + optional loopback-only HTTP.
-- [ ] THIRD_PARTY_NOTICES covers the Model Context Protocol SDK.
-- [ ] CHANGELOG entries present.
-
-## Exact output-bound gates (post-PR #80)
-
-- [ ] Output bounds measure the exact UTF-8 serialization transmitted
-      (pretty-printed included), not compact JSON.
-- [ ] Compact-below/pretty-above regression covered by tests.
-- [ ] UTF-8 byte-count regression covered by tests.
-- [ ] `forgeloop_capabilities` complete result is bounded like command tools.
-- [ ] Non-size serialization errors are rethrown, not mislabeled as overflow.
-- [ ] Structured tool input is byte-bounded (`E_MCP_INPUT_TOO_LARGE`).
-
-## Documentation gates
-
-- [ ] Repository-wide documentation audit complete.
-- [ ] Documentation manifest/index current.
-- [ ] Generated references current (`docs:generate` leaves no diff).
-- [ ] README / CHANGELOG current.
-- [ ] MCP / Universal Integration docs current.
-- [ ] Security docs current.
-
-## Publication boundary
-
-- [ ] Release identity verification passes.
-- [ ] Publication of either package is separately authorized; this checklist
-      does not itself authorize npm publishing.

package/docs/RELEASE_CHECKLIST_1_6_1.md

@@ -1,121 +0,0 @@
-# ForgeLoop 1.6.1 release checklist
-
-Preparation checklist for the `@cassiomc1/forgeloop` 1.6.1 release. It does not
-authorize publication. Historical checklists:
-[`RELEASE_CHECKLIST_1_5_MCP.md`](./RELEASE_CHECKLIST_1_5_MCP.md),
-[`RELEASE_CHECKLIST_1_4.md`](./RELEASE_CHECKLIST_1_4.md).
-
-## Version and contract identity
-
-- [ ] Core package version is `1.6.1` in `package.json` and the lockfile root.
-- [ ] ForgeLoop protocol version is `1`.
-- [ ] Integration API version is `1`
-      (`FORGELOOP_INTEGRATION_API_VERSION`).
-- [ ] Candidate version is absent from npm and the `v1.6.1` tag is absent from
-      origin before release preparation starts.
-- [ ] `CHANGELOG.md` has a versioned `1.6.1` section with the actual release
-      date and an empty `Unreleased` section above it.
-
-## Verification execution adapter contract (new in 1.6.x line)
-
-- [ ] `src/core/verification-execution.js` defines the adapter boundary,
-      `VERIFICATION_ISOLATION_MODES`, and the two public error codes.
-- [ ] `runtimeContext.verificationExecutionAdapter` and
-      `runtimeContext.verificationExecutionPolicy` are validated at context
-      creation and never accepted as CLI flags or command input.
-- [ ] `createForgeLoopContext`, the isolation modes, and both error codes are
-      exported from `@cassiomc1/forgeloop/integration`.
-- [ ] `protocol-info --json` advertises
-      `features.verificationExecutionIsolation` (version 1, adapter-backed,
-      modes enumerated, `protocolProjectRootSeparateFromExecutionCwd: true`).
-
-## Isolation metadata invariants
-
-- [ ] `NATIVE_PROJECT` requires `isolated: false` and
-      `liveProjectWritable: true`; it is never described as isolated.
-- [ ] `PROJECT_ISOLATED` and `SYSTEM_ISOLATED` require `isolated: true` and
-      `liveProjectWritable: false`; `SYSTEM_ISOLATED` additionally requires
-      `networkPolicy: DENIED`.
-- [ ] Contradictory isolation metadata is rejected with
-      `E_VERIFICATION_EXECUTION_INVALID` before evidence persistence.
-- [ ] Isolated execution must use a cwd separate from the protocol project
-      root; violation fails closed with `E_VERIFICATION_EXECUTION_INVALID`.
-- [ ] Unsatisfiable isolation policy fails closed with
-      `E_VERIFICATION_ISOLATION_UNAVAILABLE` and never falls back to the live
-      project.
-- [ ] Execution records persist `executionKind`, `protocolProjectRoot`,
-      `executionIsolation`, and the `isolation` object per
-      `schemas/execution.schema.json`.
-
-## Durable-action invariants
-
-- [ ] Trusted `COMMITTED` reconciliation replays exactly once; reconciled
-      mirrors are corroborations, never second transitions.
-- [ ] Action verification requires an independent passed execution covering the
-      action's exact immutable requirement.
-- [ ] `REQUIRE_APPROVAL` authorizations bind approval fingerprints validated by
-      readiness and audit.
-- [ ] Public provenance metadata matches behavior
-      (`CALLER_REPORTED` / `EXTERNAL_OBSERVED`).
-
-## PoC evidence validation
-
-- [ ] `npm run poc:evidence:verify` passes against committed evidence bundles.
-- [ ] `npm run poc:evidence:test` passes.
-- [ ] PoC docs (`poc/README.md`,
-      `poc/FORGELOOP_REAL_EXECUTION_POC.md`) match committed evidence paths,
-      manifests, and hashes.
-
-## Documentation freshness
-
-- [ ] `npm run docs:generate` leaves no diff (generated regions current).
-- [ ] `npm run docs:generated:check` passes.
-- [ ] `npm run docs:conformance` passes.
-- [ ] `npm run docs:diagrams:check` passes (typed Archify source unchanged or
-      regenerated with receipt).
-- [ ] `npm run docs:check` passes.
-- [ ] Normative docs represent the post-`v1.6.0` verification execution
-      boundary without making a harness-specific backend normative.
-- [ ] `DOCS_INDEX.md` points release maintainers to this checklist as current.
-
-## Local validation gates
-
-- [ ] `npm run dependency:policy` passes (runtime dependencies remain zero).
-- [ ] `npm run lint` passes.
-- [ ] `npm test` passes.
-- [ ] `npm run coverage` passes.
-- [ ] `npm run pack:check` passes.
-- [ ] Python validators pass: `python3 -m unittest discover -s tests`,
-      `validate_markdown.py` (+ self-test), `validate_loop_system.py`
-      (+ self-test).
-- [ ] `python3 scripts/scan_secrets.py` passes.
-- [ ] `npm pack` tarball inspected: correct name/version, intended docs, no
-      secrets, no `.git`, no `.forgeloop` execution state.
-
-## Protected-branch and PR gates
-
-- [ ] Changes reach `main` only through a reviewed PR; `main-protection`
-      ruleset never bypassed.
-- [ ] Required checks green: `audit`, `CodeQL`, `Verify generated Archify
-      diagram`, `validate (22)`, `tarball smoke (ubuntu-latest)`,
-      `dependency-review`; every other relevant check green.
-- [ ] No unresolved review threads; PR merged without admin bypass.
-
-## Publication boundary
-
-- [ ] Post-merge `main` workflows green before tagging.
-- [ ] npm candidate version and tag re-checked for collision immediately before
-      tagging.
-- [ ] Annotated tag `v1.6.1` created on the exact validated `main` commit and
-      pushed once; never moved after publication.
-- [ ] `npm-publish.yml` retains `contents: read` + `id-token: write`; no
-      `NPM_TOKEN`/`NODE_AUTH_TOKEN` is added anywhere.
-- [ ] `Publish npm package` workflow succeeds (trusted OIDC publishing).
-- [ ] `Release notes` workflow succeeds; GitHub Release is not draft or
-      prerelease and carries the checksum asset.
-- [ ] npm registry reports the exact version with `gitHead` equal to the
-      release commit.
-- [ ] `npm run release:identity` returns `RELEASE_IDENTITY_VALID` with every
-      individual check `ok`.
-- [ ] Optional clean-install smoke test installs `@cassiomc1/forgeloop@1.6.1`
-      and `forgeloop --version` reports `1.6.1`.