diff --git a/.gitignore b/.gitignore index 80d16751..ddddc58f 100644 --- a/.gitignore +++ b/.gitignore @@ -98,3 +98,5 @@ packages/*/.next.bak/ # Hybrid harness local artifacts packages/web/.tasks/ packages/web/.handoff/ +.tasks/locks/ +.handoff/ diff --git a/.harness/CODEX_CANARY.md b/.harness/CODEX_CANARY.md new file mode 100644 index 00000000..dccabbbd --- /dev/null +++ b/.harness/CODEX_CANARY.md @@ -0,0 +1,18 @@ +--- +title: Codex Canary +owner: human +status: draft +updated: 2026-05-28 +tags: [harness, codex] +--- + +# Codex Canary + +This file is the target for the repo-local Codex Hybrid canary TASK. + +Expected worker behavior: + +- Codex Fast edits only this file. +- This canary proves repo-root TASK dispatch works. +- Codex Strict reviews only the resulting diff. +- Claude or a human makes the final accept/reject decision. diff --git a/.harness/routing.md b/.harness/routing.md new file mode 100644 index 00000000..e5185da7 --- /dev/null +++ b/.harness/routing.md @@ -0,0 +1,60 @@ +--- +title: Codex Hybrid Routing +owner: human +status: approved +updated: 2026-05-28 +tags: [harness, codex] +--- + +# Codex Hybrid Routing + +This repo supports two Codex operating modes. They are intentionally different from Claude Code. + +## Direct Codex Session + +Use this when a human asks Codex to work directly in the current session. + +- Codex may read repo docs and implement normal scoped changes. +- Codex must respect `AGENTS.md`, repo-local docs, dirty worktree boundaries, and human instructions. +- Codex may use tests, browser QA, GitHub inspection, and package commands as needed. +- Codex must not self-approve its own work. Completion means implemented and verified, not accepted. + +## Hybrid Worker Lane + +Use this when Claude or a human dispatches `.tasks/TASK-*.md` cards through the Hybrid harness. + +- Entry point: `HARNESS_HOME=/Users/kiyeol/dotfiles/harness /Users/kiyeol/dotfiles/harness/scripts/orchestrate.sh` +- Task ledger: repo root `.tasks/` +- Handoff artifacts: repo root `.handoff/` +- Execute role: `owner: codex-fast`, `codex exec --profile fast` +- Review role: `reviewer: codex-strict`, `codex exec --profile strict` +- Final accept/reject: Claude or human only. + +## Routing Defaults + +| Work class | Owner | Reviewer | Final | +| --- | --- | --- | --- | +| Single-file low-risk product change | codex-fast | codex-strict | claude | +| Single-file docs change | codex-fast | codex-strict | claude | +| Harness routing/task-card change | claude | codex-strict | human | +| Multi-file change | claude splits first | n/a | claude | +| Auth, payment, migrations, secret handling | codex-strict or claude | human | human | + +## Hard Boundaries + +- Hybrid TASK cards must use `scope: single-file` and exactly one path in `files:`. +- Codex Fast must edit only the file listed in `files:`. +- Codex Fast must return `NEEDS_SPLIT` if one file is insufficient. +- Codex Strict is read-only and returns only review JSON. +- `.env*`, generated API clients, migrations, secrets, and local state artifacts are protected unless a human explicitly authorizes that task class. + +## Smoke Test + +Use the tracked canary TASK to verify dispatch wiring: + +```bash +HARNESS_HOME=/Users/kiyeol/dotfiles/harness HARNESS_DRY_DISPATCH=1 \ + /Users/kiyeol/dotfiles/harness/scripts/orchestrate.sh TASK-CODEX-CANARY +``` + +For a real worker smoke, run the same command without `HARNESS_DRY_DISPATCH=1`. That consumes Codex tokens and may update `.tasks/TASK-CODEX-CANARY.md` status plus `.harness/CODEX_CANARY.md`. diff --git a/.tasks/TASK-CODEX-CANARY.md b/.tasks/TASK-CODEX-CANARY.md new file mode 100644 index 00000000..3f8667c1 --- /dev/null +++ b/.tasks/TASK-CODEX-CANARY.md @@ -0,0 +1,21 @@ +--- +id: TASK-CODEX-CANARY +type: harness +owner: codex-fast +reviewer: codex-strict +final: human +scope: single-file +files: [".harness/CODEX_CANARY.md"] +status: review +constraints: + - "Edit only .harness/CODEX_CANARY.md." + - "Do not edit AGENTS.md, .harness/routing.md, .tasks, .handoff, or product code." + - "Keep the change small and documentation-only." +done_definition: + - "Add one short line under Expected worker behavior noting that this canary proves repo-root TASK dispatch." + - "No other file is modified by Codex Fast." +--- + +# TASK-CODEX-CANARY + +Verify that the repo-root Codex Hybrid worker lane can dispatch a single-file task and hand the diff to Codex Strict review. diff --git a/AGENTS.md b/AGENTS.md index 5305cef7..555897bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,6 +62,7 @@ | Rust API crate | `packages/api-server/AGENT.md` | | 아키텍처·컨벤션·스택 심층 | `.planning/codebase/` | | Harness 세션 규율 | `docs/wiki/wiki/harness/*` | +| Codex Hybrid routing | `.harness/routing.md`, `docs/wiki/wiki/harness/codex-cli.md` | ## 반드시 지킬 것 @@ -79,6 +80,7 @@ | ----------- | -------------------- | ------------------- | | gstack | 기획/리뷰/QA/배포 | Think → Plan → Ship | | Superpowers | TDD, 코드 품질 강제 | Build (구현) | +| Codex | 직접 자율 작업 또는 Hybrid Fast/Strict worker | scoped direct work / `.tasks` queue | | OMC | Claude + Gemini 듀얼 | 대규모 작업 보조 | | GSD quick | 원자적 단발 패치 | 유지보수 | diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 00000000..d2d55425 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,62 @@ +# Decoded Product Context + +This glossary defines product-domain language for decoded workflows that are implemented in this monorepo. + +## Language + +**Content Studio**: +An admin workflow for turning decoded posts into reviewable marketing content. +_Avoid_: Marketing studio, publish studio + +**Content Variant**: +A channel-specific marketing draft generated from a Content Studio packet. +_Avoid_: Post, asset, campaign + +**Instagram Feed Variant**: +A Content Variant intended for a single-image Instagram feed post. +_Avoid_: Carousel, reel, story, generic Instagram variant + +**Caption**: +The public text that accompanies an Instagram Feed Variant when it is published. +_Avoid_: Slide copy, body copy, script + +**Instagram Publish Account**: +An internal decoded Instagram account that admins can use to publish approved Content Variants. +_Avoid_: Facebook Page account, user OAuth account, Meta account + +**Publish Job**: +An auditable attempt to publish one approved Content Variant to one Instagram Publish Account. +_Avoid_: Retry state, delivery, upload + +**Review Status**: +The editorial approval state of a Content Variant before publishing. +_Avoid_: Publish status + +**Publish Status**: +The outcome state of a Publish Job. +_Avoid_: Review status + +**Publishable Asset**: +A Content Studio image asset that is eligible to be sent to an external publishing channel. +_Avoid_: Arbitrary URL, preview, attachment + +## Relationships + +- A **Content Studio** workflow produces one or more **Content Variants**. +- An **Instagram Feed Variant** is exactly one **Content Variant**. +- An **Instagram Feed Variant** has one **Caption**. +- A **Publish Job** targets exactly one approved **Instagram Feed Variant** and one **Instagram Publish Account**. +- A **Publish Job** uses exactly one **Publishable Asset**. +- A **Review Status** belongs to a **Content Variant**; a **Publish Status** belongs to a **Publish Job**. + +## Example Dialogue + +> **Dev:** "Can this approved carousel use the Instagram publishing button?" +> **Domain expert:** "No. The first publishing slice only supports an approved **Instagram Feed Variant** through the internal **Instagram Publish Account**." + +## Flagged Ambiguities + +- "Instagram account" can mean a personal OAuth account, a Facebook Page-backed account, or decoded's internal publishing account. Resolved: this slice uses **Instagram Publish Account** for the internal decoded account only. +- "media URL" can mean any public URL or a Content Studio-owned asset. Resolved: publishing uses a **Publishable Asset**, not an arbitrary URL. +- "account selection" can mean choosing among multiple social accounts or using the configured internal account. Resolved: this slice has one **Instagram Publish Account** and no account picker. +- "status" can mean editorial review or external publishing outcome. Resolved: use **Review Status** for Content Variants and **Publish Status** for Publish Jobs. diff --git a/docs/wiki/schema/ownership-matrix.md b/docs/wiki/schema/ownership-matrix.md index e952923e..4597908e 100644 --- a/docs/wiki/schema/ownership-matrix.md +++ b/docs/wiki/schema/ownership-matrix.md @@ -2,7 +2,7 @@ title: Ownership Matrix owner: human status: approved -updated: 2026-05-21 +updated: 2026-05-28 tags: [harness, agent] related: - docs/wiki/schema/frontmatter.md @@ -30,6 +30,7 @@ related: | 에이전트 운영·Gotchas | `docs/wiki/wiki/**` | `docs/agent/README.md` | | 에이전트별 프로필 | `docs/ai-playbook/*.md` | `docs/agent/ai-playbook-summary.md` | | 하네스 규칙 (gstack·Superpowers·OMC·GSD 경계) | `docs/wiki/schema/harness.md` | `CLAUDE.md`, `.cursor/rules` | +| Codex Hybrid routing | `.harness/routing.md` | `AGENTS.md`, `docs/wiki/wiki/harness/codex-cli.md`, `docs/agent/README.md` | | Git workflow | `docs/GIT-WORKFLOW.md` | `CLAUDE.md` | | React/API/Rust 코드 패턴 | `.cursor/rules/{react-components,api-routes,rust-api}.mdc` | `docs/wiki/schema/conventions.md` (요약 링크) | | ADR (Architectural Decisions) | vault `Architecture/adr/` | `docs/adr/index.md` | diff --git a/docs/wiki/schema/tags.md b/docs/wiki/schema/tags.md index 2fe24b1c..753ff060 100644 --- a/docs/wiki/schema/tags.md +++ b/docs/wiki/schema/tags.md @@ -46,6 +46,7 @@ related: | `gsd` | GSD 워크플로우 | | `obsidian` | Obsidian vault | | `telegram` | Telegram 봇 연동 | +| `codex` | Codex CLI 관련 | ## 수명 주기 (lifecycle) diff --git a/docs/wiki/wiki/harness/codex-cli.md b/docs/wiki/wiki/harness/codex-cli.md new file mode 100644 index 00000000..482b4a17 --- /dev/null +++ b/docs/wiki/wiki/harness/codex-cli.md @@ -0,0 +1,56 @@ +--- +title: Codex CLI — Harness Knowledge +owner: human +status: approved +updated: 2026-05-28 +tags: [harness, agent, codex] +related: + - AGENTS.md + - .harness/routing.md + - docs/wiki/wiki/harness/review-flow.md +--- + +# Codex CLI — Harness Knowledge + +Codex is active in this repo again, but it is not a Claude Code clone. It has two supported modes. + +## Direct Session Mode + +Use a normal Codex session for scoped autonomous work when the human is directly supervising Codex. In this mode Codex can inspect the repo, edit files, run checks, and report verification. It still must not self-approve or merge its own work. + +## Hybrid Worker Mode + +Use Hybrid when work should be task-card driven: + +```bash +HARNESS_HOME=/Users/kiyeol/dotfiles/harness \ + /Users/kiyeol/dotfiles/harness/scripts/orchestrate.sh +``` + +The root `.tasks/` directory is the task ledger. The root `.handoff/` directory is generated local output and is ignored by git. `owner: codex-fast` executes one file. `reviewer: codex-strict` reviews that file's diff. Claude or a human remains the final decision maker. + +## Readiness Checks + +```bash +HARNESS_HOME=/Users/kiyeol/dotfiles/harness \ + /Users/kiyeol/dotfiles/harness/scripts/codex-env-check.sh +``` + +```bash +HARNESS_HOME=/Users/kiyeol/dotfiles/harness HARNESS_DRY_DISPATCH=1 \ + /Users/kiyeol/dotfiles/harness/scripts/orchestrate.sh TASK-CODEX-CANARY +``` + +The first command verifies the global harness and creates local working directories. The second verifies repo-root TASK discovery without consuming model tokens. + +## Known Local Notes + +- `codex-env-check.sh` may warn on `codex auth status` because the current CLI uses `codex login status`. Treat that warning as non-blocking when `codex login status` succeeds. +- Running a nested `codex exec` from inside another sandboxed Codex session may require approval outside the sandbox. Without that approval, the canary can fail before producing `.handoff/TASK-CODEX-CANARY.exec.json`. + +## Current Boundaries + +- The canonical repo-local routing file is `.harness/routing.md`. +- The global script implementation lives in `/Users/kiyeol/dotfiles/harness` and is not edited from this repo. +- `packages/web/.tasks` and `packages/web/.handoff` are legacy package-local artifacts. New whole-repo Hybrid work uses root `.tasks` and `.handoff`. +- `docs/ai-playbook/codex-profile.md` describes current Codex use; older issue-to-spec prompting is historical only.