@kylecheng3146/agent-ops 0.0.1

package/docs/en/spec/acceptance-and-evidence.md

@@ -0,0 +1,21 @@
+# Acceptance and Evidence
+
+## EVIDENCE-CRITERION-001
+
+Every acceptance criterion MUST map to observable evidence.
+
+- Trigger: Defining or reviewing task completion.
+- Action: Name a command, read-back, or artifact for each criterion.
+- Evidence: The final report contains one evidence reference per criterion.
+- Positive: `criterion tests → npm test (354 passing tests)`.
+- Negative: `The implementation looks correct, so no evidence is needed.`
+
+## EVIDENCE-AGGREGATE-001
+
+The verifier MUST return FAIL when a criterion is missing, duplicated, unknown, or has empty evidence.
+
+- Trigger: Combining independent verifier results.
+- Action: Require the exact requested criterion set once each; require non-empty evidence.
+- Evidence: The aggregate lists the criterion IDs and their evidence references.
+- Positive: `tests PASS [report.json]; scope PASS [diff.txt]`.
+- Negative: `tests PASS; tests PASS; extra PASS`.

package/docs/en/spec/delegation.md

@@ -0,0 +1,21 @@
+# Delegation
+
+## DELEGATE-SCOPE-001
+
+Delegation MUST use a bounded task with an explicit artifact, acceptance criteria, and return format.
+
+- Trigger: Investigation spans unknown files, broad scans, or independent workstreams.
+- Action: Send only the necessary context and require evidence-backed findings.
+- Evidence: The delegation record names scope, output, and verification.
+- Positive: `Inspect runtime/src/review and return affected files plus tests.`
+- Negative: `Explore the repository and fix anything you notice.`
+
+## DELEGATE-OWNERSHIP-001
+
+The coordinator MUST retain ownership of final integration and verification.
+
+- Trigger: A delegated task returns code, findings, or a proposed change.
+- Action: Read back the artifact, reconcile conflicts, and run the required gate.
+- Evidence: The coordinator records the final command output.
+- Positive: `Reviewer reports PASS; coordinator reruns typecheck and tests.`
+- Negative: `Accept the delegated claim without inspecting the diff.`

package/docs/en/spec/guardrails.md

@@ -0,0 +1,21 @@
+# Guardrails
+
+## GUARDRAIL-SECRET-001
+
+The system MUST redact credentials and MUST NOT persist secrets in prompts, logs, fixtures, or reports.
+
+- Trigger: Handling command output, configuration, or external input.
+- Action: Apply the shared redaction boundary and keep only bounded evidence.
+- Evidence: A redaction test proves representative credential forms are absent.
+- Positive: `Authorization header becomes a redacted marker.`
+- Negative: `Store raw environment variables for later debugging.`
+
+## GUARDRAIL-DESTRUCTIVE-001
+
+Destructive or forceful commands MUST be blocked unless an exact, explicit exception is present.
+
+- Trigger: A command can delete, overwrite, force-push, or alter protected state.
+- Action: Block by default and report the stable rule ID.
+- Evidence: Positive and negative command fixtures show the boundary.
+- Positive: `git push --mirror is blocked.`
+- Negative: `Allow every command containing a familiar sub-string.`

package/docs/en/spec/harness-adapters.md

@@ -0,0 +1,21 @@
+# Harness Adapters
+
+## HARNESS-ADAPTER-001
+
+An adapter MUST preserve native harness semantics and MUST label unsupported behavior as UNKNOWN.
+
+- Trigger: Mapping portable lifecycle or review behavior into a native harness.
+- Action: Keep ownership narrow, retain user configuration, and document limitations.
+- Evidence: Adapter tests cover existing configuration and unsupported outcomes.
+- Positive: `A Codex blocking outcome remains UNKNOWN when native denial is unconfirmed.`
+- Negative: `Assume Claude exit semantics apply to Codex.`
+
+## HARNESS-ADAPTER-002
+
+An adapter MUST be idempotent and MUST avoid deleting user-owned handlers.
+
+- Trigger: Installing, updating, or removing managed harness configuration.
+- Action: Change only stable managed markers or owned handlers.
+- Evidence: Existing configuration fixtures remain intact after apply and uninstall.
+- Positive: `Managed handler updates while unrelated handlers remain byte-for-byte present.`
+- Negative: `Replace the complete settings file with toolkit defaults.`

package/docs/en/spec/judgment.md

