@sayoriqwq/effect-harness 0.0.1

package/dist/src/platform/Json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Json.js","sourceRoot":"","sources":["../../../src/platform/Json.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEjE,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAA;AAC9C,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAY;IACrC,OAAO,IAAI;SACR,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC;SACjC,OAAO,CAAC,sBAAsB,EAAE,IAAI,CAAC,CAAA;AAC1C,CAAC;AAED,MAAM,UAAU,SAAS,CAAI,IAAY,EAAE,MAAc,EAAE,MAA0E;IACnI,OAAO,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACzB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;YAC9B,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY;YACtC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,IAAI,YAAY,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,wBAAwB,MAAM,KAAK,YAAY,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;SACtH,CAAC,CAAA;QACF,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,MAAc,EACd,MAA0E;IAE1E,OAAO,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACzB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,UAAU,CAAC,UAAU,CAAA;QACvC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;QAC7C,OAAO,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,MAAc,EACd,MAA0E;IAE1E,OAAO,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACzB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,UAAU,CAAC,UAAU,CAAA;QACvC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;QAC7C,OAAO,KAAK,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAClE,CAAC,CAAC,CAAA;AACJ,CAAC","sourcesContent":["import type * as PlatformError from 'effect/PlatformError'\nimport * as Effect from 'effect/Effect'\nimport * as FileSystem from 'effect/FileSystem'\nimport { errorMessage, HarnessError } from '../harness/Errors.ts'\n\nexport function formatJson(value: unknown): string {\n  return `${JSON.stringify(value, null, 2)}\\n`\n}\n\nfunction stripJsonComments(text: string): string {\n  return text\n    .replace(/\\/\\*[\\s\\S]*?\\*\\//gu, '')\n    .replace(/(^|[^:\\\\])\\/\\/.*$/gmu, '$1')\n}\n\nexport function parseJson<A>(text: string, source: string, decode: (value: unknown, source: string) => Effect.Effect<A, HarnessError>): Effect.Effect<A, HarnessError> {\n  return Effect.gen(function* () {\n    const value = yield* Effect.try({\n      try: () => JSON.parse(text) as unknown,\n      catch: error => new HarnessError({ cause: error, message: `Cannot parse JSON at ${source}: ${errorMessage(error)}` }),\n    })\n    return yield* decode(value, source)\n  })\n}\n\nexport function readJson<A>(\n  source: string,\n  decode: (value: unknown, source: string) => Effect.Effect<A, HarnessError>,\n): Effect.Effect<A, HarnessError | PlatformError.PlatformError, FileSystem.FileSystem> {\n  return Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem\n    const text = yield* fs.readFileString(source)\n    return yield* parseJson(text, source, decode)\n  })\n}\n\nexport function readJsonLike<A>(\n  source: string,\n  decode: (value: unknown, source: string) => Effect.Effect<A, HarnessError>,\n): Effect.Effect<A, HarnessError | PlatformError.PlatformError, FileSystem.FileSystem> {\n  return Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem\n    const text = yield* fs.readFileString(source)\n    return yield* parseJson(stripJsonComments(text), source, decode)\n  })\n}\n"]}

package/dist/src/platform/ManagedFiles.d.ts

@@ -0,0 +1,8 @@
+import type * as PlatformError from 'effect/PlatformError';
+import type { ManagedWriteOptions } from '../harness/Model.ts';
+import * as Effect from 'effect/Effect';
+import * as FileSystem from 'effect/FileSystem';
+import * as Path from 'effect/Path';
+export declare const ensureDirectory: (targetPath: string, options: ManagedWriteOptions, changes: string[]) => Effect.Effect<void, PlatformError.PlatformError, FileSystem.FileSystem>;
+export declare const writeManagedFile: (targetPath: string, content: string, options: ManagedWriteOptions, changes: string[]) => Effect.Effect<void, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path>;
+export declare function copyRuntimeDirectory(source: string, target: string, replacements: Readonly<Record<string, string>>, options: ManagedWriteOptions, changes: Array<string>): Effect.Effect<void, Error | PlatformError.PlatformError, FileSystem.FileSystem | Path.Path>;

package/dist/src/platform/ManagedFiles.js

@@ -0,0 +1,59 @@
+import * as Effect from 'effect/Effect';
+import * as FileSystem from 'effect/FileSystem';
+import * as Path from 'effect/Path';
+import { HarnessError } from "../harness/Errors.js";
+export const ensureDirectory = Effect.fnUntraced(function* (targetPath, options, changes) {
+    const fs = yield* FileSystem.FileSystem;
+    const exists = yield* fs.exists(targetPath);
+    if (exists) {
+        return;
+    }
+    changes.push(`create directory ${targetPath}`);
+    if (!options.dryRun) {
+        yield* fs.makeDirectory(targetPath, { recursive: true });
+    }
+});
+export const writeManagedFile = Effect.fnUntraced(function* (targetPath, content, options, changes) {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const exists = yield* fs.exists(targetPath);
+    const current = exists ? yield* fs.readFileString(targetPath) : undefined;
+    if (current === content) {
+        return;
+    }
+    changes.push(`${exists ? 'update' : 'create'} ${targetPath}`);
+    if (!options.dryRun) {
+        yield* fs.makeDirectory(path.dirname(targetPath), { recursive: true });
+        yield* fs.writeFileString(targetPath, content);
+    }
+});
+function replaceTokens(text, replacements) {
+    let next = text;
+    for (const [key, value] of Object.entries(replacements)) {
+        next = next.replaceAll(key, value);
+    }
+    return next;
+}
+export function copyRuntimeDirectory(source, target, replacements, options, changes) {
+    return Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const exists = yield* fs.exists(source);
+        if (!exists) {
+            return yield* new HarnessError({ message: `Missing runtime source: ${source}` });
+        }
+        const entries = yield* fs.readDirectory(source);
+        for (const child of entries) {
+            const sourcePath = path.join(source, child);
+            const targetPath = path.join(target, child);
+            const entry = yield* fs.stat(sourcePath);
+            if (entry.type === 'Directory') {
+                yield* copyRuntimeDirectory(sourcePath, targetPath, replacements, options, changes);
+                continue;
+            }
+            const content = replaceTokens(yield* fs.readFileString(sourcePath), replacements);
+            yield* writeManagedFile(targetPath, content, options, changes);
+        }
+    });
+}
+//# sourceMappingURL=ManagedFiles.js.map

