@moretea-labs/forge 1.5.0-rc.1

package/AGENTS.md

@@ -0,0 +1,120 @@
+# Forge AGENTS.md
+
+This repository self-hosts the Forge contract. Retired project-skill and project-initializer staging paths are not supported or cleaned up by current tooling. Claude and Codex should follow the same repo-local workflow surface.
+
+## Forge execution runtime
+
+Treat ChatGPT as the controller and Forge as its repository execution layer. ChatGPT chooses how to inspect, plan, edit, verify, or delegate. Forge provides deterministic repository tools and does not impose an Agent-first workflow.
+
+- Direct Edit is the default for understood work. One session may accept many patch batches, keep revision history, create savepoints, run checks, roll back selected revisions, and finalize one aggregate localized diff.
+- Tasks describe objectives, scope, checks, and acceptance criteria. They do not permanently bind Codex, Claude, or GitHub Copilot. The executor is selected when each Run starts.
+- Agents are optional implementation tools for broad exploration, large refactors, or compile/test/fix loops. They receive a high-level implementation contract; ChatGPT still reviews the result and decides what happens next.
+- Ordinary local risk levels are metadata, not permission gates. There is no approval queue and no `approve_risk` handshake. Only an explicitly destructive or irreversible operation requires authorization in the same request.
+- The Controller UI is hierarchical: Overview, Work, Activity, and Settings. Work is organized as Issue -> Task -> Execution instead of exposing every technical record as a top-level destination.
+- Hard runtime boundaries remain for secrets, credentials, Git internals, concurrent write conflicts, out-of-scope writes when a scope is declared, and remote or irreversible side effects.
+## Canonical Workflow Files
+
+- `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
+- `tasks/todos.md` for deferred medium/long-term goals, not active execution checklists
+- `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `scripts/sprint-backlog.sh` (installed implementations live under `.ai/harness/scripts/`; task contracts stay the execution slices)
+- `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
+- `tasks/workstreams/` for capability long-running workstreams that project durable progress into local contracts
+- `tasks/lessons.md` for correction-derived rules
+- `docs/researches/` for deep repo knowledge
+- `tasks/notes/` for task-local implementation decisions, deviations, tradeoffs, and open questions
+- `plans/` for timestamped plans, with `plans/archive/` for history
+- `.ai/harness/workflow-contract.json` for the installed workflow contract manifest
+- `.ai/harness/policy.json` for the machine-readable workflow contract
+- `.ai/context/context-map.json` for progressive context loading
+- `docs/architecture/index.md` for umbrella architecture status, drift requests, snapshots, and diagram links
+- `docs/reference-configs/agentic-development-flow.md` for gstack/Waza routing rules
+
+## Runtime Architecture Guardrails
+
+- Treat Forge as one local MCP application, one active Runtime, one deployable release, and one in-process lifecycle owner. Gateway, MCP transport, Controller, and Scheduler may be modules; they are not independently deployable generations by default.
+- Bounded restart downtime is acceptable. Prefer `stop -> switch complete release -> start -> verify -> full rollback`; do not add ingress, blue/green slots, adoption, or mixed generations without an explicit product requirement.
+- Do not respond to an incident by adding a second status authority, daemon, proxy, KeepAlive wrapper, watchdog, recovery owner, or fallback path; extend the canonical Runtime or standalone Recovery owner instead. First identify the violated invariant and remove, merge, or correct the existing cause.
+- Readiness is one derived whole-system conclusion. Multiple diagnostic checks and reason codes are allowed, but they must not become independent durable readiness state machines.
+- Keep lifecycle, readiness, liveness, capability, authorization, release identity, and diagnostics separate. Do not create composite states such as `status=ready` with `degraded=true`.
+- Only one component may perform lifecycle or recovery side effects. Observers and probes are read-only and submit typed requests to that owner.
+- Release and rollback scope is the complete compatible Runtime, configuration, entrypoint, and SQLite schema/backup state; component-level rollback is forbidden.
+- Any new process, persistent state, enum value, health mode, authority file, or compatibility fallback requires an explicit architecture decision, transition owner, cleanup/removal criterion, and failure-injection tests.
+- Follow `docs/reference-configs/runtime-architecture-guardrails.md` for the normative review gates and target topology.
+
+## Operating Rules
+
+- Sync `tasks/` whenever substantive repo changes are made.
+- Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
+- Treat hook execution as central-first: trusted repos run `~/.forge/hooks/` (bash shim) or the packaged CLI copy; this self-host repo pins `"hook_source": "repo"` in `.ai/harness/policy.json` so `.ai/hooks/` stays the live development runtime, with `assets/hooks/` as the product source mirrored on install. User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
+- Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todos.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
+- Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.
+- Keep architecture drift handling split: `architecture-queue.sh` writes architecture requests/events, `workstream-sync.sh` maintains durable capability workstreams, and `context-contract-sync.sh` only updates controlled local `CLAUDE.md`/`AGENTS.md` architecture blocks.
+- Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
+- Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.
+- Treat Codex auto-compact as a fallback only; use `.ai/harness/handoff/current.md` and `.ai/harness/handoff/resume.md` for long-task rollover.
+- Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
+- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
+- Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
+- Treat contract-level task execution as worktree-first: `scripts/plan-to-todo.sh --plan <approved-plan>` starts `scripts/contract-worktree.sh start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `scripts/contract-worktree.sh finish`.
+- After Codex Plan mode, Waza `/think`, or `forge-plan` produces a decision-complete plan, capture it with `scripts/capture-plan.sh --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
+- If current repo state conflicts with the task, open an isolated `codex/<task-slug>` worktree, finish there, run Waza `/check`-style validation, then merge back to `main` without absorbing unrelated dirty changes.
+- Route product discovery to gstack `office-hours`, complex engineering plans to gstack `plan-eng-review`, design plans to gstack `plan-design-review`, and daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`.
+- Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `diagram-design` from `~/.codex/skills`.
+- Route knowledge sync and handoff retrieval to `gbrain`.
+- Register valuable repo-authored docs in `.ai/harness/brain-manifest.json` with `sync.direction=repo-to-brain`; `scripts/sync-brain-docs.sh` and the PostEdit hook mirror only those explicit entries into the default brain vault.
+- Treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source; `~/.agents/skills` is skills CLI staging/cache only. Update by staging upstream Waza, copying the eight managed `SKILL.md` files into Codex, and verifying with `cmp`.
+- Use `docs/reference-configs/external-tooling.md` and `bash scripts/check-agent-tooling.sh --host both --check-updates` for environment checks; this self-host repo vendors CodeGraph as a dev dependency while generated downstream repos keep the global MCP default unless local policy opts in.
+- When changing `scripts/migrate-project-template.sh` or `scripts/lib/project-init-lib.sh`, verify self-migration of this repo still works.
+- Treat repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters as retired legacy config; migration may back them up locally, but they are not product deliverables.
+
+## Required Checks
+
+```bash
+bun run check:task
+bash scripts/check-deploy-sql-order.sh
+bash scripts/check-architecture-sync.sh
+bash scripts/check-task-sync.sh
+bash scripts/check-task-workflow.sh --strict
+bun scripts/inspect-project-state.ts --repo . --format text
+bash scripts/migrate-project-template.sh --repo . --dry-run
+```
+
+`bun run test` is the affected gate. `bun run check:main` reuses the focused
+task receipt and never expands to the full suite. Full testing is manual and
+explicit through `bun run test:full`; it is not a task, CI, or release gate.
+
+<!-- BEGIN ARCHITECTURE CONTRACT -->
+## Architecture Contract
+
+- Functional block: `.ai/hooks`
+- Capability ID: `runtime-harness-hook-adapters`
+- Matched prefix: `.ai/hooks`
+- Architecture domain: `runtime-harness`
+- Architecture capability: `hook-adapters`
+- Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Last architecture event: 2026-05-29T09:44:46+0800
+- Last changed path: `.ai/hooks/session-start-context.sh`
+- Severity: high
+- Change type: workflow-surface
+- Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
+- Entrypoints: `.ai/hooks`
+- Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
+- Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.
+- Runtime path: `.ai/hooks`
+- LSP/tooling profile: `typescript-lsp`
+- Verification: Use root required checks plus local commands recorded in this capability contract.
+- Latest snapshot: `(none yet)`
+- Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Latest human diagram: `(none yet)`
+- Pending architecture request: `(none)`
+
+## Active Workstreams
+
+- (none yet)
+
+## Current Session Projection
+
+- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
+- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
+- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+<!-- END ARCHITECTURE CONTRACT -->

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable public Forge changes are recorded here. Release entries are tied to immutable Git tags and the matching package version.
+
+## Unreleased
+
+No unreleased public changes are currently recorded.
+
+## 1.5.0-rc.1 - 2026-08-11
+
+### Official plugin distribution
+
+- Added the pinned official plugin catalog and `forge plugin catalog`, `forge plugin list`, and `forge plugin install` commands.
+- Added trusted `managed_cli_json` external-provider transport for bounded cross-platform product providers.
+- Published and pinned Forge Desktop Operator `v0.2.0`, Forge Design `v0.3.0`, and Personal Knowledge Assistant `v0.2.1` as independent repositories.
+- Updated the Desktop Operator pin to `v0.2.1`, adding silent background Chrome/Vivaldi sessions, stable native tab reattachment, and fail-closed foreground-only screenshot behavior.
+- Official installs validate the package manifest, clone only the fixed Moretea Labs HTTPS repository at an immutable tag, and write through the existing Controller Home external-registration authority.
+- Investment Decision System remains an independent product and is intentionally absent from the Forge plugin catalog.
+
+### Runtime and execution
+
+- Unified the product, npm package, CLI, Runtime, protocol, environment, state directory, documentation, and repository identity under **Forge**.
+- Kept bounded work Direct-first and reserved durable Work/worktrees for recovery, isolation, dependencies, concurrency, or longer lifecycle needs.
+- Converged lifecycle authority on one Canonical Runtime service plus an independent Recovery boundary.
+- Hardened Process receipt recovery, terminal Work cleanup, local-system behavior, and stale tool-schema fencing.
+- Added resumable `forge setup open`, `forge setup next`, `forge setup status`, and `forge setup close` first-run configuration.
+
+### Public project surface
+
+- Reworked the GitHub homepage and documentation navigation around npm-first installation, the 19-tool ChatGPT surface, architecture, safety, plugins, support, and contribution paths.
+- Removed stale pre-release/version claims from maintained tutorials and release documentation.
+- Added a maintained Chinese documentation hub and professionalized the official provider repositories with CI, security, support, contribution, issue, and pull-request surfaces.
+
+## Earlier development history
+
+Detailed pre-Forge development notes remain in [docs/CHANGELOG.md](docs/CHANGELOG.md) as historical evidence only. They do not define the current product identity, Runtime architecture, or release status.