@@ -0,0 +1,21 @@
+# Judgment
+
+## JUDGMENT-STOP-001
+
+The operator MUST stop when requirements, authorization, or a required decision is materially ambiguous.
+
+- Trigger: The next action would choose product intent, security policy, or architecture for the user.
+- Action: Report the concrete ambiguity and request a decision.
+- Evidence: The handoff names the blocked choice and the safe alternatives.
+- Positive: `Ask whether project or user scope is intended before applying installation.`
+- Negative: `Assume project scope because it is more convenient.`
+
+## JUDGMENT-RETRY-001
+
+The operator MUST change approach after the same failure repeats without new information.
+
+- Trigger: The same command or diagnosis fails twice.
+- Action: inspect the failure boundary, then use a different bounded check or stop.
+- Evidence: The report records the repeated failure and the changed check.
+- Positive: `Switch from integration test to isolated fixture inspection after two identical failures.`
+- Negative: `Run the identical failing command indefinitely.`

package/docs/en/spec/loop-engineering.md

@@ -0,0 +1,23 @@
+# Loop Engineering
+
+This module defines the bounded loop used to plan, implement, verify, and hand off work.
+
+## LOOP-START-001
+
+The operator MUST state acceptance criteria before editing and MUST stop when each criterion has evidence.
+
+- Trigger: Starting a multi-step implementation or debugging loop.
+- Action: Record 2–5 observable criteria, then inspect only the files needed for the current step.
+- Evidence: The task record and final report link each criterion to a command or read-back.
+- Positive: `Criteria: tests pass; package builds; changed files are read back.`
+- Negative: `I changed the repository and will decide what success means afterward.`
+
+## LOOP-VERIFY-001
+
+The operator MUST run the smallest reliable proof for every acceptance criterion before claiming completion.
+
+- Trigger: A change appears implemented or a loop reaches a proposed stopping point.
+- Action: Run targeted tests first, then the required project gate, and report failures or unavailable checks.
+- Evidence: Command output contains a non-zero test count and the reported outcome.
+- Positive: `npm run typecheck && npm test` with all tests passing.
+- Negative: `The command exited 0 but discovered no tests; therefore it is proof.`

package/docs/en/spec/maintenance.md

@@ -0,0 +1,21 @@
+# Maintenance
+
+## MAINTAIN-BACKUP-001
+
+Before editing a rule, prompt, model table, memory, or hook, the operator MUST create and verify a recoverable backup when it contains no literal secret.
+
+- Trigger: A maintained policy or lifecycle file will change.
+- Action: Copy the source to the dated backup path and compare it before editing.
+- Evidence: The backup path and comparison command are recorded.
+- Positive: `cmp source backup` succeeds before the patch.
+- Negative: `Edit a hook in place without a recoverable copy.`
+
+## MAINTAIN-FACT-001
+
+Volatile harness facts MUST live in adapter or research documentation and MUST include a revalidation condition.
+
+- Trigger: Recording a versioned or vendor-specific behavior.
+- Action: State the source date and when it must be checked again.
+- Evidence: The document has a source and `Revalidate:` condition.
+- Positive: `Revalidate: when the vendor hook reference changes.`
+- Negative: `Treat a transient CLI flag as a permanent core rule.`

package/docs/en/spec/review.md

@@ -0,0 +1,21 @@
+# Review
+
+## REVIEW-INDEPENDENT-001
+
+An independent reviewer MUST receive a minimal packet containing the request, criteria, artifact references, and evidence requirements.
+
+- Trigger: A multi-step change reaches a review checkpoint.
+- Action: Omit implementation rationale, hidden reasoning, raw logs, and credentials.
+- Evidence: The packet keys and artifact references are visible without sensitive content.
+- Positive: `Packet contains criteria, files, and evidence requirements only.`
+- Negative: `Forward the complete session transcript and environment.`
+
+## REVIEW-RESULT-001
+
+A review result MUST preserve PASS, FAIL, or NOT_RUN and MUST NOT convert NOT_RUN into PASS.
+
+- Trigger: A reviewer CLI is missing, unauthenticated, or quota-limited.
+- Action: Return NOT_RUN with a copyable prompt and limitation.
+- Evidence: The result states harness, configured model or limitation, effort, and reason.
+- Positive: `NOT_RUN: login required; prompt is copyable.`
+- Negative: `No reviewer ran, but mark the change PASS.`

package/docs/en/spec/troubleshooting.md