package/dist/src/platform/ManagedFiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManagedFiles.js","sourceRoot":"","sources":["../../../src/platform/ManagedFiles.ts"],"names":[],"mappings":"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","sourcesContent":["import type * as PlatformError from 'effect/PlatformError'\nimport type { ManagedWriteOptions } from '../harness/Model.ts'\nimport * as Effect from 'effect/Effect'\nimport * as FileSystem from 'effect/FileSystem'\nimport * as Path from 'effect/Path'\nimport { HarnessError } from '../harness/Errors.ts'\n\nexport const ensureDirectory = Effect.fnUntraced(function* (\n  targetPath: string,\n  options: ManagedWriteOptions,\n  changes: Array<string>,\n) {\n  const fs = yield* FileSystem.FileSystem\n  const exists = yield* fs.exists(targetPath)\n  if (exists) {\n    return\n  }\n\n  changes.push(`create directory ${targetPath}`)\n  if (!options.dryRun) {\n    yield* fs.makeDirectory(targetPath, { recursive: true })\n  }\n})\n\nexport const writeManagedFile = Effect.fnUntraced(function* (\n  targetPath: string,\n  content: string,\n  options: ManagedWriteOptions,\n  changes: Array<string>,\n) {\n  const fs = yield* FileSystem.FileSystem\n  const path = yield* Path.Path\n  const exists = yield* fs.exists(targetPath)\n  const current = exists ? yield* fs.readFileString(targetPath) : undefined\n  if (current === content) {\n    return\n  }\n\n  changes.push(`${exists ? 'update' : 'create'} ${targetPath}`)\n  if (!options.dryRun) {\n    yield* fs.makeDirectory(path.dirname(targetPath), { recursive: true })\n    yield* fs.writeFileString(targetPath, content)\n  }\n})\n\nfunction replaceTokens(text: string, replacements: Readonly<Record<string, string>>): string {\n  let next = text\n  for (const [key, value] of Object.entries(replacements)) {\n    next = next.replaceAll(key, value)\n  }\n  return next\n}\n\nexport function copyRuntimeDirectory(\n  source: string,\n  target: string,\n  replacements: Readonly<Record<string, string>>,\n  options: ManagedWriteOptions,\n  changes: Array<string>,\n): Effect.Effect<void, Error | PlatformError.PlatformError, FileSystem.FileSystem | Path.Path> {\n  return Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem\n    const path = yield* Path.Path\n    const exists = yield* fs.exists(source)\n    if (!exists) {\n      return yield* new HarnessError({ message: `Missing runtime source: ${source}` })\n    }\n\n    const entries = yield* fs.readDirectory(source)\n    for (const child of entries) {\n      const sourcePath = path.join(source, child)\n      const targetPath = path.join(target, child)\n      const entry = yield* fs.stat(sourcePath)\n      if (entry.type === 'Directory') {\n        yield* copyRuntimeDirectory(sourcePath, targetPath, replacements, options, changes)\n        continue\n      }\n\n      const content = replaceTokens(yield* fs.readFileString(sourcePath), replacements)\n      yield* writeManagedFile(targetPath, content, options, changes)\n    }\n  })\n}\n"]}

package/dist/src/platform/Process.d.ts