package/CLAUDE.md

@@ -0,0 +1,120 @@
+# Forge AGENTS.md
+
+This repository self-hosts the Forge contract. Retired project-skill and project-initializer staging paths are not supported or cleaned up by current tooling. Claude and Codex should follow the same repo-local workflow surface.
+
+## Forge execution runtime
+
+Treat ChatGPT as the controller and Forge as its repository execution layer. ChatGPT chooses how to inspect, plan, edit, verify, or delegate. Forge provides deterministic repository tools and does not impose an Agent-first workflow.
+
+- Direct Edit is the default for understood work. One session may accept many patch batches, keep revision history, create savepoints, run checks, roll back selected revisions, and finalize one aggregate localized diff.
+- Tasks describe objectives, scope, checks, and acceptance criteria. They do not permanently bind Codex, Claude, or GitHub Copilot. The executor is selected when each Run starts.
+- Agents are optional implementation tools for broad exploration, large refactors, or compile/test/fix loops. They receive a high-level implementation contract; ChatGPT still reviews the result and decides what happens next.
+- Ordinary local risk levels are metadata, not permission gates. There is no approval queue and no `approve_risk` handshake. Only an explicitly destructive or irreversible operation requires authorization in the same request.
+- The Controller UI is hierarchical: Overview, Work, Activity, and Settings. Work is organized as Issue -> Task -> Execution instead of exposing every technical record as a top-level destination.
+- Hard runtime boundaries remain for secrets, credentials, Git internals, concurrent write conflicts, out-of-scope writes when a scope is declared, and remote or irreversible side effects.
+## Canonical Workflow Files
+
+- `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
+- `tasks/todos.md` for deferred medium/long-term goals, not active execution checklists
+- `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `scripts/sprint-backlog.sh` (installed implementations live under `.ai/harness/scripts/`; task contracts stay the execution slices)
+- `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
+- `tasks/workstreams/` for capability long-running workstreams that project durable progress into local contracts
+- `tasks/lessons.md` for correction-derived rules
+- `docs/researches/` for deep repo knowledge
+- `tasks/notes/` for task-local implementation decisions, deviations, tradeoffs, and open questions
+- `plans/` for timestamped plans, with `plans/archive/` for history
+- `.ai/harness/workflow-contract.json` for the installed workflow contract manifest
+- `.ai/harness/policy.json` for the machine-readable workflow contract
+- `.ai/context/context-map.json` for progressive context loading
+- `docs/architecture/index.md` for umbrella architecture status, drift requests, snapshots, and diagram links
+- `docs/reference-configs/agentic-development-flow.md` for gstack/Waza routing rules
+
+## Runtime Architecture Guardrails
+
+- Treat Forge as one local MCP application, one active Runtime, one deployable release, and one in-process lifecycle owner. Gateway, MCP transport, Controller, and Scheduler may be modules; they are not independently deployable generations by default.
+- Bounded restart downtime is acceptable. Prefer `stop -> switch complete release -> start -> verify -> full rollback`; do not add ingress, blue/green slots, adoption, or mixed generations without an explicit product requirement.
+- Do not respond to an incident by adding a second status authority, daemon, proxy, KeepAlive wrapper, watchdog, recovery owner, or fallback path; extend the canonical Runtime or standalone Recovery owner instead. First identify the violated invariant and remove, merge, or correct the existing cause.
+- Readiness is one derived whole-system conclusion. Multiple diagnostic checks and reason codes are allowed, but they must not become independent durable readiness state machines.
+- Keep lifecycle, readiness, liveness, capability, authorization, release identity, and diagnostics separate. Do not create composite states such as `status=ready` with `degraded=true`.
+- Only one component may perform lifecycle or recovery side effects. Observers and probes are read-only and submit typed requests to that owner.
+- Release and rollback scope is the complete compatible Runtime, configuration, entrypoint, and SQLite schema/backup state; component-level rollback is forbidden.
+- Any new process, persistent state, enum value, health mode, authority file, or compatibility fallback requires an explicit architecture decision, transition owner, cleanup/removal criterion, and failure-injection tests.
+- Follow `docs/reference-configs/runtime-architecture-guardrails.md` for the normative review gates and target topology.
+
+## Operating Rules
+
+- Sync `tasks/` whenever substantive repo changes are made.
+- Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
+- Treat hook execution as central-first: trusted repos run `~/.forge/hooks/` (bash shim) or the packaged CLI copy; this self-host repo pins `"hook_source": "repo"` in `.ai/harness/policy.json` so `.ai/hooks/` stays the live development runtime, with `assets/hooks/` as the product source mirrored on install. User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
+- Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todos.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
+- Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.
+- Keep architecture drift handling split: `architecture-queue.sh` writes architecture requests/events, `workstream-sync.sh` maintains durable capability workstreams, and `context-contract-sync.sh` only updates controlled local `CLAUDE.md`/`AGENTS.md` architecture blocks.
+- Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
+- Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.
+- Treat Codex auto-compact as a fallback only; use `.ai/harness/handoff/current.md` and `.ai/harness/handoff/resume.md` for long-task rollover.
+- Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
+- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
+- Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
+- Treat contract-level task execution as worktree-first: `scripts/plan-to-todo.sh --plan <approved-plan>` starts `scripts/contract-worktree.sh start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `scripts/contract-worktree.sh finish`.
+- After Codex Plan mode, Waza `/think`, or `forge-plan` produces a decision-complete plan, capture it with `scripts/capture-plan.sh --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
+- If current repo state conflicts with the task, open an isolated `codex/<task-slug>` worktree, finish there, run Waza `/check`-style validation, then merge back to `main` without absorbing unrelated dirty changes.
+- Route product discovery to gstack `office-hours`, complex engineering plans to gstack `plan-eng-review`, design plans to gstack `plan-design-review`, and daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`.
+- Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `diagram-design` from `~/.codex/skills`.
+- Route knowledge sync and handoff retrieval to `gbrain`.
+- Register valuable repo-authored docs in `.ai/harness/brain-manifest.json` with `sync.direction=repo-to-brain`; `scripts/sync-brain-docs.sh` and the PostEdit hook mirror only those explicit entries into the default brain vault.
+- Treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source; `~/.agents/skills` is skills CLI staging/cache only. Update by staging upstream Waza, copying the eight managed `SKILL.md` files into Codex, and verifying with `cmp`.
+- Use `docs/reference-configs/external-tooling.md` and `bash scripts/check-agent-tooling.sh --host both --check-updates` for environment checks; this self-host repo vendors CodeGraph as a dev dependency while generated downstream repos keep the global MCP default unless local policy opts in.
+- When changing `scripts/migrate-project-template.sh` or `scripts/lib/project-init-lib.sh`, verify self-migration of this repo still works.
+- Treat repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters as retired legacy config; migration may back them up locally, but they are not product deliverables.
+
+## Required Checks
+
+```bash
+bun run check:task
+bash scripts/check-deploy-sql-order.sh
+bash scripts/check-architecture-sync.sh
+bash scripts/check-task-sync.sh
+bash scripts/check-task-workflow.sh --strict
+bun scripts/inspect-project-state.ts --repo . --format text
+bash scripts/migrate-project-template.sh --repo . --dry-run
+```
+
+`bun run test` is the affected gate. `bun run check:main` reuses the focused
+task receipt and never expands to the full suite. Full testing is manual and
+explicit through `bun run test:full`; it is not a task, CI, or release gate.
+
+<!-- BEGIN ARCHITECTURE CONTRACT -->
+## Architecture Contract
+
+- Functional block: `.ai/hooks`
+- Capability ID: `runtime-harness-hook-adapters`
+- Matched prefix: `.ai/hooks`
+- Architecture domain: `runtime-harness`
+- Architecture capability: `hook-adapters`
+- Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Last architecture event: 2026-05-29T09:44:46+0800
+- Last changed path: `.ai/hooks/session-start-context.sh`
+- Severity: high
+- Change type: workflow-surface
+- Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
+- Entrypoints: `.ai/hooks`
+- Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
+- Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.
+- Runtime path: `.ai/hooks`
+- LSP/tooling profile: `typescript-lsp`
+- Verification: Use root required checks plus local commands recorded in this capability contract.
+- Latest snapshot: `(none yet)`
+- Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Latest human diagram: `(none yet)`
+- Pending architecture request: `(none)`
+
+## Active Workstreams
+
+- (none yet)
+
+## Current Session Projection
+
+- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
+- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
+- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+<!-- END ARCHITECTURE CONTRACT -->

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+## Our commitment
+
+We are committed to a respectful, harassment-free project for contributors and users regardless of background, identity, experience level, or point of view.
+
+## Expected behavior
+
+- Be respectful, specific, and constructive.
+- Critique code and decisions, not people.
+- Assume good intent while still requiring evidence for technical claims.
+- Respect privacy, security boundaries, and confidential information.
+- Accept maintainer decisions about scope, safety, and release readiness.
+
+## Unacceptable behavior
+
+Harassment, threats, discriminatory language, deliberate disruption, doxxing, publishing private information, or using project channels to pressure others is not acceptable.
+
+## Enforcement
+
+Report conduct concerns privately through the repository maintainers. Do not publish sensitive personal details in an issue. Maintainers may edit or remove content, close discussions, restrict participation, or take other proportionate action to protect the community.
+
+This policy applies in repository spaces and when someone is representing the project in public.