@@ -0,0 +1,21 @@
+# Troubleshooting
+
+## TROUBLESHOOT-REPRO-001
+
+Troubleshooting MUST first capture a minimal reproducible symptom and its boundary.
+
+- Trigger: A failure is vague, intermittent, or crosses layers.
+- Action: Record the command, inputs, observed output, and smallest suspected owner.
+- Evidence: A fixture or command reproduces the symptom.
+- Positive: `Fixture reproduces the parser failure with exact argv.`
+- Negative: `Rewrite unrelated modules before reproducing the report.`
+
+## TROUBLESHOOT-SAFETY-001
+
+The operator MUST preserve the failing evidence before applying a fix.
+
+- Trigger: A regression test or diagnostic is available.
+- Action: Add or retain a regression test, then implement the smallest correction.
+- Evidence: The test fails before the fix and passes after it.
+- Positive: `RED parser test → GREEN parser test.`
+- Negative: `Delete the failing test because it is inconvenient.`

package/docs/zh-TW/spec/README.md

@@ -0,0 +1,13 @@
+# Loop Engineering 規範
+
+此目錄是英文規範的繁體中文導讀；規範 rule ID 以英文版本為準。
+
+- [迴圈工程](./loop-engineering.md)
+- [驗收與證據](./acceptance-and-evidence.md)
+- [判斷](./judgment.md)
+- [委派](./delegation.md)
+- [審查](./review.md)
+- [疑難排解](./troubleshooting.md)
+- [防護規則](./guardrails.md)
+- [維護](./maintenance.md)
+- [Harness adapter](./harness-adapters.md)

package/docs/zh-TW/spec/acceptance-and-evidence.md

@@ -0,0 +1,23 @@
+# 驗收與證據
+
+English source version: 2026-07-23. Revalidate: when the English specification changes.
+
+## EVIDENCE-CRITERION-001
+
+每項驗收條件 MUST 對應可觀察的證據。
+
+- Trigger: 定義或審查任務完成度。
+- Action: 為每項條件命名命令、讀回內容或產物。
+- Evidence: 最終報告為每項條件提供一個證據參照。
+- Positive: `tests → npm test（354 個測試通過）`。
+- Negative: `看起來正確，所以不需要證據。`
+
+## EVIDENCE-AGGREGATE-001
+
+驗證器 MUST 在條件缺少、重複、未知或證據為空時回傳 FAIL。
+
+- Trigger: 合併獨立驗證器結果。
+- Action: 僅接受精確的 criterion 集合且各一次，並要求非空證據。
+- Evidence: 聚合結果列出 criterion ID 與證據參照。
+- Positive: `tests PASS [report.json]；scope PASS [diff.txt]`。
+- Negative: `tests PASS；tests PASS；extra PASS`。

package/docs/zh-TW/spec/delegation.md

@@ -0,0 +1,23 @@
+# 委派
+
+English source version: 2026-07-23. Revalidate: when the English specification changes.
+
+## DELEGATE-SCOPE-001
+
+委派 MUST 使用有界任務，並明確指定產物、驗收條件與回傳格式。
+
+- Trigger: 調查涉及未知檔案、廣泛掃描或獨立工作流。
+- Action: 僅傳送必要上下文，要求有證據的發現。
+- Evidence: 委派紀錄列出範圍、輸出與驗證方式。
+- Positive: `檢查 runtime/src/review，回傳受影響檔案與測試。`
+- Negative: `探索整個 repo 並修正任何你看到的問題。`
+
+## DELEGATE-OWNERSHIP-001
+
+協調者 MUST 保留最終整合與驗證責任。
+
+- Trigger: 委派任務回傳程式碼、發現或變更提案。
+- Action: 讀回產物、調和衝突並執行必要 gate。
+- Evidence: 協調者記錄最終命令輸出。
+- Positive: `審查者回傳 PASS；協調者重新跑 typecheck 與測試。`
+- Negative: `不看 diff 就接受委派者的完成宣告。`

package/docs/zh-TW/spec/guardrails.md