@@ -0,0 +1,8 @@
+import * as Effect from 'effect/Effect';
+import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ProcessError } from '../harness/Errors.ts';
+export declare const commandExitCode: (command: string, args: readonly string[], options?: ChildProcess.CommandOptions | undefined) => Effect.Effect<ChildProcessSpawner.ExitCode, import("effect/PlatformError").PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
+export declare const commandString: (command: string, args: readonly string[], options?: ChildProcess.CommandOptions | undefined) => Effect.Effect<string, ProcessError | import("effect/PlatformError").PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
+export declare const commandOutput: (command: string, args: readonly string[], options?: ChildProcess.CommandOptions | undefined) => Effect.Effect<string, ProcessError | import("effect/PlatformError").PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
+export declare const commandLines: (command: string, args: readonly string[], options?: ChildProcess.CommandOptions | undefined) => Effect.Effect<string[], ProcessError | import("effect/PlatformError").PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
+export declare const runStreaming: (command: string, args: readonly string[], options?: ChildProcess.CommandOptions | undefined) => Effect.Effect<undefined, ProcessError | import("effect/PlatformError").PlatformError, ChildProcessSpawner.ChildProcessSpawner>;

package/dist/src/platform/Process.js

@@ -0,0 +1,80 @@
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+import * as Str from 'effect/String';
+import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ProcessError } from "../harness/Errors.js";
+export const commandExitCode = Effect.fnUntraced(function* (command, args, options) {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    return yield* spawner.exitCode(ChildProcess.make(command, args, options));
+});
+export const commandString = Effect.fnUntraced(function* (command, args, options) {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    return yield* Effect.scoped(Effect.gen(function* () {
+        const handle = yield* spawner.spawn(ChildProcess.make(command, args, options));
+        const [stdout, stderr] = yield* Effect.all([
+            Stream.mkString(Stream.decodeText(handle.stdout)),
+            Stream.mkString(Stream.decodeText(handle.stderr)),
+        ]);
+        const exitCode = yield* handle.exitCode;
+        if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
+            return yield* new ProcessError({
+                args,
+                command,
+                ...(options?.cwd !== undefined ? { cwd: options.cwd } : {}),
+                exitCode: Number(exitCode),
+                message: `${command} ${args.join(' ')} failed with exit code ${exitCode}`,
+                stderr,
+                stdout,
+            });
+        }
+        return Str.trim(stdout);
+    }));
+});
+export const commandOutput = Effect.fnUntraced(function* (command, args, options) {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    return yield* Effect.scoped(Effect.gen(function* () {
+        const handle = yield* spawner.spawn(ChildProcess.make(command, args, options));
+        const [stdout, stderr] = yield* Effect.all([
+            Stream.mkString(Stream.decodeText(handle.stdout)),
+            Stream.mkString(Stream.decodeText(handle.stderr)),
+        ]);
+        const exitCode = yield* handle.exitCode;
+        if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
+            return yield* new ProcessError({
+                args,
+                command,
+                ...(options?.cwd !== undefined ? { cwd: options.cwd } : {}),
+                exitCode: Number(exitCode),
+                message: `${command} ${args.join(' ')} failed with exit code ${exitCode}`,
+                stderr,
+                stdout,
+            });
+        }
+        return stdout;
+    }));
+});
+export const commandLines = Effect.fnUntraced(function* (command, args, options) {
+    const output = yield* commandString(command, args, options);
+    return output.length === 0 ? [] : output.split('\n');
+});
+export const runStreaming = Effect.fnUntraced(function* (command, args, options) {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    return yield* Effect.scoped(Effect.gen(function* () {
+        const handle = yield* spawner.spawn(ChildProcess.make(command, args, options));
+        yield* handle.all.pipe(Stream.decodeText(), Stream.splitLines, Stream.runForEach(line => Console.log(line)));
+        const exitCode = yield* handle.exitCode;
+        if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
+            return yield* new ProcessError({
+                args,
+                command,
+                ...(options?.cwd !== undefined ? { cwd: options.cwd } : {}),
+                exitCode: Number(exitCode),
+                message: `${command} ${args.join(' ')} failed with exit code ${exitCode}`,
+                stderr: '',
+                stdout: '',
+            });
+        }
+    }));
+});
+//# sourceMappingURL=Process.js.map