package/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to Forge
+
+Thanks for helping make Forge safer and easier to use. The project values small, reviewable changes backed by exact checks more than broad rewrites or unverified claims.
+
+## Before opening a change
+
+1. Search existing issues and pull requests.
+2. For bugs, include a minimal reproduction and redacted diagnostic output.
+3. For a user-facing change, describe the intended workflow before proposing implementation details.
+4. Keep security-sensitive reports out of public issues; follow [SECURITY.md](SECURITY.md).
+
+## Development setup
+
+Requirements:
+
+- Git;
+- Node.js 20.10 or newer;
+- npm;
+- Bun 1.0 or newer for the complete test suite.
+
+```bash
+git clone https://github.com/moretea-labs/forge.git
+cd forge
+npm ci --ignore-scripts --no-audit --no-fund
+node bin/forge.mjs --help
+bun bin/forge.mjs --help
+```
+
+Forge has no previous-product command aliases. New documentation, tests, fixtures, and examples must use the Forge package, command, state, and protocol names unless they are explicitly asserting that a retired surface is absent.
+
+Run focused tests while working. Before requesting review, run the checks relevant to the change; public and release-facing changes should normally include:
+
+```bash
+npm run check:type
+npm run check:public-docs
+npm run check:release-surface
+npm run check:package-identity
+```
+
+The ordinary task and frozen-candidate gates are:
+
+```bash
+bun run check:task
+bun run check:main
+bun run check:release
+```
+
+`check:task` and `check:main` stop at affected tests; integration and full
+tests are explicit diagnostics. `check:main` owns the focused candidate receipt.
+`check:release` reuses it and adds package validation plus one tarball shared by
+smoke and publish. `test:full` is a manual diagnostic only.
+
+## Change rules
+
+- Do not commit Controller Home, `.ai/harness` runtime state, local jobs, logs, worktrees, tokens, OAuth material, or machine-specific paths.
+- Prefer an isolated worktree or a dedicated branch. Do not mix unrelated fixes.
+- Preserve structured authorization boundaries. Remote writes, destructive actions, and secret access must remain explicit.
+- Add or update tests for behavior changes.
+- Keep the root README user-focused. Detailed architecture and operations belong in `docs/` and the GitHub Wiki source under `docs/wiki/`.
+- English and Simplified Chinese are the maintained public documentation languages. Other translation landing pages must clearly identify themselves as unmaintained unless a maintainer owns them.
+- Do not bump a package version or create a release tag without following [the release process](docs/operations/releasing.md).
+
+## Pull requests
+
+A pull request should contain:
+
+- a clear problem statement;
+- a bounded summary of the solution;
+- the exact checks run and their outcomes;
+- migration, compatibility, or rollback notes when relevant;
+- screenshots only when they add evidence.
+
+Maintainers may ask for a smaller patch when a change combines documentation, runtime architecture, and unrelated cleanup.
+
+## License
+
+By contributing, you agree that your contribution is licensed under the repository's [MIT License](LICENSE) and that required attribution can be recorded in [NOTICE](NOTICE) or [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 AncientTwo
+Copyright (c) 2026 Moretea Labs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,9 @@
+Forge
+
+Copyright (c) 2026 Moretea Labs contributors
+
+Forge began as a derivative of AncientTwo/repo-harness, Copyright (c) 2026 AncientTwo. The initial independent repository snapshot retained substantial portions of that MIT-licensed work. The upstream repository name is preserved here solely as factual legal attribution and is not a supported Forge product or command identity.
+
+Forge has since diverged through substantial modifications to its ChatGPT integration, durable Runtime, repository registry, execution and recovery model, plugin system, review workflow, governance, and release tooling. It is independently maintained by Moretea Labs and is not endorsed by the upstream project.
+
+The upstream copyright and MIT permission notice are preserved in LICENSE as required for copies or substantial portions of the original software.

