@moretea-labs/forge 1.5.0-rc.1

package/README.zh-CN.md

@@ -0,0 +1,84 @@
+# Forge
+
+<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="README.md#english">English</a> · <a href="README.md#zh-cn">仓库首页中文</a> · <a href="docs/README.zh-CN.md">中文文档</a> · <a href="https://github.com/moretea-labs/forge/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 让 ChatGPT 在**真实本地仓库、进程、插件和恢复状态**上执行有边界、可审查的工作。它把 Git、Process、检查和发布证据保存在聊天之外，小任务走最短路径，长任务复用同一个执行生命周期。
+
+## 为什么使用 Forge
+
+| 需求 | Forge 的处理方式 |
+| --- | --- |
+| 操作真实代码 | 使用稳定的 `repoId + checkoutId` 绑定目标仓库和 checkout。 |
+| 小任务不要重流程 | Direct-first；仅调查不会自动创建 Plan、Issue、Agent 或 worktree。 |
+| 长命令不要重复跑 | Process Runtime 只启动一次，后续 status/wait/log/cancel 连接同一个 Process。 |
+| 多仓库并发工作 | 不同仓库可并行；真正需要隔离时才建立 worktree。 |
+| 结果能够复核 | diff、focused check、receipt、evidence、不可变 Runtime release 与 Recovery 都可追溯。 |
+| 安全扩展能力 | 官方 Provider 从固定版本目录安装，复用 Forge 的授权、资源声明和证据链。 |
+
+## 快速开始
+
+需要 Git、Node.js 20.10+、npm 和可写用户目录。源码开发建议安装 Bun 1.0+。
+
+```bash
+npm install -g @moretea-labs/forge@next
+forge --version
+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](docs/tutorials/02-connect-chatgpt.zh-CN.md)和[完成第一个仓库任务](docs/tutorials/03-first-repository-task.zh-CN.md)继续。源码开发可使用：
+
+```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
+```
+
+## ChatGPT 如何使用 Forge
+
+普通 ChatGPT Connector 默认是 **19 个 MCP 工具**。五个主要 facade——`rh_status`、`rh_access`、`rh_inbox`、`rh_context`、`rh_work`——覆盖日常编排，其余默认工具负责仓库、源码/补丁、check、Process、插件分发和结果读取。
+
+```text
+小任务 → 状态/上下文 → Direct Edit → focused check → commit
+长任务 → 确定身份 → 确有需要才建 durable work → Process/worktree → verify → integrate → clean
+```
+
+<p align="center"><img src="docs/images/forge-controller-flow.svg" alt="Forge Canonical Runtime 流程" width="980"></p>
+
+正常使用时直接描述目标即可，不需要自己挑工具。
+
+## 官方 Provider
+
+| Provider | 用途 | 安装 |
+| --- | --- | --- |
+| [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator) | macOS 原生桌面操作 | `forge plugin install desktop_operator` |
+| [Forge Design](https://github.com/moretea-labs/forge-design) | 仓库原生设计工作区和 `design.md` | `forge plugin install design` |
+| [Personal Knowledge Assistant](https://github.com/moretea-labs/personal-knowledge-assistant) | 本地优先个人知识检索、记忆与安全写入 | `forge plugin install personal_knowledge` |
+
+Forge 不扫描用户本机 sibling 仓库，也不允许模型临时提供任意 executable。完整边界见[插件管理](docs/forge-plugin-management.md)。Investment Decision System 保持独立产品，不进入 Forge 官方插件目录。
+
+## 安全模型
+
+Forge 区分读取、普通本地修改、远程影响、破坏性操作、工作区外访问和密钥访问。Full Access 只减少普通本地工作的重复授权，不会削弱 destructive、remote 或 secret 边界。详见[安全模型](docs/wiki/Security-Model.md)和 [SECURITY.md](SECURITY.md)。
+
+## 文档
+
+- **开始使用：** [中文文档中心](docs/README.zh-CN.md) · [安装](docs/tutorials/01-install-and-start.zh-CN.md) · [公开使用指南](docs/public-usage-guide.zh-CN.md)
+- **理解系统：** [Wiki](docs/wiki/Home.md) · [核心概念](docs/wiki/Core-Concepts.md) · [架构](docs/wiki/Architecture.md) · [工作生命周期](docs/wiki/Work-Lifecycle.md)
+- **运维维护：** [故障排查](docs/operations/troubleshooting.zh-CN.md) · [平台支持](docs/operations/platform-support.zh-CN.md) · [发布流程](docs/operations/releasing.zh-CN.md)
+- **参与项目：** [贡献](CONTRIBUTING.md) · [安全](SECURITY.md) · [支持](SUPPORT.md) · [版本记录](CHANGELOG.md)
+
+**当前候选版本：** `1.5.0-rc.1`，npm 使用 `next`；稳定版本使用 `latest`。项目采用 [MIT License](LICENSE)。

package/SECURITY.md

@@ -0,0 +1,50 @@
+# Security policy
+
+## Supported versions
+
+Until the first stable release, security fixes are applied to the latest `1.4.0-rc.x` line and `main`. Older prereleases and historical tags are not supported.
+
+| Version | Supported |
+| --- | --- |
+| latest `1.4.0-rc.x` | Yes |
+| `main` | Yes, for verification before release |
+| older prereleases and historical tags | No |
+
+## Reporting a vulnerability
+
+Use GitHub's private vulnerability reporting flow from the repository **Security** tab. Include:
+
+- the affected version or commit;
+- the smallest safe reproduction;
+- impact and required preconditions;
+- whether credentials, remote writes, destructive actions, sandbox escapes, or privilege boundaries are involved;
+- suggested mitigations, when known.
+
+Do not include exploit details, credentials, tokens, private repository data, or unredacted host paths in a public issue. If private reporting is unavailable, open a public issue containing only a request for a private maintainer contact channel and no vulnerability details.
+
+## Scope
+
+Security reports are especially useful for:
+
+- authorization or repository-scope bypasses;
+- remote or destructive actions occurring without explicit authorization;
+- secret leakage through logs, artifacts, packages, or public exports;
+- command injection, path traversal, unsafe worktree cleanup, or symlink attacks;
+- MCP authentication, OAuth, Supervisor, Gateway, Worker, or plugin boundary failures;
+- release provenance or package-content tampering.
+
+A normal validation failure, unsupported platform, stale documentation, or unavailable optional provider is usually a bug rather than a vulnerability unless it crosses a security boundary.
+
+## Disclosure
+
+Please allow maintainers time to reproduce, fix, and prepare an advisory before public disclosure. The project will credit reporters who request attribution and will avoid publishing sensitive reproduction details that create unnecessary risk.
+
+## Credential exposure response
+
+Forge redacts credential-shaped Process Runtime output before persistence
+and sanitizes bounded historical logs and result artifacts when they are read or
+reconciled. These controls reduce retained exposure but do not revoke a credential.
+If a real token, password, private key, or authenticated URL may have appeared in
+process output, treat it as compromised: rotate or revoke it through the owning
+provider, review recent use, and avoid copying the original value into issues,
+logs, test fixtures, or remediation evidence.

package/SKILL.md

@@ -0,0 +1,431 @@
+---
+name: forge
+description: Single canonical skill for operating forge CLI, controller, hooks, planning, repair, verification, and delivery workflows
+when_to_use: "forge, initialize repo-local agentic development harness, scaffold new project with forge, migrate repo-local agentic development harness, audit repo-local agentic development harness, repair repo-local agentic development harness"
+---
+
+# Forge
+
+Forge is the CLI, Runtime, and hook automation product for repo-local agentic development. This skill is the single host-discoverable router for the versioned workflow engine and CLI commands.
+
+Product boundary:
+
+- internal engine: CLI plus hook-backed tasks-first harness
+- contract ID: tasks-first-harness-v1
+- canonical skill, CLI, and package name: `forge`
+- new-project creation surface: `forge scaffold`
+
+Retired project-skill and project-initializer staging paths are not recognized, synchronized, or cleaned up by current tooling. Historical markers in long-migrated repositories are inert evidence.
+
+The skill should not carry the whole workflow contract in prose. It should:
+
+1. inspect the repository
+2. classify the workflow state
+3. choose the correct path
+4. rely on the repo contract, migration scripts, and tests for enforcement
+
+## 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.
+## Explicit mode directives
+
+Automatic routing remains authoritative when the user does not provide a mode directive. In particular, understood bounded work still defaults to Direct Edit; adding explicit modes must not make ordinary requests Plan-first, Agent-first, Issue-first, or Campaign-first.
+
+A leading mode directive is an opt-in instruction to ChatGPT's Forge router. It applies only to the current request, is removed from the objective before execution, and never bypasses permissions, Runtime authority, protected-path rules, approvals, or destructive/remote-write confirmation.
+
+- `-plan` or `/plan`: force the reviewed planning path. Planning is read-only: inspect repository state and call `controller_context_pack` with `structural_context=required` so CodeGraph symbol/reference/dependency/impact evidence is used when the index is ready; load only relevant architecture/ADR/design/README material, then create or revise the existing PlanContract. Review the PlanContract before approval. Do not start mutation until the reviewed plan is approved and execution is explicitly bound to an approved plan step. If CodeGraph is unavailable or stale, keep the degraded evidence warning visible and use bounded current-source context instead of pretending graph coverage exists.
+- `-debug` or `/debug`: force evidence-first debugging. Reproduce or characterize the failure, then prefer `controller_context_pack` with `structural_context=auto` to isolate callers, dependencies, and the smallest causal surface before patching and focused verification. The directive does not force an Agent or Campaign; existing routing still chooses Direct, bounded Work, or an optional worker from the actual scope and risk.
+- `-campaign` or `/campaign`: force the durable Campaign topology for the current request. Use Campaign review checkpoints and independent task coordination even when automatic routing would otherwise choose Direct or bounded Work. This is an explicit user override of topology, not a permission override.
+
+A bare directive with no objective should return/explain that mode's working contract and must not mutate repository state. Mode directives are not sticky across turns unless the user repeats them or explicitly asks to continue the same active Plan/Campaign.
+
+## When to use
+
+- install or refresh the CLI+hooks workflow in an existing repo
+- create a new project or module scaffold only when the user asks for a new product/module skeleton, then attach the harness
+- migrate an older repo to the current tasks-first harness
+- audit drift between prompts, hooks, scripts, and repo-local contract files
+- repair broken task-sync, workflow-contract, or handoff surfaces
+
+## When not to use
+
+- runtime bug debugging inside an already healthy AI workflow
+- generic project scaffolding unrelated to AI routing or repo-local workflow contracts
+- using scaffold to adopt an existing repo; choose the canonical router's init,
+  migrate, upgrade, or repair path instead
+- ordinary product feature work
+
+## Controller direct-change rule
+
+When this skill is used to operate the Controller itself, prefer a bounded direct edit for known small documentation, configuration, or code changes. The expected chain is `read_repository_file -> begin_edit_session -> apply_patch -> get_edit_session_diff -> verify_edit_session -> finalize_edit_session`. Create an Issue only when investigation, dependencies, broad scope, parallelism, long-running verification, or elevated risk requires durable orchestration. Issue creation alone is never a completed result.
+
+## Router Protocol
+
+Always start with structured inspection, not prompt guessing.
+
+### Step 1. Inspect first
+
+Run:
+
+- `bun scripts/inspect-project-state.ts --repo <path> --format text`
+  - fallback: `node --loader ./src/runtime/shared/node-ts-loader.mjs scripts/inspect-project-state.ts --repo <path> --format text`
+
+Read the result fields:
+
+- `mode`
+- `legacy_contract_version`
+- `drift_signals`
+- `required_decisions`
+- `safe_defaults`
+
+### Step 2. Choose one path
+
+Classify the request into one canonical workflow path before running checks or
+edits. The CLI subcommands are execution surfaces, not separate skills. For
+example, pre-merge or release readiness uses the check path, while broken task
+sync, hook routing, handoff, context, policy, or helper surfaces use repair.
+
+1. **Scaffold**
+   - use only when creating a new project, app, or module skeleton
+   - use `forge scaffold`
+   - choose the A-K project catalog entry, then optional `ai_native_profile`
+   - attach the harness after the project structure exists
+   - do not use this path for existing-repo adoption
+2. **Initialize**
+   - use when the repo has no meaningful tasks-first workflow yet
+3. **Migrate**
+   - use when the repo has legacy workflow docs, missing contract manifest, or stale harness artifacts
+4. **Audit**
+   - use when the repo mostly works but the user wants drift analysis and enforcement review
+5. **Repair**
+   - use when the repo has a current contract surface but broken task-sync, hooks, or handoff behavior
+### Step 3. Prefer engine actions over prompt-only fixes
+
+Default order:
+
+1. for new projects, scaffold the requested project/module shape first
+2. migrate legacy docs if needed
+3. install or refresh workflow contract artifacts
+4. sync hooks, helpers, and templates
+5. merge the guidance-only `external_tooling` profile into `.ai/harness/policy.json`
+6. verify the repo-local contract
+
+Do not treat hooks as the primary source of truth. The repo contract lives in repo files.
+
+## Core Engine Surfaces
+
+The single machine-readable contract source is:
+
+- `assets/workflow-contract.v1.json`
+
+The installed runtime copy inside a repo is:
+
+- `.ai/harness/workflow-contract.json`
+
+The main engine entrypoints are:
+
+- `scripts/inspect-project-state.ts`
+- `scripts/migrate-workflow-docs.ts`
+- `scripts/migrate-project-template.sh`
+- `scripts/check-agent-tooling.sh`
+- `scripts/check-task-workflow.sh`
+- `scripts/create-project-dirs.sh`
+
+## CLI Workflow Surface
+
+`forge` is the only host-discoverable skill. Planning, review, execution,
+maintenance, verification, delivery, browser consultation, and setup remain CLI
+commands or controller capabilities selected by this router. Do not install one
+skill per command.
+
+Choose the smallest applicable path:
+
+- planning: plan, PRD, review, sprint, or bounded goal preparation
+- lifecycle: init, scaffold, migrate, upgrade, or capability configuration
+- maintenance: architecture, deploy-readiness, handoff, repair, or check
+- execution and delivery: direct controller work, automated workflow, or ship
+- consultation: ChatGPT browser/GPT Pro setup and consult commands, preserving
+  the existing credential, session, and user-consent boundaries
+
+The implementation authority remains in the CLI, controller tools, scripts,
+hooks, and versioned contract files. Add a separate skill only when it represents
+a genuinely independent knowledge domain with a non-overlapping trigger and
+safety model; a CLI alias is not sufficient justification.
+
+## Plan Index
+
+Keep A-K as stable scaffold codes, but route them as stack-family handles, not
+product prescriptions. Choose by frontend shell, backend/runtime boundary,
+deployment target, data authority, and sidecar needs first. Product domains
+such as finance, CRM, Web3, healthcare, and commerce are overlays.
+
+Core Plans (A-F), routed as stack families:
+- Plan A: Astro-first SSR/content shell. Use Astro for SSR, content, docs,
+  marketing, and mostly-static app shells with islands where needed.
+- Plan B: Vite 8 client-only app shell. Use Vite + React + TanStack
+  Router/Query plus shadcn/Radix-style UI for dense interactive apps and
+  internal tools that do not need crawler-visible SSR landing HTML.
+- Plan C: TanStack Start Workers webapp. Prefer TanStack Start + Vite +
+  Cloudflare Workers when the same React webapp needs public SEO/SSR at `/`
+  and authenticated or browser-heavy workspace routes under `/app`. Use
+  route-level `ssr: false` for `/app`; Next.js is not a default recommendation.
+- Plan D: Shared frontend/backend monorepo. Prefer Bun workspaces with apps,
+  packages, shared contracts, a Hono gateway, and optional Turborepo only when
+  repo scale needs orchestration.
+- Plan E: Cloudflare edge web stack. Prefer Workers for TanStack Start SSR
+  webapps, Pages only for static/client-only assets or content shells, and R2,
+  KV, Queues, Durable Objects, and Hyperdrive where they fit. Do not default to
+  D1; use Postgres/Supabase or SQLite/Turso unless the D1 tradeoff is explicit.
+- Plan F: Mobile/realtime companion. Use Expo Router on React Native New
+  Architecture, with NativeWind where useful and explicit voice/media/realtime
+  boundaries when needed.
+
+Custom Presets (G-K), routed as sidecar/runtime families:
+- Plan G: Python research/data/agent sidecar. Use `uv`, FastAPI or Pydantic AI,
+  DuckDB/Polars, evals, and artifact storage behind the app gateway.
+- Plan H: Go high-concurrency or financial sidecar. Use Go/Gin or narrow Go
+  workers for market data, FIX/RFQ, fan-out, infra adapters, and TS-adjacent
+  high-concurrency services.
+- Plan I: Local-first or lightweight SQL stack. Use SQLite, Turso/libSQL,
+  Turso Sync for new local-first sync work, Loro or other sync primitives, and
+  explicit replication/ownership contracts.
+- Plan J: Rust native/performance sidecar. Use Rust for parsers, indexing,
+  sandboxing, native kernels, and low-latency tools when the team can support
+  the operational complexity.
+- Plan K: Fully custom configuration. Use when the stack cannot be expressed as
+  a composition of the families above.
+
+Agent runtimes that need stable Node APIs, long-lived processes, local tools,
+or heavier sidecars should default to VPS deployment behind the Hono gateway,
+not Cloudflare Workers. Cloudflare remains the preferred web/edge delivery
+surface, not the mandatory agent execution environment.
+
+## AI-native scaffold overlay
+
+`forge scaffold` keeps A-K as the stack-family catalog and uses
+`ai_native_profile` as a separate overlay axis. The default profile is `none`,
+so generated output stays on the selected family unless the user asks for agentic
+runtime behavior. Use an overlay only when the generated app needs agent UI,
+streaming protocol, tool boundary, sidecar, shared state, approvals, artifacts,
+or observability.
+
+Supported profile IDs live in `assets/initializer-question-pack.v4.json`.
+Current stack guidance:
+
+- Use Astro for SSR/content/docs shells and Vite 8 for rich interactive
+  surfaces. Prefer a shared monorepo over disconnected frontend/backend repos.
+- Use TanStack Start + Vite + Cloudflare Workers when a SaaS webapp needs
+  public landing SEO/SSR and a client-heavy workspace in the same product
+  surface. Keep `/` SSR/prerender-capable and `/app` client-only.
+- Do not scaffold `apps/marketing` plus `apps/web` as the default answer to
+  SEO/SSR. Treat a static marketing app as explicit legacy/rollback or content
+  scope, not as the normal SaaS webapp split.
+- Use React Router Framework Mode or Vike only as fallback evaluations if the
+  Start + Workers thin scaffold gate fails. Do not default to Next.js.
+- Use Expo Router for mobile and keep React Native New Architecture
+  compatibility visible in the scaffold.
+- Use assistant-ui or AI SDK UI for chat and generative UI primitives; use
+  AG-UI when the frontend and backend need a durable event stream for runs,
+  tools, shared state, interrupts, approvals, replay, or multimodal updates.
+- Use Bun/Hono as the default app-facing agent gateway. The gateway owns auth,
+  policy, run IDs, tool contracts, approval state, streaming, and telemetry
+  before any model framework or sidecar runs.
+- Prefer Cloudflare for web and edge delivery, but keep agent runtimes on VPS
+  when they need Node compatibility, local tools, long-lived workers, or heavier
+  sidecars. D1 is opt-in, not the default database.
+- Use MCP or narrow HTTP jobs for tools and sidecars. Do not let MCP servers,
+  model providers, or agent frameworks become product authority.
+- Keep orchestration swappable: AI SDK for simple provider/tool streaming;
+  OpenAI Agents SDK, Mastra, LangGraph, Pydantic AI, or a custom runner only
+  when the product needs multi-step state, handoffs, memory, evals, approvals,
+  or durable execution.
+- Prefer Postgres or Supabase for durable app authority. Use SQLite or
+  Turso/libSQL for lightweight, local-first, edge, or embedded workloads.
+  Treat object storage, queues, Redis, vector stores, ClickHouse,
+  Temporal/Inngest/BullMQ/Trigger.dev, and OpenTelemetry as opt-in capability
+  boundaries, not mandatory scaffold defaults.
+
+Generated structure overlays currently exist for:
+
+- `runtime-console`: assistant-ui/AG-UI run console, Bun/Hono agent gateway,
+  run store, contracts, approvals, artifacts, replay, and telemetry
+- `product-copilot`: in-product copilot panel, AG-UI app-domain events, product
+  context loaders, business action tools, authorization, and approval policies
+- `sidecar-kernel`: Bun/Hono app gateway with Python, Go, or Rust kernels behind
+  MCP tools or narrow HTTP jobs
+- `collaborative-editor`: editor surface with document contracts, CRDT/sync
+  ownership, and user-visible agent action boundaries
+
+Do not turn AI-native overlays into more lettered plans. Do not make A2UI,
+specific model providers, vector DBs, workflow engines, tracing vendors, or
+sidecar languages mandatory defaults.
+
+Scaffold is not an existing-repo adoption path. If the target already has a
+product tree, use `forge init`, `forge migrate`,
+`forge upgrade`, or `forge repair` and preserve the existing app
+shape. `create-project-dirs`, `hooks-init`, and `docs-init` remain internal
+steps behind public commands, not standalone user-facing scaffold aliases.
+
+## Migration Rules
+
+For legacy repos, migrate old document surfaces before refreshing templates.
+
+Legacy paths include:
+
+- `docs/plan.md`
+- `docs/TODO.md`
+- `docs/PROGRESS.md`
+- `docs/contract.md`
+- `docs/review.md`
+- `docs/handoff.md`
+- `HANDOFF.md`
+
+Use:
+
+- `bun scripts/migrate-workflow-docs.ts --repo <path> --dry-run`
+- `bun scripts/migrate-workflow-docs.ts --repo <path> --apply`
+
+Migration defaults:
+
+- preserve user-authored content
+- archive uncertain legacy content instead of guessing
+- remove repo-local Skill Factory and auto-memory surfaces when present
+- archive legacy `docs/PROGRESS.md` content; do not regenerate it as a default workflow surface
+- keep `tasks/todos.md` limited to deferred medium/long-term goals, including the tradeoff and revisit trigger
+- move hidden contracts and deep findings into topic-scoped `docs/researches/*.md`
+- distill repeated corrections into `tasks/lessons.md`
+- merge missing `external_tooling` defaults into `.ai/harness/policy.json` without overwriting explicit user values
+- keep gstack/gbrain/CodeGraph detection advisory-only; do not auto-install, auto-upgrade, auto-sync, or auto-enable MCP
+- let `forge init` bootstrap the required global runtime in one pass:
+  CLI install, forge runtime alias sync, user-level hook adapters, Waza
+  (`think`, `hunt`, `check`, `health`), Mermaid, brain root persistence, and
+  CodeGraph CLI/MCP configuration
+- treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source, `~/.agents/skills` is only skills CLI staging/cache, and updates require stage -> copy to Codex -> `cmp` verification
+
+## Repo-Local Contract
+
+Preserve these semantics:
+
+- `plans/` is the timestamped plan catalog; `.ai/harness/active-plan` selects the active plan, with `.claude/.active-plan` as a legacy fallback during transition
+- `plans/plan-*.md` must carry a workflow inventory before implementation: active plan, owning worktree, contract, review, notes, deferred ledger, checks, run snapshots, scope owner, switching rule, and worktree isolation path
+- `tasks/todos.md` is the deferred-goal ledger; active execution stays in the plan's `## Task Breakdown`
+- `tasks/lessons.md` stores correction-derived rules
+- `docs/researches/*.md` stores deep repo findings and hidden contracts by topic
+- `tasks/contracts/` and `tasks/reviews/` are completion gates
+- `tasks/contracts/*.contract.md` must repeat the workflow inventory and make `allowed_paths` the edit-scope authority
+- `tasks/workstreams/` stores durable capability progress
+- `docs/CHANGELOG.md` stores release history
+- `assets/hooks/` is the installable hook product source; `.ai/hooks/` is a full live runtime only in repos that pin `"hook_source": "repo"`
+- user-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapter surfaces; repo-local `.claude/hooks/`, `.claude/settings.json`, and `.codex/hooks.json` are legacy cleanup targets
+
+## Hook Workflow Protocol
+
+When the task mentions hooks, hook workflow, Codex hook detection, or hook-based
+automation, treat it as a runtime-harness slice, not a generic config edit.
+
+Map the route first:
+
+1. `assets/hooks/` is the installable source.
+2. The active runtime resolves central-first through `forge-hook`; `.ai/hooks/`
+   is a full repo-local implementation only when `"hook_source": "repo"` is pinned.
+3. User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are adapters
+   that dispatch to the packaged `forge-hook` entry or the equivalent `forge hook` CLI route.
+4. Codex also requires the user-level hook config to be trusted in Codex Settings before it
+   executes.
+5. Generated `.claude/hooks/`, repo-local `.claude/settings.json`, and repo-local
+   `.codex/hooks.json` are legacy cleanup targets; preserve only user-authored
+   `custom-*.sh` hooks.
+
+Trace one real event before changing behavior, for example:
+
+`UserPromptSubmit -> adapter -> forge-hook -> prompt-guard.sh -> plan
+or advisory output`
+
+or:
+
+`PostToolUse(Edit|Write) -> adapter -> forge-hook ->
+post-edit-guard.sh -> architecture drift, brain sync, contract verification,
+task handoff`
+
+For Codex hook failures, debug in this order: user-level `~/.codex/hooks.json`,
+Codex Settings trust, `forge-hook` resolution, the active target hook
+script, then `.ai/harness/events.jsonl` or `.claude/.trace.jsonl` evidence.
+
+Hooks are accelerators and guards. They do not replace `plans/`, `tasks/`,
+contracts, reviews, policy, checks, or handoff artifacts. Heavy workflows such as
+autoresearch must not silently run as background hook mutations. The retired
+`autoresearch-advisory.sh` hook is not part of `.ai/hooks`, user-level adapters,
+or installable hook templates. If autoresearch evidence is needed, the agent
+runs it explicitly and keeps local run products under ignored `autoresearch/`
+when they must remain in the workspace.
+
+Verify hook workflow changes with hook-specific evidence:
+
+- default hook asset parity between `assets/hooks/` and `.ai/hooks/`, with
+  no self-host-only hook exclusions
+- `bun test tests/hook-runtime.test.ts tests/workflow-contract.test.ts`
+- `bash scripts/check-task-sync.sh`
+- `bash scripts/check-task-workflow.sh --strict`
+- `bun scripts/inspect-project-state.ts --repo . --format text`
+- `.ai/harness/checks/latest.json`, `.ai/harness/events.jsonl`, or handoff readback
+
+## Output Ownership
+
+This skill may create or update:
+
+- `AGENTS.md`
+- `AGENTS.md`
+- `.ai/hooks/*`
+- `.claude/settings.json`
+- `.codex/hooks.json`
+- `.claude/templates/*`
+- `docs/spec.md`
+- `docs/reference-configs/*.md`
+- `tasks/todos.md`
+- `tasks/lessons.md`
+- `docs/researches/*`
+- `tasks/contracts/*`
+- `tasks/reviews/*`
+- `tasks/workstreams/*`
+- `deploy/README.md`
+- `deploy/sql/*` for ordered deployment SQL files
+- `.ai/harness/*`
+- helper scripts under `scripts/`
+
+## Verification
+
+When changing the engine, migration path, contract manifest, or self-hosted workflow, run:
+
+```bash
+bun run check:task
+bash scripts/check-deploy-sql-order.sh
+bash scripts/check-task-sync.sh
+bash scripts/check-task-workflow.sh --strict
+bash scripts/migrate-project-template.sh --repo . --dry-run
+```
+
+The self-host repository uses content-addressed test governance: ordinary
+verification runs the affected/task gate, and `bun run check:main` reuses that
+focused receipt without expanding to the full suite. Full testing is an
+explicit manual diagnostic, not an ordinary, CI, or release gate.
+
+For migration-focused work, also inspect and dry-run legacy doc migration explicitly:
+
+```bash
+bun scripts/inspect-project-state.ts --repo . --format text
+bun scripts/migrate-workflow-docs.ts --repo . --dry-run
+```
+
+## Iteration Notes
+
+- Keep this file short; detailed policy belongs in `docs/reference-configs/`
+- Keep stack-specific detail in assets and references, not in this skill body
+- If the router changes, update `evals/evals.json`
+- If the contract changes, update templates, migration, checks, and tests together

package/SUPPORT.md

@@ -0,0 +1,31 @@
+# Support
+
+Forge is currently in release-candidate hardening. Support is best-effort and focused on reproducible installation, first-run setup, repository safety, ChatGPT connectivity, Runtime recovery, and release-blocking defects.
+
+## Before asking for help
+
+Run:
+
+```bash
+forge --version
+forge setup status
+forge doctor
+forge status --json
+forge repo list --json
+```
+
+Forge does not provide previous-product command aliases. Redact tokens, OAuth material, private repository names, absolute home paths, email addresses, and proprietary source before sharing output.
+
+## Where to ask
+
+- Reproducible bugs: use the **Bug report** issue template.
+- Documentation errors: use the **Documentation** template.
+- Setup or usage questions: use the **Support question** template or GitHub Discussions.
+- Feature proposals: use the **Feature request** template.
+- Vulnerabilities: follow [SECURITY.md](SECURITY.md), never a public issue.
+
+Issues should remain actionable and tied to a reproducible problem or a concrete documentation gap. Discussions are better for open-ended workflow questions and usage patterns.
+
+## Useful details
+
+Include the operating system, Node and Bun versions, installation method, exact command, expected result, actual result, and the smallest redacted log excerpt that demonstrates the problem. For Runtime incidents, also include local Forge Runtime readiness, standalone Recovery status, restart-attempt and rollback evidence, the public MCP result, and whether the external tunnel was reachable.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,18 @@
+# Third-party notices
+
+This inventory covers the direct runtime and development dependencies declared by `@moretea-labs/forge@1.5.0-rc.1`.
+
+License values come from `package-lock.json` where available. For lock entries without a license field, the declared license was verified from package metadata during release-candidate preparation. This file is informational and does not replace the license text distributed by each dependency.
+
+| Package | Version | Role | Declared license | Source |
+| --- | --- | --- | --- | --- |
+| `@modelcontextprotocol/sdk` | `1.29.0` | runtime | `MIT` | package-lock.json |
+| `commander` | `14.0.3` | runtime | `MIT` | package metadata |
+| `express` | `5.2.1` | runtime | `MIT` | package metadata |
+| `playwright` | `1.61.1` | runtime | `Apache-2.0` | package metadata |
+| `agent-device` | `0.20.2` | optional runtime (iOS/Android device automation provider) | `MIT` | package-lock.json |
+| `@colbymchenry/codegraph` | `1.0.1` | development | `MIT` | package-lock.json |
+| `@types/bun` | `1.3.14` | development | `MIT` | package-lock.json |
+| `@types/cors` | `2.8.19` | development | `MIT` | package-lock.json |
+| `@types/express` | `5.0.6` | development | `MIT` | package-lock.json |
+| `typescript` | `6.0.3` | development | `Apache-2.0` | package metadata |

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "forge"
+  short_description: "Operate Forge workflows for repository planning, execution, verification, migration, audit, and repair"
+  default_prompt: "Use Forge to inspect this repository, choose the smallest appropriate workflow, and carry out or plan the requested work with bounded evidence and verification."