package/dist/src/platform/Process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Process.js","sourceRoot":"","sources":["../../../src/platform/Process.ts"],"names":[],"mappings":"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","sourcesContent":["import * as Console from 'effect/Console'\nimport * as Effect from 'effect/Effect'\nimport * as Stream from 'effect/Stream'\nimport * as Str from 'effect/String'\nimport { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process'\nimport { ProcessError } from '../harness/Errors.ts'\n\ntype CommandOptions = ChildProcess.CommandOptions\n\nexport const commandExitCode = Effect.fnUntraced(function* (\n  command: string,\n  args: ReadonlyArray<string>,\n  options?: CommandOptions,\n) {\n  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner\n  return yield* spawner.exitCode(ChildProcess.make(command, args, options))\n})\n\nexport const commandString = Effect.fnUntraced(function* (\n  command: string,\n  args: ReadonlyArray<string>,\n  options?: CommandOptions,\n) {\n  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner\n  return yield* Effect.scoped(Effect.gen(function* () {\n    const handle = yield* spawner.spawn(ChildProcess.make(command, args, options))\n    const [stdout, stderr] = yield* Effect.all([\n      Stream.mkString(Stream.decodeText(handle.stdout)),\n      Stream.mkString(Stream.decodeText(handle.stderr)),\n    ])\n    const exitCode = yield* handle.exitCode\n    if (exitCode !== ChildProcessSpawner.ExitCode(0)) {\n      return yield* new ProcessError({\n        args,\n        command,\n        ...(options?.cwd !== undefined ? { cwd: options.cwd } : {}),\n        exitCode: Number(exitCode),\n        message: `${command} ${args.join(' ')} failed with exit code ${exitCode}`,\n        stderr,\n        stdout,\n      })\n    }\n    return Str.trim(stdout)\n  }))\n})\n\nexport const commandOutput = Effect.fnUntraced(function* (\n  command: string,\n  args: ReadonlyArray<string>,\n  options?: CommandOptions,\n) {\n  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner\n  return yield* Effect.scoped(Effect.gen(function* () {\n    const handle = yield* spawner.spawn(ChildProcess.make(command, args, options))\n    const [stdout, stderr] = yield* Effect.all([\n      Stream.mkString(Stream.decodeText(handle.stdout)),\n      Stream.mkString(Stream.decodeText(handle.stderr)),\n    ])\n    const exitCode = yield* handle.exitCode\n    if (exitCode !== ChildProcessSpawner.ExitCode(0)) {\n      return yield* new ProcessError({\n        args,\n        command,\n        ...(options?.cwd !== undefined ? { cwd: options.cwd } : {}),\n        exitCode: Number(exitCode),\n        message: `${command} ${args.join(' ')} failed with exit code ${exitCode}`,\n        stderr,\n        stdout,\n      })\n    }\n    return stdout\n  }))\n})\n\nexport const commandLines = Effect.fnUntraced(function* (\n  command: string,\n  args: ReadonlyArray<string>,\n  options?: CommandOptions,\n) {\n  const output = yield* commandString(command, args, options)\n  return output.length === 0 ? [] : output.split('\\n')\n})\n\nexport const runStreaming = Effect.fnUntraced(function* (\n  command: string,\n  args: ReadonlyArray<string>,\n  options?: CommandOptions,\n) {\n  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner\n  return yield* Effect.scoped(Effect.gen(function* () {\n    const handle = yield* spawner.spawn(ChildProcess.make(command, args, options))\n    yield* handle.all.pipe(\n      Stream.decodeText(),\n      Stream.splitLines,\n      Stream.runForEach(line => Console.log(line)),\n    )\n    const exitCode = yield* handle.exitCode\n    if (exitCode !== ChildProcessSpawner.ExitCode(0)) {\n      return yield* new ProcessError({\n        args,\n        command,\n        ...(options?.cwd !== undefined ? { cwd: options.cwd } : {}),\n        exitCode: Number(exitCode),\n        message: `${command} ${args.join(' ')} failed with exit code ${exitCode}`,\n        stderr: '',\n        stdout: '',\n      })\n    }\n  }))\n})\n"]}

package/guide/default-capabilities.md

@@ -0,0 +1,38 @@
+# Default Harness Capabilities
+
+这份 guide 给人读，用来理解 `effect-harness` 默认补充了哪些官方 source 之外的工程保护。
+这些能力不是 Effect API 教程，也不是业务模板；它们来自 target/self practice feedback，
+并且已经落到 runtime、guardrail、verifier 或 repo-local skill。
+
+## 当前默认能力
+
+### Assertion-based tsgo suggestion cleanup
+
+`@effect/tsgo` suggestion 代表类型边界需要表达清楚。harness 默认要求优先用明确 return type、
+命名 result union/helper、`satisfies`、`Effect.satisfiesSuccessType` 或
+`Function.satisfies` 表达边界。
+
+默认保护：
+
+- target runtime 的 `effect-code` skill 会提示 agent 不要用 assertion 消音。
+- `effect-harness guardrails` 会拒绝 recurring assertion cleanup shapes。
+- `pnpm effect:verify` 和 `pnpm verify` 会执行这些 guardrails。
+
+会被拒绝的典型形态：
+
+- `Effect.orElseSucceed(() => [] as ...)`
+- `Effect.succeed(null as ...)`
+- ad-hoc `{ ok: true/false as const }` result wrappers
+
+确实来自第三方 IO 或不可表达外部边界时，可以使用局部 assertion，但应该先在 Effect 外声明边界，
+不要用 assertion 让 diagnostic 消失。
+
+## 新增默认能力
+
+新增默认能力前，先把 evidence 放进 `harness/feedback/index.md` 的 intake。
+只有同时满足这些条件才提升：
+
+- 官方 source 没有解释或捕获这个 practice failure。
+- 问题 business-neutral，并能跨 Effect targets 复用。
+- landing 是 guide、runtime、guardrail、verifier 或 repo-local skill。
+- drift 时有明确验证命令会失败。

package/guide/index.md

@@ -0,0 +1,49 @@
+# Effect Harness Guide
+
+这个目录是给人读的 guide 层。它帮助维护者和目标仓库用户理解 harness 怎么运作、
+从哪里补信息、以及实践问题如何反馈回来。
+
+如果你是在执行任务的 agent，优先读取 harness contract 层：
+
+- `harness/index.md`
+- `harness/exposure.md`
+- `harness/feedback/index.md`
+- `harness/target-agent-contract.md`
+- `repos/effect/LLMS.md`
+- `repos/effect.subtree.json`
+
+## 层级划分
+
+| Layer | Audience | Writing style | Files |
+| --- | --- | --- | --- |
+| Guide | 人 | 解释背景、路径和判断方式，优先可读性。 | `guide/` |
+| Harness contract | agent | 明确规则、输入、输出、验证命令和禁止事项。 | `harness/`、CLI/verifier |
+| Official source | 人和 agent | Effect 语义真源。 | `repos/effect/`、`@effect/tsgo` |
+
+Guide 可以解释为什么这样设计；harness contract 必须让 agent 知道具体该读什么、改什么、
+跑什么验证、哪些内容不能提升。
+
+## 阅读路径
+
+新接入目标仓库的人先读：
+
+- [Setup Guide](./setup.md)
+- [Default Harness Capabilities](./default-capabilities.md)
+
+维护本仓库的人先读：
+
+- [Default Harness Capabilities](./default-capabilities.md)
+- `harness/feedback/index.md`
+- `harness/exposure.md`
+
+## Feedback Loop
+
+实践反馈可以来自外部 target，也可以来自本仓库自己的 CLI/runtime/verifier 使用。
+反馈先进入 intake；只有能变成 reusable harness contract 的内容才提升。
+
+提升后的落点必须明确：
+
+- guide：帮助人理解怎么使用或判断。
+- runtime：由 `effect-harness init` 投递给 target。
+- guardrail/verifier：把 recurring failure 变成会失败的检查。
+- repo-local skill：维护本仓库 harness contract 的流程。

package/guide/setup.md

@@ -0,0 +1,64 @@
+# Setup Guide
+
+这份 guide 给刚接入 `effect-harness` 的人读。它解释 init 之后发生了什么，以及遇到缺口时
+应该去哪里补信息。
+
+## Init 做什么
+
+在目标仓库运行：
+
+```bash
+effect-harness init
+pnpm install
+pnpm effect:status
+pnpm effect:verify
+pnpm verify
+```
+
+`effect-harness init` 会写入：
+
+- `.effect-harness.json`
+- `package.json` scripts：`effect:status`、`effect:verify`
+- `tsconfig.json` 的 `@effect/language-service` plugin
+- `.codex/skills/effect-code/`
+- `.codex/skills/effect-feedback/`
+- `.codex/agents/effect-worker.md`
+- `AGENTS.md` 里的 harness route
+
+这些是 target runtime。目标仓库不需要复制本仓库的 `.codex/skills/`。
+`.effect-harness.json` 记录 harness root、可执行 commands、route、source pin 和 package baseline，
+agent 后续应先读它，再运行 target scripts。
+需要派出 focused Effect subagent 时，使用 `.codex/agents/effect-worker.md`。
+
+## 从哪里补信息
+
+Effect API、pattern、testing 和 migration 先读官方 source：
+
+- `repos/effect/LLMS.md`
+- `repos/effect/ai-docs/src/`
+- `repos/effect/migration/v3-to-v4.md`
+- patched `tsgo --noEmit`
+
+想理解 harness 默认提供了哪些补充保护，读：
+
+- [Default Harness Capabilities](./default-capabilities.md)
+
+agent 执行任务时读 harness contract：
+
+- `harness/index.md`
+- `harness/exposure.md`
+- `harness/feedback/index.md`
+- `harness/target-agent-contract.md`
+
+## 如何反馈回来
+
+如果目标仓库遇到 recurring Effect practice failure：
+
+1. 先检查官方 source 是否已经覆盖。
+2. 如果官方 source 已覆盖，直接 route 回官方 source。
+3. 如果没有覆盖，并且问题 business-neutral、可复用，用 target 的
+   `.codex/skills/effect-feedback/` 记录到 `.codex/effect-feedback/`。
+4. 维护者再判断是否提升到 `effect-harness/harness/feedback/`。
+
+能提升的反馈必须落成 guide、runtime、guardrail、verifier 或 repo-local skill。业务示例、
+产品语义、release ritual 和项目形态不进入 harness。

package/harness/default-capabilities.md

@@ -0,0 +1,32 @@
+# Default Harness Capabilities
+
+This is the agent-facing contract for default harness supplements. Human-readable explanation lives in
+`guide/default-capabilities.md`.
+
+## Assertion-based tsgo suggestion cleanup
+
+Treat `@effect/tsgo` suggestions as type-boundary work, not assertion cleanup.
+
+Preferred shapes:
+
+- explicit return types
+- named discriminated union helpers
+- `satisfies`
+- `Effect.satisfiesSuccessType`
+- `Function.satisfies`
+- `Schema.Finite` where applicable
+
+Rejected recurring shapes:
+
+- `Effect.orElseSucceed(() => [] as ...)`
+- `Effect.succeed(null as ...)`
+- ad-hoc `{ ok: true/false as const }` result wrappers
+
+Landing surfaces:
+
+- `harness/runtime/codex/skills/effect-code/SKILL.md`
+- `src/harness/GuardrailRules.ts`
+- `pnpm effect:verify`
+
+Exceptions must be explicit third-party IO or external boundary assertions, declared outside the Effect
+fallback or lifted value.

package/harness/exposure.md

@@ -0,0 +1,46 @@
+# Harness Exposure Boundary
+
+这份文件定义 `effect-harness` 允许向外暴露什么。
+
+本仓库只暴露稳定、business-neutral 的 harness contract：
+
+- pinned official Effect source 和 package baseline
+- official source drift status
+- `effect-harness init` 投递的 target runtime
+- target `AGENTS.md` route fragment
+- guardrails 和 verifier contracts
+- reusable practice feedback intake
+
+它不暴露 target business examples、product semantics、project shape、local distribution machinery
+或 upstream maintainer-only workflow。
+
+`publish` 只服务本仓库 npm package / CLI 分发，不是 target repo ritual。npm tarball 包含
+`repos/effect/` 是有意暴露：CLI、verifier、target route 和 agent 都需要 pinned official
+source/reference 与 `repos/effect.subtree.json` 保持同包可读。
+
+## Allowed Exposure
+
+| Surface | 是否投递给 target | Contract owner |
+| --- | --- | --- |
+| `repos/effect/LLMS.md` route | 是，作为 reference | official Effect source |
+| `harness/runtime/codex/` | 是，由 init 复制 | `effect-harness` |
+| `effect:status` / `effect:verify` scripts | 是，由 init 写入 | `src/harness/Init.ts` |
+| `.effect-harness.json` | 是，由 init 写入 | target verifier |
+| `harness/feedback/index.md` | 不直接复制 | harness maintainers |
+| `.codex/skills/` | 否 | repo-local maintenance only |
+
+Target setup 细节见 [target-agent-contract.md](./target-agent-contract.md)。
+Official source classification 见 [official-inventory.md](./official-inventory.md)。
+
+## Promotion Gate
+
+新增 exposure route 前必须回答：
+
+1. official Effect source 或 `@effect/tsgo` 是否已经提供 semantic rule 或 diagnostic？
+2. 哪个 pinned upstream artifact 能证明？
+3. 证据来自 external target，还是 harness-as-target practice？
+4. 这是 reusable harness contract，而不是 target business shape 吗？
+5. landing 是 guide、route、target runtime、guardrail、verifier 还是 repo-local skill？
+6. 后续 drift 由哪个 verifier 或 review path 捕获？
+
+只有通过这个 gate 的内容才属于本仓库。

package/harness/feedback/index.md

@@ -0,0 +1,60 @@
+# Harness Feedback
+
+这是 Effect harness 的 practice-to-contract feedback contract，给 agent 和维护者执行判断时读取。
+人类理解默认补充能力时读 `guide/default-capabilities.md`。
+
+Feedback 可以来自外部 target projects，也可以来自本仓库自己的 CLI/runtime/verifier dogfood。
+它不改写 Effect API 语义；Effect API 教学、业务示例、项目形态和 release ritual 不进入这里。
+官方 source 已覆盖的内容直接 route 到 pinned source。
+
+## Intake Rule
+
+新增 feedback item 前，先使用 target runtime 的 `.codex/skills/effect-feedback/` 或本仓库
+`.codex/skills/effect-feedback-maintainer/` 做判断。只有同时满足这些条件才写入：
+
+- target project 或本仓库 self dogfood 给出了 recurring Effect practice failure 的具体证据
+- `repos/effect/LLMS.md`, `repos/effect/ai-docs/src/`, `repos/effect/migration/v3-to-v4.md`,
+  pinned source 和 `@effect/tsgo` diagnostics 没有解释或捕获它
+- 问题是 business-neutral，并能跨 Effect targets 复用
+- landing 是 harness route、target runtime contract、guardrail、verifier 或 skill update
+
+不要添加 upstream maintainer-only workflow、project-specific product examples、local machine
+paths、downstream project shape details 或 generic Effect API tutorials。
+
+## Intake Entry Format
+
+这是本仓库的 feedback 记录格式，不是官方 Effect 格式。它只用于判断一个 practice failure
+是否应该进入 harness contract。
+
+```markdown
+## <short issue name>
+
+- Evidence:
+- Official coverage check:
+- Missing harness contract:
+- Proposed landing:
+- Verifier or guardrail:
+- Status:
+```
+
+## Default Harness Capabilities
+
+这一节记录已经由 harness 默认提供的补充能力。它们来自 practice feedback，但已经落成
+runtime、guardrail、verifier 或 repo-local skill，不再只是待判断 intake。
+
+### Assertion-based tsgo suggestion cleanup
+
+- Evidence: A target update produced non-blocking `@effect/tsgo` suggestions. The first cleanup used
+  `Effect.orElseSucceed(() => [] as ...)`, `Effect.succeed(null as ...)`, and
+  `{ ok: false as const }` result wrappers instead of declaring the type boundary.
+- Official coverage check: The pinned Effect source shows typed `orElseSucceed` fallbacks,
+  `Effect.fn(...)` transform arguments, and `satisfies` helpers, but it does not give target agents
+  a harness-level rule for avoiding assertion-based suggestion cleanup.
+- Missing harness contract: Target agents need to distinguish soft review guidance from hard verifier
+  failures when a tsgo suggestion can be silenced with `as`.
+- Proposed landing: Add target skill guidance for type-boundary fixes and an AST guardrail for the
+  recurring assertion-silencing shapes.
+- Verifier or guardrail: `effect-harness guardrails` rejects assertion fallback cleanup in
+  `Effect.orElseSucceed`, asserted values lifted directly by `Effect.succeed`, and ad-hoc
+  `ok: true/false as const` result wrappers.
+- Status: Landed.

package/harness/index.md

@@ -0,0 +1,22 @@
+# Harness Contract Index
+
+这是 agent-facing route table。给人读的说明在 `guide/`。
+
+## Route Matrix
+
+| Incoming intent | Read first | Authority | Action surface | Verify | Feedback path |
+| --- | --- | --- | --- | --- | --- |
+| Setup target repo | `harness/target-agent-contract.md` | `repos/effect.subtree.json`, `repos/effect/LLMS.md` | `effect-harness init`, `harness/runtime/codex/` | target `pnpm effect:verify`, `pnpm verify` | target `.codex/effect-feedback/` |
+| Write or review Effect code | target `AGENTS.md`, `harness/runtime/codex/skills/effect-code/SKILL.md` | `repos/effect/LLMS.md`, `repos/effect/ai-docs/src/`, patched `tsgo --noEmit` | target source/tests | target `pnpm verify` | target `.codex/effect-feedback/` |
+| Inspect default harness capability | `harness/default-capabilities.md` | landed feedback plus verifier/guardrail | `harness/runtime/codex/`, guardrails, verifier | `pnpm effect:verify` | `harness/feedback/index.md` |
+| Report recurring practice gap | `harness/feedback/index.md` | official source coverage check | target `.codex/effect-feedback/` or harness feedback entry | landing-specific | promote to guide/runtime/verifier |
+| Update official source pin | `harness/source.md` | `repos/effect.subtree.json`, official remote/npm tags | `repos/effect/`, package baseline files | subtree trailer, `pnpm verify`, `pnpm effect:status` | source update notes |
+| Maintain harness implementation | `harness/exposure.md` | harness contract plus tests | `src/`, `bin/`, `tests/` | `pnpm verify` | self dogfood feedback |
+
+## Boundaries
+
+- application 或 test code 不从 `repos/effect/` import。
+- 不复制 `.codex/skills/` 到 target repos；targets 只接收 `harness/runtime/codex/`。
+- 不创建 target-local dispatcher scripts。
+- 不把 target business examples、product semantics 或 release rituals 放进本仓库。
+- `guide/` 负责解释；`harness/` contract files 对 agent 具有规范性。

package/harness/official-inventory.md

@@ -0,0 +1,85 @@
+# Effect Official Harness Inventory
+
+这份文档记录 pin 住的 Effect source 中哪些文件可以作为 coding agents 和 LLM-assisted
+Effect development 的依据。
+
+Pinned source：
+
+```text
+repos/effect @ 95545bdc334f4cd27a14f3308e68114e5bed92f2
+```
+
+## Role
+
+pin 住的 Effect repository 是 Effect API、patterns、examples、testing guidance、
+migration map 和 diagnostics 的唯一真源。本仓库不重写 Effect 语义；它把真源转成
+可投递、可验证、可回流改进的 harness contract。
+
+## Source Classification
+
+harness 在向 target 暴露 upstream material 前，必须先分类：
+
+| Class | Upstream surface | Decision |
+| --- | --- | --- |
+| Authoritative guide | `repos/effect/LLMS.md` | Effect application coding guidance 的 single source of truth。 |
+| Authoritative guide | `repos/effect/ai-docs/src/` | 需要 examples 或 context 时读取。 |
+| Authoritative guide | `repos/effect/migration/v3-to-v4.md` | v3-to-v4 import/API migration 的 source of truth。 |
+| Reference only | `repos/effect/.patterns/effect.md` | 只在 narrow pitfalls 适用于 downstream app code 时参考。 |
+| Reference only | `repos/effect/.patterns/testing.md` | 解决 testing 冲突；target verifier 应体现相关规则。 |
+| Reference only | `repos/effect/packages/effect/MCP.md` | 只在维护 Effect worker、MCP route 或 tool server 时使用。 |
+| Reference only | `repos/effect/package.json` 和 `tsconfig*.json` | 理解官方 `tsgo` 和 validation setup，不复制 repo-maintenance scripts。 |
+| Maintainer-only | `repos/effect/AGENTS.md` | 官方 repo operating policy，不是 downstream coding guide。 |
+| Do not promote | `repos/effect/.agents/skills/*` | Effect maintainer skills，不默认安装或暴露给 target projects。 |
+| Do not promote | `repos/effect/.specs/*` | Effect maintainer feature specs，不是通用 harness guidance。 |
+| Do not promote | package-specific docgen 和 validation configs | 内部 publishing/docs machinery，不是 downstream defaults。 |
+
+不属于 authoritative guide 的文件，不应在没有 promotion decision 时复制、安装或暴露给
+target projects。
+
+## Upstream Surfaces
+
+| Surface | Role | Harness implication |
+| --- | --- | --- |
+| `repos/effect/LLMS.md` | 从 `ai-docs/src` 生成的 LLM coding guide，覆盖 services、errors、resources、runtime、testing、HTTP、CLI、AI、cluster 等。 | 第一 Effect coding reference；本地 docs 只 route，不替代。 |
+| `repos/effect/ai-docs/src/` | `LLMS.md` 的 source examples。 | 当 `LLMS.md` 太压缩时读取。 |
+| `repos/effect/migration/v3-to-v4.md` | migration-agent import/API rename map。 | 适配 v3 code 时优先使用。 |
+| `repos/effect/.patterns/effect.md` | narrow pitfalls：`Effect.gen`、terminal `return yield*`、`Context.Service` 等。 | reference only；只把 target-relevant pitfalls 转为 guardrails。 |
+| `repos/effect/.patterns/testing.md` | testing rules：`it.effect`、pure test、禁止 `Effect.runSync`、优先 `assert` from `@effect/vitest`、`TestClock`。 | reference only；verifier 跟随官方。 |
+| `repos/effect/packages/effect/MCP.md` | Effect-native MCP server guide。 | 只服务 MCP/worker route 维护。 |
+| `repos/effect/package.json` 和 `tsconfig*.json` | 官方 validation scripts 与 `@effect/language-service` / `tsgo` setup。 | 确认 `tsgo` diagnostic path；target 可以更严格。 |
+
+## Coverage
+
+对 application-style Effect code，upstream coverage 包含：
+
+- coding style：`Effect.gen`、`Effect.fn`、terminal `return yield*`、tagged errors
+- service style：`Context.Service`、`Layer.effect`、`Layer.unwrap`、`Layer.provideMerge`
+- runtime entrypoints：`NodeRuntime.runMain`、`Layer.launch`、`NodeServices.layer`
+- testing：`@effect/vitest`、`it.effect`、`TestClock`、shared layers
+- integration：`ManagedRuntime`、bridge code、child processes
+- operational concerns：schedules、retries、logging、tracing、Otlp modules
+- boundaries：HTTP client/server、CLI、streams、AI modules、cluster entities
+- migration：v3-to-v4 import 和 symbol maps
+
+修改 Effect repo 自身的 agent workflow 不属于默认 downstream harness surface：
+
+- `AGENTS.md` 里的 local workflow 和 validation matrix
+- package-specific validation commands
+- JSDoc skill 和 custom JSDoc linting
+- scratchpad extraction
+- `.specs/` 下的 complex feature specs
+
+## Promotion Boundary
+
+这份 inventory 只分类 official source surface。是否提升 practice feedback，按
+[exposure.md](./exposure.md) 和 [feedback/index.md](./feedback/index.md) 判断。
+
+## Harness Contract
+
+- coding agents 首先读取 `repos/effect/LLMS.md`。
+- 用 `repos/effect/ai-docs/src/` 和 `repos/effect/migration/v3-to-v4.md` 做 supporting official source。
+- 不默认暴露 `repos/effect/AGENTS.md`、`repos/effect/.agents/skills/`、`repos/effect/.specs/`。
+- 本仓库自身和外部 target 都可以产生 reusable practice evidence。
+- upstream docs 无法机械保护的 target constraints 进入 verifier 或 guardrail。
+- 面向用户的 examples 和业务项目形态不进入本仓库。
+- 本仓库只暴露 contracts，不做业务分发实现。

package/harness/runtime/codex/AGENTS.fragment.md

@@ -0,0 +1,28 @@
+# Effect Harness
+
+This repo uses `__EFFECT_HARNESS_ROOT__` as its Effect harness root.
+
+Before writing non-trivial Effect code, read:
+
+- `__EFFECT_HARNESS_ROOT__/repos/effect/LLMS.md`
+- `__EFFECT_HARNESS_ROOT__/harness/index.md`
+- `__EFFECT_HARNESS_ROOT__/repos/effect.subtree.json`
+- `.effect-harness.json`
+
+Runtime skills and agents installed by the harness:
+
+- Use `.codex/skills/effect-code/SKILL.md` for Effect implementation and review.
+- Use `.codex/skills/effect-feedback/SKILL.md` for reusable target feedback.
+- Use `.codex/agents/effect-worker.md` when delegating focused Effect subagent work.
+
+Use:
+
+```bash
+pnpm effect:status
+pnpm effect:verify
+pnpm verify
+```
+
+Do not import from `__EFFECT_HARNESS_ROOT__/repos/effect`.
+Do not copy effect-harness `.codex/skills`; this target only uses the runtime installed under
+`.codex/`.