package/README.en.md

@@ -0,0 +1,5 @@
+# Forge
+
+Forge is a local-first action runtime for bounded, resumable and reviewable software work.
+
+See [README.md](README.md) for installation, product identity, architecture entry points and operating guidance.

package/README.es.md

@@ -0,0 +1,12 @@
+# Forge
+
+Forge es un asistente de acción local-first para trabajo de software que conecta ChatGPT con el estado real de tus repositorios y procesos locales.
+
+La documentación completa y mantenida está en [README.md](README.md). También puedes consultar la [Wiki](docs/wiki/Home.md), la [arquitectura](docs/wiki/Architecture.md) y el [mapa de implementación](docs/wiki/Implementation.md).
+
+La versión candidata actual es `1.5.0-rc.1`. Las versiones candidatas de `@moretea-labs/forge` usan el canal npm `next`; las versiones estables usan `latest`.
+
+- Uso y soporte: [SUPPORT.md](SUPPORT.md)
+- Seguridad: [SECURITY.md](SECURITY.md)
+- Contribuir: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Cambios: [CHANGELOG.md](CHANGELOG.md)

package/README.fr.md

@@ -0,0 +1,12 @@
+# Forge
+
+Forge est un assistant d’action local-first pour le développement logiciel. Il relie ChatGPT à l’état réel de vos dépôts, commandes et vérifications locales.
+
+La documentation complète et maintenue se trouve dans [README.md](README.md). Consultez aussi le [Wiki](docs/wiki/Home.md), l’[architecture](docs/wiki/Architecture.md) et la [carte d’implémentation](docs/wiki/Implementation.md).
+
+La version candidate actuelle est `1.5.0-rc.1`. Les versions candidates de `@moretea-labs/forge` utilisent le canal npm `next` ; les versions stables utilisent `latest`.
+
+- Utilisation et support : [SUPPORT.md](SUPPORT.md)
+- Sécurité : [SECURITY.md](SECURITY.md)
+- Contribution : [CONTRIBUTING.md](CONTRIBUTING.md)
+- Historique : [CHANGELOG.md](CHANGELOG.md)