@@ -0,0 +1,23 @@
+# 防護規則
+
+English source version: 2026-07-23. Revalidate: when the English specification changes.
+
+## GUARDRAIL-SECRET-001
+
+系統 MUST 遮罩憑證，且 MUST NOT 將秘密持久化到 prompt、log、fixture 或報告。
+
+- Trigger: 處理命令輸出、設定或外部輸入。
+- Action: 使用共用 redaction 邊界，只保留有界證據。
+- Evidence: redaction 測試證明代表性憑證形式不存在。
+- Positive: `Authorization header 變成 redacted marker。`
+- Negative: `為了除錯保存原始環境變數。`
+
+## GUARDRAIL-DESTRUCTIVE-001
+
+破壞性或強制命令 MUST 在沒有精確明確例外時被阻擋。
+
+- Trigger: 命令會刪除、覆寫、force-push 或改變受保護狀態。
+- Action: 預設阻擋並回報穩定 rule ID。
+- Evidence: 正反命令 fixture 展示邊界。
+- Positive: `git push --mirror 被阻擋。`
+- Negative: `允許所有包含熟悉子字串的命令。`

package/docs/zh-TW/spec/harness-adapters.md

@@ -0,0 +1,23 @@
+# Harness Adapter
+
+English source version: 2026-07-23. Revalidate: when the English specification changes.
+
+## HARNESS-ADAPTER-001
+
+Adapter MUST 保留原生 harness 語意，並將未支援行為標示為 UNKNOWN。
+
+- Trigger: 將可攜 lifecycle 或 review 行為映射到原生 harness。
+- Action: 保持 ownership 狹窄、保留使用者設定並記錄限制。
+- Evidence: adapter 測試涵蓋既有設定與未支援結果。
+- Positive: `Codex blocking outcome 未確認原生 denial 時保持 UNKNOWN。`
+- Negative: `假設 Claude exit semantics 適用 Codex。`
+
+## HARNESS-ADAPTER-002
+
+Adapter MUST 具備冪等性，且 MUST NOT 刪除使用者擁有的 handler。
+
+- Trigger: 安裝、更新或移除 managed harness 設定。
+- Action: 只變更穩定 managed marker 或 owned handler。
+- Evidence: 既有設定 fixture 在 apply 與 uninstall 後保持完整。
+- Positive: `更新 managed handler，無關 handler 仍逐位元存在。`
+- Negative: `以 toolkit defaults 取代整份 settings。`

package/docs/zh-TW/spec/judgment.md

@@ -0,0 +1,23 @@
+# 判斷
+
+English source version: 2026-07-23. Revalidate: when the English specification changes.
+
+## JUDGMENT-STOP-001
+
+當需求、授權或必要決策有重大歧義時，操作者 MUST 停止。
+
+- Trigger: 下一步會替使用者選擇產品意圖、安全政策或架構。
+- Action: 說明具體歧義並請使用者決定。
+- Evidence: 交接內容列出受阻選擇與安全替代方案。
+- Positive: `套用安裝前詢問要 project 或 user scope。`
+- Negative: `因為方便就假設 project scope。`
+
+## JUDGMENT-RETRY-001
+
+相同失敗在沒有新資訊時重複發生，操作者 MUST 改變方法。
+
+- Trigger: 同一命令或診斷失敗兩次。
+- Action: 檢查失敗邊界，改用另一個有界檢查或停止。
+- Evidence: 報告記錄重複失敗與改用的檢查。
+- Positive: `兩次相同失敗後改查隔離 fixture。`
+- Negative: `無限重跑完全相同的失敗命令。`

package/docs/zh-TW/spec/loop-engineering.md

@@ -0,0 +1,23 @@
+# 迴圈工程
+
+English source version: 2026-07-23. Revalidate: when the English specification changes.
+
+## LOOP-START-001
+
+操作者 MUST 在編輯前列出驗收條件，並在每項條件都有證據時停止。
+
+- Trigger: 開始多步驟實作或除錯迴圈。
+- Action: 記錄 2–5 個可觀察條件，只檢查目前步驟所需檔案。
+- Evidence: 任務紀錄與最終報告把每項條件連到命令或讀回內容。
+- Positive: `條件：測試通過；套件建置；讀回變更檔案。`
+- Negative: `先修改，再決定成功標準。`
+
+## LOOP-VERIFY-001
+
+操作者 MUST 在宣告完成前，為每項驗收條件執行最小且可靠的證明。
+
+- Trigger: 變更看似完成或迴圈準備停止。
+- Action: 先跑針對性測試，再跑必要 gate，並回報失敗或不可用檢查。
+- Evidence: 命令輸出包含非零測試數與結果。
+- Positive: `npm run typecheck && npm test` 且所有測試通過。
+- Negative: `命令 exit 0 但沒有發現測試，仍視為證明。`

package/docs/zh-TW/spec/maintenance.md

