@dalzoubi/dev-agents-sync 3.0.2 → 3.0.4

package/README.md

@@ -49,15 +49,17 @@ To adopt the toolkit with OpenAI Codex, pass the `codex` target explicitly:
 npx --yes @dalzoubi/dev-agents-sync@1 init --targets codex
 ```
 
-Codex is **opt-in only**. Unlike other targets there is no filesystem signal to detect (there is no `.codex/` directory), so `codex` is never auto-selected — you must pass `--targets codex` explicitly. You can combine it with other targets, e.g. `--targets claude,codex`.
+Codex is **opt-in only** so an existing `AGENTS.md` or `.codex/` configuration is never adopted accidentally. Pass `--targets codex` explicitly; you can combine it with other targets, e.g. `--targets claude,codex`.
 
-**Output shape.** `init --targets codex` writes one directory-per-skill file per agent at `.agents/skills/<agent>/SKILL.md` — covering the full `define`/`deliver` topology listed under [Agents](#agents) — plus a thin root `AGENTS.md` index. Codex discovers these by scanning from the working directory up to the repo root, so each agent lives at its own `.agents/skills/<agent>/SKILL.md` path. Every file carries the managed-by marker, and `update` and `check` scope to these paths exactly like the other targets.
+**Output shape.** `init --targets codex` writes one directory-per-skill file per agent at `.agents/skills/<agent>/SKILL.md`, a native custom-agent definition at `.codex/agents/<agent>.toml`, the shared lifecycle scripts under `.codex/hooks/`, their adapter and `.codex/hooks.json`, plus a thin root `AGENTS.md` index. Every file carries the managed-by marker, and `update`, `status`, and `check` scope to these paths exactly like the other targets.
 
 **Standalone.** Codex is a first-class standalone target. Each emitted `SKILL.md` bundles the workflow support docs it references, so a Codex-only install does **not** need `.claude/skills/*.md`, `.cursor/`, or any other target files to run the agent workflows.
 
-**Model-invoked, not slash commands.** Codex Agent Skills are model-invoked: a Codex user triggers an agent through `/skills`, a `$<name>` mention, or implicit selection by the model — *not* by typing a literal `/define`-style slash command the way Claude commands work. This is an accepted approximation of the slash-command UX the other targets provide; the agent content is the same, only the invocation differs.
+**Invocation and delegation.** Codex Agent Skills are model-invoked through `/skills`, a `$<name>` mention, or implicit selection. The matching `.codex/agents/*.toml` definitions also make the topology available to Codex's native subagent delegation.
 
-**Manual removal.** Like every target, there is no uninstall or cleanup command. Dropping `codex` from the `targets` in `.dev-agents-sync.json` stops future writes, but the already-written `.agents/skills/<agent>/SKILL.md` directories and the root `AGENTS.md` are removed manually.
+**Hooks.** The Codex target registers the same nine lifecycle policies as the Claude target in project-local `.codex/hooks.json`; Claude wiring remains in `.claude/settings.json`. Codex asks the user to trust project hooks the first time it loads them; review with `/hooks` and choose the appropriate trust option. The adapter translates Codex `apply_patch` events into the shared Edit/Write contract, so the same blocking and warning scripts remain the source of truth.
+
+**Manual removal.** Like every target, there is no uninstall or cleanup command. Dropping `codex` from the `targets` in `.dev-agents-sync.json` stops future writes, but the already-written `.agents/skills/<agent>/SKILL.md`, `.codex/`, and root `AGENTS.md` files are removed manually.
 
 > **Maintainer note — two file shapes.** Do not confuse the Codex output with this toolkit's own authoring sources. In the `dalzoubi/dev-agents` repo, the canonical skill sources are **flat single files** at `.agents/skills/*.md`. The Codex target **output** is the **directory-per-skill** form `.agents/skills/<agent>/SKILL.md`. Both share the `.agents/skills/` prefix, but the flat `.md` files are for authoring and the `SKILL.md` directories are the generated codex output shape.
 
@@ -101,7 +103,7 @@ npx --yes @dalzoubi/dev-agents-sync@1 status
 
 ## Steering and hooks
 
-For the `claude` target, `init` and `update` set up two extra pieces of project memory and automation: a consumer-owned steering scaffold, and managed hook scripts that are auto-wired into `.claude/settings.json`.
+For the `claude` target, `init` and `update` seed consumer-owned steering and auto-wire hooks into `.claude/settings.json`. The `codex` target ships the same hook policies through project-local `.codex/hooks.json`; steering remains consumer-owned and the workflow scratch path is `.agents/state/` for either runtime.
 
 ### Steering scaffold (consumer-owned)
 
@@ -111,7 +113,7 @@ The CLI seeds a blank steering scaffold under `.claude/steering/` — `decisions
 
 ### Hook scripts (managed)
 
-`init` and `update` install the toolkit's hook scripts into `.claude/hooks/` as marker-managed, lockfile-tracked, executable files. Most are **warning** hooks: they print one line to stderr and always exit 0. Three are **blocking** hooks that can deny a tool call outright.
+`init` and `update` install the toolkit's hook scripts as marker-managed, lockfile-tracked executable files: `.claude/hooks/` for Claude and `.codex/hooks/` for Codex. Most are **warning** hooks: they print one line to stderr and always exit 0. Four are **blocking** hooks that can deny a tool call outright. Claude registrations are merged into `.claude/settings.json`; Codex registrations ship as managed `.codex/hooks.json` plus `.codex/hook-adapter.mjs`.
 
 | Script | Event | Matcher | Mode | What it does |
 |---|---|---|---|---|
@@ -119,6 +121,7 @@ The CLI seeds a blank steering scaffold under `.claude/steering/` — `decisions
 | `managed-file-guard.sh` | `PostToolUse` | `Edit\|Write` | warning | Guards managed files against unexpected edits. |
 | `uncommitted-check.sh` | `Stop` | `.*` | warning | Flags uncommitted work when a session ends. |
 | `force-push-guard.sh` | `PreToolUse` | `Bash` | **blocking** | Denies `git push` carrying `--force` / `-f` / `--force-with-lease` at `main` or `master` (by explicit refspec, or by the checked-out branch when the push names no ref). Force-pushing a feature branch, and a plain push to `main`, both pass. |
+| `direct-push-guard.sh` | `PreToolUse` | `Bash` | **blocking** | Denies ANY `git push` — force or not — at `main`, `master`, or `develop` (by explicit refspec, or by the checked-out branch when the push names no ref). Pushing a feature branch passes; open a pull request instead. |
 | `spec-approval-gate.sh` | `PreToolUse` | `Edit\|Write` | **blocking** | Denies an edit that sets a spec to `Status: Approved` while an unresolved clarification marker — a bare bracketed `NEEDS CLARIFICATION` token — remains in prose. Occurrences inside code spans or fenced blocks are documentation and never match. |
 | `handoff-state-guard.sh` | `PreToolUse` | `Write` | **blocking** | Denies a write to `.claude/state/*.json` whose `handoff.status`, `from_agent`, or `to_agent` is outside the vocabulary `.claude/rules/handoff.md` defines. |
 | `spec-drift-warn.sh` | `PostToolUse` | `Edit\|Write` | warning | After an edit to `spec.md` / `design.md` / `tasks.md` under `docs/specs/`, warns when that folder's `spec.md` has already moved past `Draft`. Draft folders stay silent. |
@@ -135,6 +138,7 @@ A blocking hook runs on `PreToolUse`, where exiting 2 denies the tool call and t
 | Code | Raised by | Example message |
 |---|---|---|
 | `EHOOK_FORCE_PUSH` | `force-push-guard.sh` | `blocked: EHOOK_FORCE_PUSH — force-push to protected branch 'main' — push without a force flag or open a pull request; to override, set DEV_AGENTS_HOOKS_BYPASS=force-push-guard` |
+| `EHOOK_DIRECT_PUSH` | `direct-push-guard.sh` | `blocked: EHOOK_DIRECT_PUSH — direct push to protected branch 'main' — open a pull request instead; to override, set DEV_AGENTS_HOOKS_BYPASS=direct-push-guard` |
 | `EHOOK_SPEC_APPROVAL` | `spec-approval-gate.sh` | `blocked: EHOOK_SPEC_APPROVAL — <path> sets Status: Approved while an unresolved clarification marker (a bare bracketed NEEDS CLARIFICATION token) remains in prose — resolve it via /define-analyze or /define before approving; to override, set DEV_AGENTS_HOOKS_BYPASS=spec-approval-gate` |
 | `EHOOK_HANDOFF_STATE` | `handoff-state-guard.sh` | `blocked: EHOOK_HANDOFF_STATE — handoff.status "done" is outside the status enum — fix the value in the state file before writing, or re-run with DEV_AGENTS_HOOKS_BYPASS=handoff-state-guard` |
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dalzoubi/dev-agents-sync",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "type": "module",
-  "description": "CLI that syncs managed dev-agent prompts into consumer repos (.claude/ and/or .cursor/).",
+  "description": "CLI that syncs managed dev-agent workflows into Claude Code, Cursor, Copilot, and Codex projects.",
   "license": "UNLICENSED",
   "bin": {
     "dev-agents-sync": "src/cli.mjs"

package/src/commands/status.mjs

@@ -13,11 +13,7 @@ const TARGET_DIRS = {
   cursor: ['.cursor', 'rules'],
 };
 
-function countTargetFiles(consumerCwd, target) {
-  const segs = TARGET_DIRS[target];
-  if (!segs) return 0;
-  // Count files recursively under <target-root>/
-  const root = path.join(consumerCwd, segs[0]);
+function countFiles(root) {
   if (!existsSync(root)) return 0;
   let n = 0;
   const stack = [root];
@@ -38,6 +34,19 @@ function countTargetFiles(consumerCwd, target) {
   return n;
 }
 
+function countTargetFiles(consumerCwd, target) {
+  if (target === 'codex') {
+    return (existsSync(path.join(consumerCwd, 'AGENTS.md')) ? 1 : 0) +
+      countFiles(path.join(consumerCwd, '.agents', 'skills')) +
+      countFiles(path.join(consumerCwd, '.codex'));
+  }
+  const segs = TARGET_DIRS[target];
+  if (!segs) return 0;
+  // Count files recursively under <target-root>/
+  const root = path.join(consumerCwd, segs[0]);
+  return countFiles(root);
+}
+
 export async function runStatus(consumerCwd, opts = {}) {
   const { availableTags } = opts;
 

package/src/hook-manifest.mjs

@@ -0,0 +1,24 @@
+/**
+ * Target-neutral lifecycle-hook manifest.
+ *
+ * The content build and the sync CLI both import this module so Claude settings
+ * wiring and generated Codex hooks.json cannot silently drift apart.
+ */
+export const HOOK_MANIFEST = Object.freeze([
+  { event: 'SessionStart', matcher: '.*', file: 'steering-injector.sh' },
+  { event: 'PostToolUse', matcher: 'Edit|Write', file: 'managed-file-guard.sh' },
+  { event: 'Stop', matcher: '.*', file: 'uncommitted-check.sh' },
+  { event: 'PreToolUse', matcher: 'Bash', file: 'force-push-guard.sh' },
+  { event: 'PreToolUse', matcher: 'Bash', file: 'direct-push-guard.sh' },
+  { event: 'PreToolUse', matcher: 'Edit|Write', file: 'spec-approval-gate.sh' },
+  { event: 'PreToolUse', matcher: 'Write', file: 'handoff-state-guard.sh' },
+  { event: 'PostToolUse', matcher: 'Edit|Write', file: 'spec-drift-warn.sh' },
+  { event: 'PreToolUse', matcher: 'Bash', file: 'pre-pr-preflight.sh' },
+  { event: 'Stop', matcher: '.*', file: 'ui-verification-reminder.sh' },
+]);
+
+export function hookPathFor(target, file) {
+  if (target === 'claude') return `.claude/hooks/${file}`;
+  if (target === 'codex') return `.codex/hooks/${file}`;
+  throw new Error(`unsupported hook target: ${target}`);
+}