package/README.ja.md

@@ -0,0 +1,12 @@
+# Forge
+
+Forge は、ChatGPT を実際のローカルリポジトリ、コマンド、検証状態につなぐ、ソフトウェア開発向けの local-first アクションアシスタントです。
+
+完全かつ継続的に更新される説明は [README.md](README.md) を参照してください。[Wiki](docs/wiki/Home.md)、[アーキテクチャ](docs/wiki/Architecture.md)、[実装マップ](docs/wiki/Implementation.md) も利用できます。
+
+現在のリリース候補は `1.5.0-rc.1` です。`@moretea-labs/forge` の RC は npm の `next`、安定版は `latest` チャネルを使用します。
+
+- 利用・サポート: [SUPPORT.md](SUPPORT.md)
+- セキュリティ: [SECURITY.md](SECURITY.md)
+- コントリビューション: [CONTRIBUTING.md](CONTRIBUTING.md)
+- 変更履歴: [CHANGELOG.md](CHANGELOG.md)

package/README.md

@@ -0,0 +1,132 @@
+<a id="english"></a>
+
+<p align="center"><img src="docs/images/forge-banner.svg" alt="Forge — local-first action runtime" width="1280"></p>
+<p align="center"><strong>Local-first action runtime for ChatGPT and AI coding assistants.</strong></p>
+<p align="center"><a href="#english">English</a> · <a href="#zh-cn">简体中文</a> · <a href="docs/README.md">Docs</a> · <a href="docs/forge-plugin-management.md">Plugins</a> · <a href="https://github.com/moretea-labs/forge/releases">Releases</a></p>
+<p align="center"><img alt="CI" src="https://github.com/moretea-labs/forge/actions/workflows/ci.yml/badge.svg"> <img alt="Release" src="https://img.shields.io/github/v/release/moretea-labs/forge?include_prereleases&sort=semver"> <img alt="npm next" src="https://img.shields.io/npm/v/%40moretea-labs%2Fforge?tag=next&label=npm%20next"> <img alt="License" src="https://img.shields.io/github/license/moretea-labs/forge"></p>
+
+Forge gives ChatGPT a bounded, auditable way to work with **real local repositories, processes, plugins, and recovery state**. It keeps durable execution facts outside the chat, uses the lightest valid path for small work, and preserves explicit safety boundaries for remote, destructive, secret, and outside-workspace effects.
+
+## Why Forge
+
+| Need | Forge behavior |
+| --- | --- |
+| Work on real code | Stable `repoId + checkoutId` identity binds every repository operation to the intended checkout. |
+| Keep small tasks fast | Direct-first execution avoids Plan/Issue/Agent/worktree overhead when the change is already understood. |
+| Run long work once | Process Runtime owns build/test/process lifecycle; status, wait, logs, and cancel attach to the same process. |
+| Work concurrently | Independent repositories run in parallel; worktrees are introduced only when isolation is actually needed. |
+| Trust the result | Focused checks, diffs, receipts, evidence, immutable runtime releases, and Recovery make outcomes reviewable. |
+| Extend safely | Typed external providers install through Forge's pinned catalog and reuse the same authorization/evidence path. |
+
+## Quick start
+
+Requirements: Git, Node.js 20.10+, npm, and a writable home directory. Bun 1.0+ is recommended for source development and the full test suite.
+
+```bash
+npm install -g @moretea-labs/forge@next
+forge --version
+forge setup open --target both
+forge setup next     # repeat until ready
+forge setup close
+forge doctor
+```
+
+Connect ChatGPT with [Tutorial 2](docs/tutorials/02-connect-chatgpt.md), then adopt a repository:
+
+```bash
+forge adopt --repo /path/to/your-project --dry-run
+forge adopt --repo /path/to/your-project
+forge repo list --json
+```
+
+For source development, follow [Install and start](docs/tutorials/01-install-and-start.md) or install the reviewed checkout directly:
+
+```bash
+git clone https://github.com/moretea-labs/forge.git && cd forge
+npm ci --ignore-scripts --no-audit --no-fund
+npm install -g . --omit=optional --no-audit --no-fund
+```
+
+## How ChatGPT uses Forge
+
+The normal ChatGPT connector exposes a bounded **19-tool MCP surface**. Five preferred facades—`rh_status`, `rh_access`, `rh_inbox`, `rh_context`, and `rh_work`—cover most orchestration; repository, source/patch, check, Process, plugin-dispatch, and result tools complete the default surface.
+
+```text
+Small task  → inspect → relevant context → Direct Edit → focused check → commit
+Long task   → resolve identity → durable work only if needed → Process/worktree → verify → integrate → clean
+```
+
+<p align="center"><img src="docs/images/forge-controller-flow.svg" alt="Forge canonical runtime flow" width="980"></p>
+
+Ask for the outcome, not the tool: “fix this failing test and commit”, “compare these repositories in parallel”, or “run the build and keep using the same Process”.
+
+## Official providers
+
+| Provider | Purpose | Install |
+| --- | --- | --- |
+| [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator) | Native macOS desktop automation | `forge plugin install desktop_operator` |
+| [Forge Design](https://github.com/moretea-labs/forge-design) | Repository-native design workspace and `design.md` provider | `forge plugin install design` |
+| [Personal Knowledge Assistant](https://github.com/moretea-labs/personal-knowledge-assistant) | Local-first personal knowledge retrieval, memory, and safe writes | `forge plugin install personal_knowledge` |
+
+See [Plugin Management](docs/forge-plugin-management.md) for trust, distribution, update, and transport boundaries. Investment Decision System remains an independent product rather than a Forge plugin.
+
+## Safety model
+
+Forge distinguishes observation, normal local changes, remote effects, destructive actions, outside-workspace access, and secrets. Full Access reduces repetitive approval for ordinary local work; it does **not** weaken destructive, remote, or secret boundaries. See [Security Model](docs/wiki/Security-Model.md) and [SECURITY.md](SECURITY.md).
+
+## Documentation
+
+- **Start:** [Documentation hub](docs/README.md) · [Wiki](docs/wiki/Home.md) · [Quick Start](docs/wiki/Quick-Start.md) · [Public usage guide](docs/public-usage-guide.md)
+- **Understand:** [Core Concepts](docs/wiki/Core-Concepts.md) · [Architecture](docs/wiki/Architecture.md) · [Work Lifecycle](docs/wiki/Work-Lifecycle.md)
+- **Operate:** [Operations](docs/wiki/Operations.md) · [Troubleshooting](docs/operations/troubleshooting.md) · [Platform support](docs/operations/platform-support.md)
+- **Maintain:** [Contributing](CONTRIBUTING.md) · [Release process](docs/operations/releasing.md) · [Changelog](CHANGELOG.md) · [Support](SUPPORT.md)
+
+**Current release candidate:** `1.5.0-rc.1` on the npm `next` channel. Stable releases use `latest`. Forge is MIT licensed; see [LICENSE](LICENSE), [NOTICE](NOTICE), and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+---
+<a id="zh-cn"></a>
+
+<p align="center"><img src="docs/images/forge-banner-cn.svg" alt="Forge——本地优先的行动运行时" width="1280"></p>
+<p align="center"><strong>面向 ChatGPT 与 AI 编程助手的本地优先行动运行时。</strong></p>
+<p align="center"><a href="#english">English</a> · <a href="#zh-cn">简体中文</a> · <a href="docs/README.zh-CN.md">中文文档</a> · <a href="docs/forge-plugin-management.md">插件</a> · <a href="https://github.com/moretea-labs/forge/releases">版本</a></p>
+
+Forge 让 ChatGPT 在**真实本地仓库、进程、插件与恢复状态**上执行有边界、可审查的工作。小任务默认走最短路径；长任务复用同一个 Process；远程、破坏性、密钥和工作区外访问继续保持明确安全边界。
+
+## 核心能力
+
+- **Direct-first**：范围明确的小修改不因调查自动创建 Plan、Issue、Agent 或 worktree。
+- **真实并发**：不同仓库可并行；需要隔离时再建立 worktree；同一 checkout 保持单写者。
+- **可恢复执行**：build/test 只启动一次，后续 status/wait/log/cancel 连接同一个 Process。
+- **明确身份**：`repoId + checkoutId` 防止一个会话误操作另一个 checkout。
+- **可验证结果**：diff、focused check、receipt、evidence、不可变 Runtime release 与 Recovery 都可追溯。
+- **类型化插件**：官方 Provider 从固定版本目录安装，并复用 Forge 的授权、资源声明与证据链。
+
+## 快速开始
+
+```bash
+npm install -g @moretea-labs/forge@next
+forge setup open --target both
+forge setup next     # 重复直到 ready
+forge setup close
+forge doctor
+```
+
+接入仓库：
+
+```bash
+forge adopt --repo /path/to/your-project --dry-run
+forge adopt --repo /path/to/your-project
+forge repo list --json
+```
+
+普通 ChatGPT Connector 默认收敛为 **19 个 MCP 工具**，其中 `rh_status`、`rh_access`、`rh_inbox`、`rh_context`、`rh_work` 五个 facade 覆盖主要编排。正常使用时直接描述目标，不需要自己挑工具。
+
+## 官方 Provider
+
+`forge plugin catalog` 可查看当前目录；官方 Provider 包括 [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator)、[Forge Design](https://github.com/moretea-labs/forge-design) 与 [Personal Knowledge Assistant](https://github.com/moretea-labs/personal-knowledge-assistant)。详见[插件管理](docs/forge-plugin-management.md)。
+
+## 文档与维护
+
+[中文文档中心](docs/README.zh-CN.md) · [安装教程](docs/tutorials/01-install-and-start.zh-CN.md) · [公开使用指南](docs/public-usage-guide.zh-CN.md) · [架构](docs/wiki/Architecture.md) · [故障排查](docs/operations/troubleshooting.zh-CN.md) · [贡献](CONTRIBUTING.md) · [安全](SECURITY.md)
+
+**当前候选版本：** `1.5.0-rc.1`，npm 使用 `next`；稳定版使用 `latest`。项目采用 [MIT License](LICENSE)。