@@ -0,0 +1,23 @@
+# 維護
+
+English source version: 2026-07-23. Revalidate: when the English specification changes.
+
+## MAINTAIN-BACKUP-001
+
+編輯不含文字秘密的 rule、prompt、model table、memory 或 hook 前，操作者 MUST 建立並驗證可復原備份。
+
+- Trigger: 即將變更受維護的政策或 lifecycle 檔案。
+- Action: 編輯前把來源複製到日期化備份路徑並比較。
+- Evidence: 記錄備份路徑與比較命令。
+- Positive: `編輯前 cmp source backup 成功。`
+- Negative: `沒有可復原副本就直接修改 hook。`
+
+## MAINTAIN-FACT-001
+
+易變的 harness fact MUST 放在 adapter 或 research 文件，且 MUST 包含重驗條件。
+
+- Trigger: 記錄版本化或 vendor-specific 行為。
+- Action: 說明來源日期與何時重新檢查。
+- Evidence: 文件含來源與 `Revalidate:` 條件。
+- Positive: `Revalidate：vendor hook reference 變更時。`
+- Negative: `把暫時性的 CLI flag 當永久核心規則。`

package/docs/zh-TW/spec/review.md

@@ -0,0 +1,23 @@
+# 審查
+
+English source version: 2026-07-23. Revalidate: when the English specification changes.
+
+## REVIEW-INDEPENDENT-001
+
+獨立審查者 MUST 只收到包含請求、條件、產物參照與證據要求的最小 packet。
+
+- Trigger: 多步驟變更到達審查 checkpoint。
+- Action: 排除實作理由、隱藏推理、原始 log 與憑證。
+- Evidence: 可見 packet keys 與產物參照，且不含敏感內容。
+- Positive: `Packet 僅含條件、檔案與證據要求。`
+- Negative: `轉送完整 session transcript 與環境。`
+
+## REVIEW-RESULT-001
+
+審查結果 MUST 保留 PASS、FAIL 或 NOT_RUN，且 MUST NOT 把 NOT_RUN 轉成 PASS。
+
+- Trigger: 審查 CLI 缺少、未登入或 quota 不足。
+- Action: 回傳 NOT_RUN、可複製 prompt 與限制原因。
+- Evidence: 結果列出 harness、設定的 model 或限制、effort 與原因。
+- Positive: `NOT_RUN：需要登入；prompt 可複製。`
+- Negative: `沒有審查執行，仍標示 PASS。`

package/docs/zh-TW/spec/troubleshooting.md

@@ -0,0 +1,23 @@
+# 疑難排解
+
+English source version: 2026-07-23. Revalidate: when the English specification changes.
+
+## TROUBLESHOOT-REPRO-001
+
+疑難排解 MUST 先捕捉最小可重現症狀與邊界。
+
+- Trigger: 失敗模糊、間歇性或跨越多層。
+- Action: 記錄命令、輸入、觀察輸出與最小疑似 owner。
+- Evidence: fixture 或命令能重現症狀。
+- Positive: `fixture 以精確 argv 重現 parser 失敗。`
+- Negative: `先重寫無關模組再重現報告。`
+
+## TROUBLESHOOT-SAFETY-001
+
+操作者 MUST 在修正前保留失敗證據。
+
+- Trigger: 已有 regression test 或診斷。
+- Action: 新增或保留 regression test，再實作最小修正。
+- Evidence: 測試在修正前失敗、修正後通過。
+- Positive: `RED parser test → GREEN parser test。`
+- Negative: `因為不方便就刪除失敗測試。`

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@kylecheng3146/agent-ops",
+  "version": "0.0.1",
+  "description": "Evidence-driven development loops for Codex and Claude Code",
+  "type": "module",
+  "license": "MIT",
+  "repository": "github:kylecheng3146/agent-ops",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "bin": {
+    "agent-ops": "dist/packages/cli/src/bin.js"
+  },
+  "files": [
+    "dist/",
+    "schemas/",
+    "templates/",
+    "docs/en/spec/",
+    "docs/zh-TW/spec/",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node scripts/clean.mjs dist .tmp",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:compile": "node scripts/clean.mjs .tmp && tsc -p tsconfig.test.json",
+    "test": "npm run test:compile && node scripts/run-tests.mjs .tmp/test-dist/tests",
+    "build": "node scripts/clean.mjs dist && tsc -p tsconfig.build.json",
+    "package:check": "node scripts/package-check.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.1",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "typescript": "7.0.2"
+  }
+}