package/src/marker.mjs

@@ -9,6 +9,7 @@
  */
 
 const MARKER_RE = /^<!--\s*managed-by:\s*dev-agents-sync\s+v([0-9]+\.[0-9]+\.[0-9]+(?:[-+][\w.-]+)?)\s*-->\s*$/;
+const COMMENT_MARKER_RE = /^(?:#|\/\/)\s*managed-by:\s*dev-agents-sync\s+v([0-9]+\.[0-9]+\.[0-9]+(?:[-+][\w.-]+)?)\s*$/;
 
 export function buildMarker(version) {
   return `<!-- managed-by: dev-agents-sync v${version} -->`;
@@ -48,7 +49,22 @@ export function hasMarker(content) {
   const body = stripFrontmatter(content);
   const first = firstNonEmptyLine(body);
   if (first === null) return false;
-  return MARKER_RE.test(first);
+  if (MARKER_RE.test(first) || COMMENT_MARKER_RE.test(first)) return true;
+
+  // Executable scripts preserve their shebang on line 1 and carry the marker
+  // immediately after it. JSON cannot contain comments, so generated Codex
+  // hooks.json stores the unchanged HTML marker string in `_managedBy`.
+  const lines = body.split(/\r?\n/);
+  if (lines[0]?.startsWith('#!')) {
+    const second = firstNonEmptyLine(lines.slice(1).join('\n'));
+    return second !== null && COMMENT_MARKER_RE.test(second);
+  }
+  try {
+    const parsed = JSON.parse(body);
+    return typeof parsed?._managedBy === 'string' && MARKER_RE.test(parsed._managedBy);
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -66,6 +82,17 @@ export function extractMarkerVersion(content) {
   const body = stripFrontmatter(content);
   const first = firstNonEmptyLine(body);
   if (first === null) return null;
-  const m = first.match(MARKER_RE);
+  let m = first.match(MARKER_RE) ?? first.match(COMMENT_MARKER_RE);
+  if (!m && first.startsWith('#!')) {
+    const second = firstNonEmptyLine(body.split(/\r?\n/).slice(1).join('\n'));
+    m = second?.match(COMMENT_MARKER_RE) ?? null;
+  }
+  if (!m) {
+    try {
+      m = JSON.parse(body)?._managedBy?.match(MARKER_RE) ?? null;
+    } catch {
+      m = null;
+    }
+  }
   return m ? m[1] : null;
 }

package/src/settings.mjs

@@ -25,6 +25,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { HOOK_MANIFEST, hookPathFor } from './hook-manifest.mjs';
 
 /**
  * Property injected onto every CLI-managed hook entry so it can be identified
@@ -436,26 +437,10 @@ export function hookCommandFor(script) {
  * `Bash` matcher — one blocking, one warning — which the merge handles as two
  * independent registrations keyed by command.
  */
-export const DEFAULT_HOOK_SCRIPTS = [
-  { event: 'SessionStart', matcher: '.*', script: '.claude/hooks/steering-injector.sh' },
-  // Edit|Write, not `.*`: this hook reads a written file path out of the hook
-  // payload and exits 0 silently when there is none, so on `.*` it was spawned
-  // by every tool call — every Read, every Bash — to do nothing.
-  { event: 'PostToolUse', matcher: 'Edit|Write', script: '.claude/hooks/managed-file-guard.sh' },
-  { event: 'Stop', matcher: '.*', script: '.claude/hooks/uncommitted-check.sh' },
-  // Added by docs/specs/260805-hooks-wave-2/ — the toolkit's first blocking
-  // hooks plus two warning hooks. Blockers deny only on a positive violation
-  // match, fail open otherwise, and honor DEV_AGENTS_HOOKS_BYPASS.
-  { event: 'PreToolUse', matcher: 'Bash', script: '.claude/hooks/force-push-guard.sh' },
-  { event: 'PreToolUse', matcher: 'Edit|Write', script: '.claude/hooks/spec-approval-gate.sh' },
-  { event: 'PreToolUse', matcher: 'Write', script: '.claude/hooks/handoff-state-guard.sh' },
-  { event: 'PostToolUse', matcher: 'Edit|Write', script: '.claude/hooks/spec-drift-warn.sh' },
-  { event: 'PreToolUse', matcher: 'Bash', script: '.claude/hooks/pre-pr-preflight.sh' },
-  // UI/UX framework: a Stop-time reminder that frontend work is governed by the
-  // UI Definition of Done, not by a green build. Non-blocking by construction —
-  // a Stop hook cannot deny, and this one exits 0 on every path.
-  { event: 'Stop', matcher: '.*', script: '.claude/hooks/ui-verification-reminder.sh' },
-].map((h) => ({ ...h, command: hookCommandFor(h.script) }));
+export const DEFAULT_HOOK_SCRIPTS = HOOK_MANIFEST.map(({ event, matcher, file }) => {
+  const script = hookPathFor('claude', file);
+  return { event, matcher, script, command: hookCommandFor(script) };
+});
 
 /**
  * Hook registrations the toolkit once shipped and has since retired.
@@ -511,4 +496,9 @@ export const RETIRED_HOOK_SCRIPTS = [
   // or by a future regression, and pruning it is always correct since that form
   // is never in DEFAULT_HOOK_SCRIPTS.
   { event: 'Stop', matcher: '.*', command: '.claude/hooks/ui-verification-reminder.sh' },
+  // direct-push-guard.sh ships only in the `bash …` form — same reasoning as
+  // ui-verification-reminder.sh above: it never shipped bare, but the
+  // bare-path form is pruned defensively so a hand-edit or regression can't
+  // register it live alongside the real one.
+  { event: 'PreToolUse', matcher: 'Bash', command: '.claude/hooks/direct-push-guard.sh' },
 ];

package/tests/e2e/steering-hooks-flow.test.mjs

@@ -324,10 +324,12 @@ describe('S5 E1 — integrated init → update → check flow', () => {
       assert.ok(existsSync(absPath), `update must install .claude/hooks/${file}`);
 
       const st = statSync(absPath);
-      assert.ok(
-        (st.mode & 0o111) !== 0,
-        `${file} must be executable after install (mode: 0o${st.mode.toString(8)})`,
-      );
+      if (process.platform !== 'win32') {
+        assert.ok(
+          (st.mode & 0o111) !== 0,
+          `${file} must be executable after install (mode: 0o${st.mode.toString(8)})`,
+        );
+      }
     }
 
     // Lockfile must reference each installed hook script.

package/tests/hooks-cli-install.test.mjs

@@ -323,10 +323,12 @@ describe('S4 H1 — init installs hook scripts', () => {
       const absPath = path.join(hooksDir, file);
       const st = statSync(absPath);
       // On POSIX: mode & 0o111 checks owner+group+other execute bits.
-      assert.ok(
-        (st.mode & 0o111) !== 0,
-        `${file} must be executable after install (mode: 0o${st.mode.toString(8)})`,
-      );
+      if (process.platform !== 'win32') {
+        assert.ok(
+          (st.mode & 0o111) !== 0,
+          `${file} must be executable after install (mode: 0o${st.mode.toString(8)})`,
+        );
+      }
     }
   });
 
@@ -412,10 +414,12 @@ describe('S4 H1 — update installs hook scripts', () => {
     const hooksDir = path.join(consumerDir, '.claude', 'hooks');
     for (const file of HOOK_FILES) {
       const st = statSync(path.join(hooksDir, file));
-      assert.ok(
-        (st.mode & 0o111) !== 0,
-        `update-installed ${file} must be executable`,
-      );
+      if (process.platform !== 'win32') {
+        assert.ok(
+          (st.mode & 0o111) !== 0,
+          `update-installed ${file} must be executable`,
+        );
+      }
     }
   });
 });

package/tests/hooks-wave2-registration.test.mjs

@@ -295,10 +295,10 @@ describe('W2 — init and update install and wire every registered hook', () =>
     }
   });
 
-  it('W2d: the two Bash PreToolUse hooks are both wired (a shared event+matcher is not deduped)', async () => {
-    // force-push-guard and pre-pr-preflight share PreToolUse/Bash. Merge
-    // identity is the COMMAND, so both must survive — collapsing on
-    // event+matcher would silently drop one.
+  it('W2d: all three Bash PreToolUse hooks are wired (a shared event+matcher is not deduped)', async () => {
+    // force-push-guard, direct-push-guard, and pre-pr-preflight all share
+    // PreToolUse/Bash. Merge identity is the COMMAND, so all three must
+    // survive — collapsing on event+matcher would silently drop one.
     await runInit(consumerDir, {
       targets: ['claude'],
       fetcher: makeFixtureFetcher(),
@@ -312,10 +312,11 @@ describe('W2 — init and update install and wire every registered hook', () =>
     assert.deepEqual(
       commands,
       [
+        expectedCommand('.claude/hooks/direct-push-guard.sh'),
         expectedCommand('.claude/hooks/force-push-guard.sh'),
         expectedCommand('.claude/hooks/pre-pr-preflight.sh'),
       ],
-      'both PreToolUse/Bash hooks must be wired independently',
+      'all three PreToolUse/Bash hooks must be wired independently',
     );
   });
 

package/tests/marker.test.mjs

@@ -187,4 +187,22 @@ describe('extractMarkerVersion', () => {
     const content = '# No marker here\nBody.';
     assert.equal(extractMarkerVersion(content), null);
   });
+
+  it('extracts versions from TOML, shebang scripts, and JSON manifests', () => {
+    assert.equal(extractMarkerVersion('# managed-by: dev-agents-sync v1.2.3\nname = "x"'), '1.2.3');
+    assert.equal(extractMarkerVersion('#!/usr/bin/env node\n// managed-by: dev-agents-sync v2.3.4\n'), '2.3.4');
+    assert.equal(extractMarkerVersion(JSON.stringify({ _managedBy: '<!-- managed-by: dev-agents-sync v3.4.5 -->' })), '3.4.5');
+  });
+});
+
+describe('hasMarker — Codex native file formats', () => {
+  it('accepts TOML comments, shebang-plus-comment scripts, and JSON manifests', () => {
+    assert.ok(hasMarker('# managed-by: dev-agents-sync v1.2.3\nname = "x"'));
+    assert.ok(hasMarker('#!/usr/bin/env node\n// managed-by: dev-agents-sync v1.2.3\n'));
+    assert.ok(hasMarker(JSON.stringify({ _managedBy: '<!-- managed-by: dev-agents-sync v1.2.3 -->' })));
+  });
+
+  it('rejects a comment marker buried after ordinary content', () => {
+    assert.equal(hasMarker('name = "x"\n# managed-by: dev-agents-sync v1.2.3'), false);
+  });
 });

package/tests/status-check-diff.test.mjs

@@ -205,6 +205,21 @@ describe('status', () => {
       'result must include file counts',
     );
   });
+
+  it('counts Codex root, skill, hook, and custom-agent files', async () => {
+    setupConsumerRepo(consumerDir, { targets: ['codex'], writeFiles: false });
+    mkdirSync(path.join(consumerDir, '.agents', 'skills', 'define'), { recursive: true });
+    mkdirSync(path.join(consumerDir, '.codex', 'agents'), { recursive: true });
+    mkdirSync(path.join(consumerDir, '.codex', 'hooks'), { recursive: true });
+    writeFileSync(path.join(consumerDir, 'AGENTS.md'), 'index');
+    writeFileSync(path.join(consumerDir, '.agents', 'skills', 'define', 'SKILL.md'), 'skill');
+    writeFileSync(path.join(consumerDir, '.codex', 'agents', 'define.toml'), 'agent');
+    writeFileSync(path.join(consumerDir, '.codex', 'hooks.json'), '{}');
+    writeFileSync(path.join(consumerDir, '.codex', 'hooks', 'guard.sh'), 'exit 0');
+
+    const result = await runStatus(consumerDir, { availableTags: ['v1.2.0'] });
+    assert.equal(result.fileCounts.codex, 5);
+  });
 });
 
 // ---------------------------------------------------------------------------