From 6f202751287fb6479e6702c53f8c9f69b6f285e5 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Sat, 30 May 2026 19:12:16 +0900 Subject: [PATCH] docs(omo-codex): batch 89 (12 files) --- .../plugin/components/ulw-loop/.gitattributes | 13 ++++ .../plugin/components/ulw-loop/.gitignore | 6 ++ .../plugin/components/ulw-loop/AGENTS.md | 48 ++++++++++++ .../plugin/components/ulw-loop/CHANGELOG.md | 7 ++ .../plugin/components/ulw-loop/LICENSE | 21 ++++++ .../plugin/components/ulw-loop/NOTICE | 6 ++ .../plugin/components/ulw-loop/README.md | 74 +++++++++++++++++++ .../plugin/components/ulw-loop/biome.json | 48 ++++++++++++ .../plugin/components/ulw-loop/package.json | 55 ++++++++++++++ .../components/ulw-loop/tsconfig.build.json | 12 +++ .../plugin/components/ulw-loop/tsconfig.json | 27 +++++++ .../components/ulw-loop/vitest.config.ts | 10 +++ 12 files changed, 327 insertions(+) create mode 100644 packages/omo-codex/plugin/components/ulw-loop/.gitattributes create mode 100644 packages/omo-codex/plugin/components/ulw-loop/.gitignore create mode 100644 packages/omo-codex/plugin/components/ulw-loop/AGENTS.md create mode 100644 packages/omo-codex/plugin/components/ulw-loop/CHANGELOG.md create mode 100644 packages/omo-codex/plugin/components/ulw-loop/LICENSE create mode 100644 packages/omo-codex/plugin/components/ulw-loop/NOTICE create mode 100644 packages/omo-codex/plugin/components/ulw-loop/README.md create mode 100644 packages/omo-codex/plugin/components/ulw-loop/biome.json create mode 100644 packages/omo-codex/plugin/components/ulw-loop/package.json create mode 100644 packages/omo-codex/plugin/components/ulw-loop/tsconfig.build.json create mode 100644 packages/omo-codex/plugin/components/ulw-loop/tsconfig.json create mode 100644 packages/omo-codex/plugin/components/ulw-loop/vitest.config.ts diff --git a/packages/omo-codex/plugin/components/ulw-loop/.gitattributes b/packages/omo-codex/plugin/components/ulw-loop/.gitattributes new file mode 100644 index 000000000..9363fdb74 --- /dev/null +++ b/packages/omo-codex/plugin/components/ulw-loop/.gitattributes @@ -0,0 +1,13 @@ +# Normalize line endings: store LF in git, check out LF on every platform. +# Required so biome's --check passes on Windows (default core.autocrlf=true). +* text=auto eol=lf + +# Explicit binary types +*.png binary +*.jpg binary +*.jpeg binary +*.gif binary +*.ico binary +*.zip binary +*.tgz binary +*.gz binary diff --git a/packages/omo-codex/plugin/components/ulw-loop/.gitignore b/packages/omo-codex/plugin/components/ulw-loop/.gitignore new file mode 100644 index 000000000..e5f7145b7 --- /dev/null +++ b/packages/omo-codex/plugin/components/ulw-loop/.gitignore @@ -0,0 +1,6 @@ +node_modules/ +dist/ +*.log +.DS_Store +coverage/ +.vitest/ diff --git a/packages/omo-codex/plugin/components/ulw-loop/AGENTS.md b/packages/omo-codex/plugin/components/ulw-loop/AGENTS.md new file mode 100644 index 000000000..54f1a3c03 --- /dev/null +++ b/packages/omo-codex/plugin/components/ulw-loop/AGENTS.md @@ -0,0 +1,48 @@ +# Repository Conventions + +Conventions for human contributors and AI agents working on this repository. + +## Stack + +- Node >=20 runtime. +- npm package manager. +- TypeScript 6 strict mode. +- Biome 2 linting and formatting. +- Vitest 4 test runner. + +## Forbidden + +- No `as any` or `as unknown`. +- No `@ts-ignore` or `@ts-expect-error`. +- No enums. +- No non-null assertions. +- No default exports. `vitest.config.ts` is exempt because the framework requires that shape. + +## File Ceiling + +- Keep each `src/` TypeScript file under 250 pure LOC. +- Split by responsibility before a file reaches the ceiling. + +## Test Discipline + +- Use Vitest with nested `describe` names in `#given`, `#when`, and `#then` form, or inline `// given`, `// when`, and `// then` comments. +- Never use Arrange-Act-Assert comments. +- Keep fixtures in `test/fixtures/`. + +## Commit Style + +- Use Conventional Commits. +- Keep commits atomic. +- Each commit's tests and build must pass on its own. + +## Branding + +- Repo artifacts live under `.omo/ulw-loop/` paths. +- Environment variables use the `OMO_ULW_LOOP_*` prefix. +- CLI commands use the `omo ulw-loop` form. +- Do not use any alternate legacy CLI alias anywhere. + +## Build and Hooks + +- Build output goes to `dist/`. +- `hooks/hooks.json` runs `node ${PLUGIN_ROOT}/dist/cli.js hook user-prompt-submit`. diff --git a/packages/omo-codex/plugin/components/ulw-loop/CHANGELOG.md b/packages/omo-codex/plugin/components/ulw-loop/CHANGELOG.md new file mode 100644 index 000000000..7145a3b66 --- /dev/null +++ b/packages/omo-codex/plugin/components/ulw-loop/CHANGELOG.md @@ -0,0 +1,7 @@ +# Changelog + +## [0.1.0] - unreleased + +- Initial scaffold of codex-ulw-loop plugin. +- Per-Criterion Cycle: `EXECUTE` is now **EXECUTE-AS-SCENARIO** — the agent must run the Manual-QA channel scenario the criterion named (HTTP call / tmux / browser use / computer use; see new `## Manual-QA channels` section). Inserted a new **CLEAN (PAIRED, NEVER SKIP)** step that tears down every QA-spawned process / `tmux` session / browser context / container / port / temp dir before recording evidence; the cleanup receipt is embedded in the `--evidence` string. Missing receipt → record BLOCKED, not PASS. Added Constraint #13 and a Stop Rule for leftover state. +- New top-level **`## Manual-QA channels`** section explicitly enumerates the four channels (HTTP call, tmux, Browser use, Computer use) with concrete commands and required artifacts. Goal section now declares **TESTS ALONE NEVER PROVE DONE**: a green test suite is supporting evidence, never completion proof. Criterion-refinement step 2 requires each criterion to name its channel up front. diff --git a/packages/omo-codex/plugin/components/ulw-loop/LICENSE b/packages/omo-codex/plugin/components/ulw-loop/LICENSE new file mode 100644 index 000000000..09aac3c3b --- /dev/null +++ b/packages/omo-codex/plugin/components/ulw-loop/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Yeongyu Kim + +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. diff --git a/packages/omo-codex/plugin/components/ulw-loop/NOTICE b/packages/omo-codex/plugin/components/ulw-loop/NOTICE new file mode 100644 index 000000000..01b3ff903 --- /dev/null +++ b/packages/omo-codex/plugin/components/ulw-loop/NOTICE @@ -0,0 +1,6 @@ +codex-ulw-loop + +This package provides the ulw-loop feature in a Codex plugin repository. + +The plugin targets Codex plugin manifests and plugin-bundled lifecycle hooks. +The orchestration engine is added in later port waves. diff --git a/packages/omo-codex/plugin/components/ulw-loop/README.md b/packages/omo-codex/plugin/components/ulw-loop/README.md new file mode 100644 index 000000000..a99d5e360 --- /dev/null +++ b/packages/omo-codex/plugin/components/ulw-loop/README.md @@ -0,0 +1,74 @@ +# codex-ulw-loop + +[![ci](https://img.shields.io/badge/ci-pending-lightgrey.svg)](#) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) + +Codex plugin scaffold for durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit. + +## Behavior + +| Subcommand | Purpose | +|------------|---------| +| `omo ulw-loop create-goals` | Create repo-native goals from a brief and seed criteria. | +| `omo ulw-loop record-evidence` | Record observable evidence for the active criterion. | +| `omo ulw-loop criteria` | Inspect or revise goal success criteria. | +| `omo ulw-loop complete-goals` | Complete eligible goals after criteria pass. | +| `omo ulw-loop checkpoint` | Refuse completion until criteria and evidence gates pass. | +| `omo ulw-loop steer` | Apply steering updates to the plan. | +| `omo ulw-loop status` | Report active goal, criteria, and evidence state. | + +Wave 1 is scaffold only. Command behavior lands in later waves. + +## Codex Plugin + +The plugin ships: + +- `.codex-plugin/plugin.json` for Codex plugin discovery. +- `hooks/hooks.json` for the `UserPromptSubmit` hook. +- `skills/ulw-loop/` as the future skill directory. + +The hook command is: + +```bash +node "${PLUGIN_ROOT}/dist/cli.js" hook user-prompt-submit +``` + +No MCP server or Codex tool is exposed in this scaffold. + +## Local Development + +```bash +npm install +npm test +npm run typecheck +npm run check +npm pack --dry-run +``` + +## Local Codex Installation + +```bash +bunx lazycodex install +``` + +The installer builds and copies the plugin into `~/.codex/plugins/cache/sisyphuslabs/omo/0.1.0`, registers the `sisyphuslabs` marketplace from the `lazycodex` Git repository, installs runtime dependencies there, and enables: + +```toml +[features] +plugins = true +plugin_hooks = true + +[plugins."omo@sisyphuslabs"] +enabled = true +``` + +## Privacy + +This plugin runs locally. The scaffold does not call a network service by itself. + +## License + +[MIT](LICENSE). + +## Related + +- [lazycodex](https://github.com/code-yeongyu/lazycodex) - Sisyphus Labs Codex marketplace repository. diff --git a/packages/omo-codex/plugin/components/ulw-loop/biome.json b/packages/omo-codex/plugin/components/ulw-loop/biome.json new file mode 100644 index 000000000..5aa1a0dcc --- /dev/null +++ b/packages/omo-codex/plugin/components/ulw-loop/biome.json @@ -0,0 +1,48 @@ +{ + "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json", + "linter": { + "enabled": true, + "rules": { + "recommended": true, + "style": { + "noDefaultExport": "error", + "noEnum": "error", + "noNonNullAssertion": "error", + "useImportType": "error", + "useConst": "error", + "useNodejsImportProtocol": "off" + }, + "complexity": { + "useLiteralKeys": "off" + }, + "suspicious": { + "noExplicitAny": "error", + "noTsIgnore": "error", + "noControlCharactersInRegex": "off", + "noEmptyInterface": "off" + } + } + }, + "formatter": { + "enabled": true, + "formatWithErrors": false, + "indentStyle": "tab", + "indentWidth": 3, + "lineWidth": 120 + }, + "files": { + "includes": ["src/**/*.ts", "test/**/*.ts", "vitest.config.ts", "!**/node_modules/**/*", "!**/dist/**/*"] + }, + "overrides": [ + { + "includes": ["vitest.config.ts"], + "linter": { + "rules": { + "style": { + "noDefaultExport": "off" + } + } + } + } + ] +} diff --git a/packages/omo-codex/plugin/components/ulw-loop/package.json b/packages/omo-codex/plugin/components/ulw-loop/package.json new file mode 100644 index 000000000..06f46f6ef --- /dev/null +++ b/packages/omo-codex/plugin/components/ulw-loop/package.json @@ -0,0 +1,55 @@ +{ + "name": "@code-yeongyu/codex-ulw-loop", + "version": "0.1.0", + "description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.", + "type": "module", + "packageManager": "npm@11.12.1", + "license": "MIT", + "homepage": "https://github.com/code-yeongyu/codex-ulw-loop", + "repository": { + "type": "git", + "url": "git+https://github.com/code-yeongyu/codex-ulw-loop.git" + }, + "bugs": { + "url": "https://github.com/code-yeongyu/codex-ulw-loop/issues" + }, + "keywords": [ + "codex", + "codex-plugin", + "ulw-loop", + "goal-mode", + "orchestration", + "evidence", + "typescript" + ], + "bin": { + "omo": "./dist/cli.js" + }, + "files": [ + "dist", + "hooks", + "skills", + "LICENSE", + "NOTICE", + "README.md", + "CHANGELOG.md" + ], + "scripts": { + "build": "tsc -p tsconfig.build.json", + "test": "vitest --run", + "test:watch": "vitest", + "typecheck": "tsc --noEmit", + "lint": "biome check .", + "lint:fix": "biome check --write .", + "check": "tsc --noEmit && biome check . && npm run build" + }, + "devDependencies": { + "@biomejs/biome": "2.4.15", + "@types/node": "^25.7.0", + "typescript": "^6.0.3", + "vitest": "^4.1.5" + }, + "engines": { + "node": ">=20.0.0" + } +} diff --git a/packages/omo-codex/plugin/components/ulw-loop/tsconfig.build.json b/packages/omo-codex/plugin/components/ulw-loop/tsconfig.build.json new file mode 100644 index 000000000..5b5bbcafd --- /dev/null +++ b/packages/omo-codex/plugin/components/ulw-loop/tsconfig.build.json @@ -0,0 +1,12 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "allowImportingTsExtensions": false, + "declaration": true, + "outDir": "dist", + "rootDir": "src", + "noEmit": false + }, + "include": ["src/**/*"], + "exclude": ["test/**/*"] +} diff --git a/packages/omo-codex/plugin/components/ulw-loop/tsconfig.json b/packages/omo-codex/plugin/components/ulw-loop/tsconfig.json new file mode 100644 index 000000000..73e5001dd --- /dev/null +++ b/packages/omo-codex/plugin/components/ulw-loop/tsconfig.json @@ -0,0 +1,27 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "Node16", + "moduleResolution": "Node16", + "lib": ["ES2022"], + "strict": true, + "exactOptionalPropertyTypes": true, + "noUncheckedIndexedAccess": true, + "noPropertyAccessFromIndexSignature": true, + "verbatimModuleSyntax": true, + "noImplicitOverride": true, + "noImplicitReturns": true, + "noFallthroughCasesInSwitch": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "esModuleInterop": true, + "allowImportingTsExtensions": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "resolveJsonModule": true, + "useDefineForClassFields": false, + "types": ["node"], + "noEmit": true + }, + "include": ["src/**/*", "test/**/*", "vitest.config.ts"] +} diff --git a/packages/omo-codex/plugin/components/ulw-loop/vitest.config.ts b/packages/omo-codex/plugin/components/ulw-loop/vitest.config.ts new file mode 100644 index 000000000..5453488cc --- /dev/null +++ b/packages/omo-codex/plugin/components/ulw-loop/vitest.config.ts @@ -0,0 +1,10 @@ +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + test: { + include: ["test/**/*.test.ts"], + environment: "node", + pool: "threads", + isolate: true, + }, +});