@aacombarro89/praxis 0.1.7 → 0.1.9

package/dist/sync.js

@@ -1,7 +1,10 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { applyOp, planEmit } from "./emit.js";
+import { applyOp, BLOCK_FILE, planEmit } from "./emit.js";
 import { loadManifest } from "./manifest.js";
+import { blockStatus, findBlocks } from "./merge.js";
+import { reconcileCodexConfig } from "./codex-security.js";
+import { CODEX_MARKETPLACE_PATH, CODEX_MARKETPLACE_STATE_PATH, reconcileCodexMarketplace, } from "./codex-marketplace.js";
 export function runSync(opts) {
     const manifestPath = opts.manifestPath ?? join(opts.cwd, "praxis.yaml");
     return applyManifest(loadManifest(manifestPath), opts.cwd, opts.write);
@@ -14,19 +17,151 @@ export function runSync(opts) {
 export function applyManifest(manifest, cwd, write) {
     const ops = planEmit(manifest);
     const files = [];
+    const handledPaths = new Set();
     for (const op of ops) {
+        handledPaths.add(op.path);
+        if (op.kind === "codex-marketplace") {
+            handledPaths.add(op.statePath);
+            const marketplaceAbs = join(cwd, op.path);
+            const stateAbs = join(cwd, op.statePath);
+            const marketplaceExisting = readFileIfExists(marketplaceAbs) ?? "";
+            const stateExisting = readFileIfExists(stateAbs) ?? "";
+            const result = reconcileCodexMarketplace(marketplaceExisting, stateExisting, op.plugins);
+            for (const output of [
+                { path: op.path, abs: marketplaceAbs, existing: marketplaceExisting, text: result.marketplaceText, changed: result.marketplaceChanged, conflicts: result.conflicts },
+                { path: op.statePath, abs: stateAbs, existing: stateExisting, text: result.stateText, changed: result.stateChanged, conflicts: [] },
+            ]) {
+                const existed = existsSync(output.abs);
+                const status = !existed ? "created" : output.changed ? "updated" : "unchanged";
+                const written = write && output.changed;
+                if (written) {
+                    mkdirSync(dirname(output.abs), { recursive: true });
+                    writeFileSync(output.abs, output.text, "utf8");
+                }
+                files.push({ path: output.path, status, conflicts: output.conflicts, written });
+            }
+            continue;
+        }
         const abs = join(cwd, op.path);
         const existing = readFileIfExists(abs);
         const result = applyOp(op, existing ?? "");
-        const status = existing === undefined ? "created" : result.changed ? "updated" : "unchanged";
-        // Write safe changes only: never in check mode, never a pure no-op. result.text
+        let text = result.text;
+        let changed = result.changed;
+        let conflicts = result.conflicts;
+        // Prune orphan blocks in the same pass: a block-target file (e.g. AGENTS.md)
+        // may still carry a managed block for a package the manifest no longer
+        // selects. Splice those out of the already-reconciled text so the file
+        // report and the single write below cover both concerns together.
+        if (op.kind === "block") {
+            const pruned = pruneOrphanBlocks(text, new Set(Object.keys(op.blocks)));
+            text = pruned.text;
+            changed = changed || pruned.changed;
+            conflicts = [...conflicts, ...pruned.conflicts];
+        }
+        const status = existing === undefined ? "created" : changed ? "updated" : "unchanged";
+        // Write safe changes only: never in check mode, never a pure no-op. `text`
         // already preserves any conflicted block, so writing it honors D10.
-        const written = write && (status === "created" || (status === "updated" && result.changed));
+        const written = write && (status === "created" || status === "updated");
         if (written) {
             mkdirSync(dirname(abs), { recursive: true });
-            writeFileSync(abs, result.text, "utf8");
+            writeFileSync(abs, text, "utf8");
         }
-        files.push({ path: op.path, status, conflicts: result.conflicts, written });
+        files.push({ path: op.path, status, conflicts, written });
+    }
+    // Block orphans in a file the manifest no longer emits ANY block for (e.g. the
+    // last rules package for a target was removed): no "block" op exists this run
+    // to carry the pruning above, so sweep the known block-owned files directly.
+    for (const path of new Set(Object.values(BLOCK_FILE))) {
+        if (handledPaths.has(path))
+            continue;
+        const abs = join(cwd, path);
+        const existing = readFileIfExists(abs);
+        if (existing === undefined)
+            continue;
+        const pruned = pruneOrphanBlocks(existing, new Set());
+        if (!pruned.changed && pruned.conflicts.length === 0)
+            continue;
+        const written = write && pruned.changed;
+        if (written)
+            writeFileSync(abs, pruned.text, "utf8");
+        files.push({
+            path,
+            status: pruned.changed ? "updated" : "unchanged",
+            conflicts: pruned.conflicts,
+            written,
+        });
+    }
+    // A removed Codex permissions package/target removes only Praxis's protected
+    // TOML block; unrelated project configuration remains byte-for-byte intact.
+    const codexConfigPath = ".codex/config.toml";
+    if (!handledPaths.has(codexConfigPath)) {
+        const abs = join(cwd, codexConfigPath);
+        const existing = readFileIfExists(abs);
+        if (existing !== undefined) {
+            const result = reconcileCodexConfig(existing, false);
+            if (result.changed || result.conflicts.length > 0) {
+                const written = write && result.changed;
+                if (written)
+                    writeFileSync(abs, result.text, "utf8");
+                files.push({
+                    path: codexConfigPath,
+                    status: result.changed ? "updated" : "unchanged",
+                    conflicts: result.conflicts,
+                    written,
+                });
+            }
+        }
+    }
+    // Marketplace ownership lives in a committed sidecar. Without that state,
+    // removal is deliberately conservative: Praxis cannot prove an entry is its own.
+    if (!handledPaths.has(CODEX_MARKETPLACE_PATH)) {
+        const marketplaceAbs = join(cwd, CODEX_MARKETPLACE_PATH);
+        const stateAbs = join(cwd, CODEX_MARKETPLACE_STATE_PATH);
+        const marketplaceExisting = readFileIfExists(marketplaceAbs);
+        const stateExisting = readFileIfExists(stateAbs);
+        if (marketplaceExisting !== undefined && stateExisting !== undefined) {
+            const result = reconcileCodexMarketplace(marketplaceExisting, stateExisting, []);
+            for (const output of [
+                { path: CODEX_MARKETPLACE_PATH, abs: marketplaceAbs, text: result.marketplaceText, changed: result.marketplaceChanged, conflicts: result.conflicts },
+                { path: CODEX_MARKETPLACE_STATE_PATH, abs: stateAbs, text: result.stateText, changed: result.stateChanged, conflicts: [] },
+            ]) {
+                if (!output.changed && output.conflicts.length === 0)
+                    continue;
+                const written = write && output.changed;
+                if (written)
+                    writeFileSync(output.abs, output.text, "utf8");
+                files.push({
+                    path: output.path,
+                    status: output.changed ? "updated" : "unchanged",
+                    conflicts: output.conflicts,
+                    written,
+                });
+            }
+        }
+        else if (stateExisting !== undefined) {
+            // marketplace.json is gone (hand-deleted or never re-created) but the
+            // Praxis-owned sidecar remains — it now describes nothing and would
+            // otherwise orphan forever. Prune it (D46: manifest expresses absence).
+            if (write)
+                unlinkSync(stateAbs);
+            files.push({ path: CODEX_MARKETPLACE_STATE_PATH, status: "deleted", conflicts: [], written: write });
+        }
+    }
+    // Owned-file orphans: `.claude/rules/praxis-*.md` / `.claude/commands/praxis-*.md`
+    // on disk that the current manifest no longer implies (the package that used to
+    // own them was removed, or its target was). The `praxis-` prefix is the
+    // ownership convention; a user's own file with that prefix would be flagged too
+    // — acceptable because deletion is always previewed here, never silent.
+    const impliedOwnedPaths = new Set(ops.filter((op) => op.kind === "owned").map((op) => op.path));
+    for (const path of findOwnedOrphans(cwd, impliedOwnedPaths)) {
+        if (write) {
+            const abs = join(cwd, path);
+            unlinkSync(abs);
+            const parent = dirname(abs);
+            if (path.startsWith(".agents/skills/") && readdirSync(parent).length === 0)
+                rmdirSync(parent);
+        }
+        files.push({ path, status: "deleted", conflicts: [], written: write });
     }
     return {
         files,
@@ -42,4 +177,72 @@ function readFileIfExists(path) {
         return undefined;
     }
 }
+// Directories whose contents are Praxis-owned by naming convention alone — see
+// `planEmit` in src/emit.ts; files in these directories are owned by prefix.
+const OWNED_ORPHAN_DIRS = [".claude/rules", ".claude/commands", ".codex/rules"];
+/** Praxis-owned files on disk (by the `praxis-` prefix convention) whose path is
+ *  not in `impliedPaths` — the current manifest no longer emits them. */
+function findOwnedOrphans(cwd, impliedPaths) {
+    const orphans = [];
+    for (const dir of OWNED_ORPHAN_DIRS) {
+        const abs = join(cwd, dir);
+        if (!existsSync(abs))
+            continue;
+        for (const entry of readdirSync(abs, { withFileTypes: true })) {
+            const suffix = dir === ".codex/rules" ? ".rules" : ".md";
+            if (!entry.isFile() || !entry.name.startsWith("praxis-") || !entry.name.endsWith(suffix))
+                continue;
+            const path = `${dir}/${entry.name}`;
+            if (!impliedPaths.has(path))
+                orphans.push(path);
+        }
+    }
+    const skillsDir = join(cwd, ".agents/skills");
+    if (existsSync(skillsDir)) {
+        for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory() || !entry.name.startsWith("praxis-"))
+                continue;
+            const path = `.agents/skills/${entry.name}/SKILL.md`;
+            if (existsSync(join(cwd, path)) && !impliedPaths.has(path))
+                orphans.push(path);
+        }
+    }
+    return orphans;
+}
+/** Remove one managed block (both markers + content) from `text`, absorbing the
+ *  blank-line separator and trailing newline that `appendBlock` (src/merge.ts)
+ *  introduces when a block is first added — so removing an orphan restores the
+ *  surrounding prose to exactly what it was before the block ever existed. */
+function spliceOutBlock(text, block) {
+    let start = block.start;
+    let end = block.end;
+    if (text.slice(end, end + 1) === "\n")
+        end += 1;
+    if (text.slice(Math.max(0, start - 2), start) === "\n\n")
+        start -= 1;
+    return text.slice(0, start) + text.slice(end);
+}
+/** Splice every managed block out of `text` whose id is not in `keepIds` — the
+ *  block-file analogue of `findOwnedOrphans`. Mirrors `reconcile`'s conflict rule
+ *  (D10): a block whose content hash no longer matches its recorded marker was
+ *  user-edited, so it is reported as a conflict and left untouched, never deleted. */
+function pruneOrphanBlocks(text, keepIds) {
+    let out = text;
+    let changed = false;
+    const conflicts = [];
+    const skip = new Set();
+    for (;;) {
+        const orphan = findBlocks(out).find((b) => !keepIds.has(b.id) && !skip.has(b.id));
+        if (!orphan)
+            break;
+        if (blockStatus(orphan) === "user-edited") {
+            conflicts.push(orphan.id);
+            skip.add(orphan.id);
+            continue;
+        }
+        out = spliceOutBlock(out, orphan);
+        changed = true;
+    }
+    return { text: out, changed, conflicts };
+}
 //# sourceMappingURL=sync.js.map

package/dist/sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAiB,MAAM,eAAe,CAAC;AAoC5D,MAAM,UAAU,OAAO,CAAC,IAAiB;IACvC,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;IACxE,OAAO,aAAa,CAAC,YAAY,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,QAAkB,EAAE,GAAW,EAAE,KAAc;IAC3E,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAE/B,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC;QAE3C,MAAM,MAAM,GACV,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC;QAEhF,gFAAgF;QAChF,oEAAoE;QACpE,MAAM,OAAO,GACX,KAAK,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9E,IAAI,OAAO,EAAE,CAAC;YACZ,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7C,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO;QACL,KAAK;QACL,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC;QACpD,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;KACxD,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aacombarro89/praxis",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "A CLI that installs an AI methodology layer into a codebase.",
   "type": "module",
   "bin": {

package/packages/external/ponytail/plugins.yaml

@@ -2,7 +2,7 @@
 # Praxis never executes anything here — this is committable config that Claude
 # Code itself reads on folder-trust to offer installing/enabling the plugin.
 # Verified against github.com/DietrichGebert/ponytail (tag v4.7.0 exists).
-targets: [claude-code]
+targets: [claude-code, codex]
 marketplace:
   name: ponytail
   source:
@@ -11,3 +11,6 @@ marketplace:
     ref: v4.7.0
 enable:
   - ponytail@ponytail
+codex:
+  name: ponytail
+  category: Developer Tools

package/packages/layer1/instruction-upkeep/commands/instructions.md

@@ -1,14 +1,16 @@
 ---
-description: Keep the authored instruction files (CLAUDE.md, .claude/rules) current with the project's state and complete against the standard rubric.
+description: Keep the project's authored agent instruction files current with its state and complete against the standard rubric.
 ---
 
-Scope: $ARGUMENTS
+Scope: {{arguments}}
 
-This updates the **authored instruction layer** — `CLAUDE.md` and
-`.claude/rules` — not the tool's native auto-memory and not any 3rd-party
+This updates the **authored agent instruction layer** — project-owned prose in
+the selected tool's instruction surfaces — not native auto-memory and not any 3rd-party
 agent-memory system. Those are out of scope.
 
-1. Read `CLAUDE.md` and every file under `.claude/rules`. Identify any
+1. Read `praxis.yaml`, then read every project instruction surface selected by
+   its first-class targets (`CLAUDE.md` for Claude Code, `AGENTS.md` for Codex).
+   Identify any
    canonical doc they point to (architecture doc, decision log, design doc).
 2. Compare what the instruction files claim against that canonical doc and
    against recent git history (`git log`, changed files) and the current
@@ -21,6 +23,11 @@ agent-memory system. Those are out of scope.
    - always-do rules (the few non-negotiable habits)
 
    Flag any rubric section that's entirely absent, citing where it should go.
+   When Claude Code and Codex are both selected, inspect the project-owned
+   `praxis:shared-project` block in both native files. Their contents must match
+   exactly (apart from line endings), while prose outside the blocks may differ.
+   Treat a missing, duplicate, or mismatched block reported by `praxis check` as
+   authored instruction drift — never choose one file as the automatic winner.
 3. **Ask the user before editing anything.** Present the list from step 2 and
    confirm which items to fix.
 4. For approved items, update only project-owned sections of the instruction
@@ -28,6 +35,8 @@ agent-memory system. Those are out of scope.
    code, or the user's answer. Where an instruction file currently restates a
    fact that lives in a canonical doc, prefer replacing the restatement with a
    link to that doc (reference, don't duplicate) so it can't drift again.
+   In a dual-target repo, apply approved shared-fact changes to both shared blocks
+   together and preserve all target-specific content outside them.
 5. If an instruction file carries `praxisAnchors` frontmatter, revalidate and
    update the anchors for any changed source reference. Phase-2 anchors are
    deterministic only:

package/packages/layer1/instruction-upkeep/rules.md

@@ -1,26 +1,14 @@
 ## Instruction upkeep
 
-The authored instruction layer (`CLAUDE.md`, `.claude/rules`) drifts as a
-project changes, and can be incomplete from the start. Keep it both current
-and complete:
+The authored agent instruction layer drifts as a
+project changes. When it goes stale, incomplete, or a misunderstanding
+surfaces, fix it — checking coverage against: build/test/run commands ·
+layout · conventions · always-do rules.
 
-- When the project changes in a way that makes an instruction stale, or a
-  misunderstanding surfaces that's worth encoding, update the instruction
-  files rather than letting the gap persist.
-- An instruction file should document, for any project: build/test/run
-  commands, project layout, key conventions, and always-do rules. If one of
-  these is missing, fill it by discovery and asking the user — never invent
-  a fact that isn't backed by the code, config, or the user's answer.
-- Prefer linking a canonical source (e.g. an architecture doc) over restating
-  its facts — restated facts drift independently of their source.
-- If a *derived overview* like `README.md` exists, check it hasn't drifted from
-  its canonical sources — being a restatement of them, it drifts by
-  construction; reconcile it to the source rather than the reverse.
-- When instruction files include `praxisAnchors` frontmatter, keep those anchors
-  resolving. `praxis check` hard-fails broken `path`, `command`, and `section`
-  anchors; staleness signals are future advisory work.
-- Make instruction-layer changes through `/praxis-instructions`, not ad-hoc edits — run
-  it when unsure whether the instruction files still match the project, or whether
-  they cover the sections above. When this is part of reconciling the methodology
-  layer after a change, enter through the `/praxis-upkeep` front gate (which
-  delegates here) instead of running this pass alone.
+When multiple first-class targets are selected, audit every native project
+instruction surface. Shared project sections must remain consistent; native
+target-specific sections may differ.
+
+Make changes through `{{workflow:praxis-instructions}}`, not ad-hoc edits. When
+reconciling the methodology layer after a change, enter through
+`{{workflow:praxis-upkeep}}` (which delegates here) instead of running this pass alone.

package/packages/layer1/onboarding/commands/onboard.md

@@ -1,24 +1,37 @@
 ---
-description: Author the project-owned sections of CLAUDE.md for a fresh Praxis install — build/run/test commands, layout, conventions, and always-do rules. One-shot: deletes .praxis-setup-pending when done.
+description: Author project-owned agent instructions for a fresh Praxis install—build/run/test commands, layout, conventions, and always-do rules. One-shot: deletes .praxis-setup-pending when done.
 ---
 
-Scope: $ARGUMENTS
+Scope: {{arguments}}
 
 This is the **first-run front gate** — the single entry point for a fresh Praxis
-install, symmetric to `/praxis-upkeep` (the ongoing front gate). It authors the
-**project-owned** sections of `CLAUDE.md`, then seeds the installed methodology
-packages, then hands off to `/praxis-upkeep` so the full baseline is established
+install, symmetric to `{{workflow:praxis-upkeep}}` (the ongoing front gate). It authors
+the **project-owned** agent instructions, then seeds the installed methodology
+packages, then hands off to `{{workflow:praxis-upkeep}}` so the full baseline is established
 in one pass.
 
-Praxis never calls an LLM (D12); never edits `CLAUDE.md` directly (D13). The
+Praxis never calls an LLM (D12) or authors project facts directly (D13). The
 **agent** writes the facts, guided by the steps below, asking the user for
 anything it cannot infer.
 
-1. **Bulk discovery — lean on the tool's native `/init` first.** If `CLAUDE.md`
-   does not yet exist (or is empty), suggest running the tool's built-in `/init`
-   command so the model can auto-discover repository facts (files, build config,
-   README). Incorporate any useful output into the project-owned sections below,
-   rather than restating it from scratch.
+1. **Choose the project instruction surfaces from `praxis.yaml`.** For a Codex-only
+   install, author project facts as free prose outside managed blocks in `AGENTS.md`.
+   For Claude-only, retain the existing `CLAUDE.md` flow. When both are selected,
+   maintain both native files as peers — never make either import or replace the
+   other. Put facts shared by both tools inside exactly one project-owned block in
+   each file, with identical content and these marker lines:
+
+   ```markdown
+   <!-- praxis:shared-project begin -->
+   ...shared project facts...
+   <!-- praxis:shared-project end -->
+   ```
+
+   The markers declare a parity contract, not Praxis ownership: the project owns
+   the prose and both native files remain complete if Praxis is removed. Guidance
+   outside this block may differ by target. If the active tool offers a native
+   repository initialization workflow, suggest it for bulk discovery and
+   incorporate useful output rather than re-deriving it.
 
 2. **Check detected stacks (if known).** Read `praxis.yaml` for the `stacks:`
    field. If stacks are declared, tailor the sections below to those stacks (e.g.
@@ -44,30 +57,35 @@ anything it cannot infer.
      short; a long always-do list is never read.
 
 4. **Ask the user for anything not inferable.** If a section can't be filled from
-   config files, git history, or the `/init` output, ask a targeted question
-   rather than inventing a plausible answer. Content inclusion bar: a fact only
-   enters if it's backed by the code, config, a canonical doc, or the user.
+   config files, git history, or the native initialization workflow's output, ask
+   a targeted question rather than inventing a plausible answer. Content
+   inclusion bar: a fact only enters if it's backed by the code, config, a
+   canonical doc, or the user.
 
 5. **Write only project-owned content.** Never put content inside a Praxis
-   managed block (a `<!-- praxis-start … -->` / `<!-- praxis-end … -->` region).
-   Project facts belong in the free-prose sections the author controls; Praxis
-   owns only its own managed blocks.
+   managed block (a `<!-- praxis:begin … -->` / `<!-- praxis:end … -->` region).
+   Project facts belong in the free-prose sections the author controls; the
+   unhashed `praxis:shared-project` block is also project-owned. Praxis owns only
+   its hashed managed blocks. When both native files are selected, write the four
+   rubric sections to both shared blocks in one edit and keep their content exact.
 
 6. **Run each installed companion bootstrap action** (each seeds part of the
-   methodology), then hand off to `/praxis-upkeep`:
+   methodology), then hand off to `{{workflow:praxis-upkeep}}`:
 
 <!-- praxis:bootstrap-delegations -->
 
-   After the bootstrap actions above complete, run `/praxis-upkeep` to confirm
-   the full methodology baseline is in sync. If `/praxis-upkeep` is not
+   After the bootstrap actions above complete, run `{{workflow:praxis-upkeep}}` to confirm
+   the full methodology baseline is in sync. If `{{workflow:praxis-upkeep}}` is not
    installed, skip this step.
 
 7. **Delete `.praxis-setup-pending`** to make this one-shot. Once the rubric
-   sections are authored and the user is satisfied, remove the sentinel file
-   from the repo root. This prevents the bootstrap rule (`.claude/rules/
-   praxis-onboarding.md`) from re-offering onboarding on the next session.
+   sections are authored, the bootstrap actions and upkeep pass above have run,
+   and the user is satisfied, remove the sentinel file from the repo root. This
+   prevents the bootstrap rule from re-offering onboarding on the next session —
+   deleting it any earlier would leave an interrupted session with no re-offer
+   and an unseeded baseline.
 
 8. **Report what was written / left.** Summarise which rubric sections were
    filled, which were left empty (and why — e.g. "no build step detected"), and
    any follow-up items for the user. The baseline is now established; from here
-   `/praxis-upkeep` keeps the methodology layer current.
+   `{{workflow:praxis-upkeep}}` keeps the methodology layer current.

package/packages/layer1/onboarding/rules.md

@@ -1,14 +1,10 @@
 ## First-run onboarding
 
 At the start of work, check for the `.praxis-setup-pending` sentinel file in
-the repo root. Its presence means this is a fresh Praxis install and the
-project-owned sections of `CLAUDE.md` haven't been authored yet.
+the repo root: present means a fresh Praxis install whose project-owned agent
+instruction sections aren't authored yet.
 
-- **If the sentinel is present:** offer to run `/praxis-onboard`. Once the
-  skill completes it deletes the sentinel — making this check one-shot and
-  self-terminating. Never nag when the sentinel is absent.
-- **If the sentinel is absent:** do nothing here. The ongoing front gate
-  (`/praxis-upkeep`) handles currency after initial setup.
-
-Cross-references: `/praxis-onboard` (first-run front gate),
-`/praxis-upkeep` (ongoing front gate — D29/D31, [onboarding](../../../docs/wiki/onboarding.md)).
+- **Present:** offer to run `{{workflow:praxis-onboard}}`; it deletes the sentinel on
+  completion, making this check one-shot. Never nag when absent.
+- **Absent:** do nothing here — `{{workflow:praxis-upkeep}}` (ongoing front gate, D29/D31)
+  handles currency after initial setup.

package/packages/layer1/safe-permissions/permissions.yaml

@@ -1,7 +1,7 @@
 # Neutral permission policy — the enforcement side of the rails
 # (docs/wiki/emitters.md, D18/D19). Tool-agnostic INTENT expressed as capabilities; per-tool emitters
-# translate to concrete rule strings (Claude Code today; tools without a
-# permission model emit nothing). Edit your own settings to tune — Praxis owns
+# translate to target-native Claude Code and Codex controls; tools without a
+# permission model emit nothing. Edit your own settings to tune — Praxis owns
 # only the rules it emits and never clobbers rules you add.
 #
 # Posture: allow common local dev (smooth); prompt before anything that leaves the

package/packages/layer1/session-handoff/commands/handoff.md

@@ -46,10 +46,10 @@ single-doc flow below.
 
 Read the clock so the name sorts chronologically (do not guess the time):
 
-- Timestamp: !`date +%Y-%m-%d_%H%M`
+- Timestamp: {{shell:date +%Y-%m-%d_%H%M}}
 
 Build the filename `YYYY-MM-DD_HHMM_HANDOFF_<topic>.md`:
-- `<topic>` is a short kebab-case slug for the work. Use `$ARGUMENTS` if
+- `<topic>` is a short kebab-case slug for the work. Use {{arguments}} if
   provided; otherwise derive it from the task.
 - Date-and-time first means a plain alphabetical listing is chronological.
 
@@ -73,9 +73,9 @@ references* section below. Don't re-derive them; you already paid for them.
 If in a git repo, capture current branch, staged/unstaged changes, and recent
 commits from this session:
 
-- Branch: !`git branch --show-current 2>/dev/null`
-- Status: !`git status --short 2>/dev/null`
-- Recent commits: !`git log --oneline -10 2>/dev/null`
+- Branch: {{shell:git branch --show-current 2>/dev/null}}
+- Status: {{shell:git status --short 2>/dev/null}}
+- Recent commits: {{shell:git log --oneline -10 2>/dev/null}}
 
 Capture verification state too: identify the project's own build/test/lint
 commands (from its config / docs / CI) and record their current result — what

package/packages/layer1/session-handoff/rules.md

@@ -1,62 +1,15 @@
 ## Session handoff
 
-Work outlives a single session: context windows fill, tasks switch, phases
-close. Before that state is lost, capture it — so a fresh session, with none of
-the current conversation in memory, can resume without guessing or re-deriving.
-
-- Hand off at a natural boundary in a verified state — not mid-edit. Stop where
-  the build and tests are green, or where any breakage is understood and noted.
-- Write handoffs by running `/praxis-handoff`, not by hand — it produces a
-  self-contained, chronologically-named document. Treat it as the next session's
-  only briefing.
-- Make it actionable: what's done, what's pending, the single most important
-  next step, verification status, and any open decisions.
-- Carry the context forward, don't just summarize it. Reference the load-bearing
-  files (`path:line`), the relevant design-doc sections, the prior-art to mirror,
-  and the exact commands — so the next session skips re-running discovery.
-- Note instruction-layer follow-up: if the session changed the project in a way
-  that makes the authored instruction files stale or incomplete, say so.
-- Keep handoffs together in one directory so they sort in chronological order;
-  don't scatter them into the codebase.
+Work outlives a single session: at a natural boundary in a verified state —
+never mid-edit — capture context before it's lost. Write handoffs by running
+`{{workflow:praxis-handoff}}`, not by hand; it's the next session's only briefing.
 
 ## Delegated execution
 
-A handoff brief is not only for the *next* session — it is also the briefing an
-execution agent needs to do scoped work *now*. The reason to delegate is to keep
-in the orchestrator's context only what it needs — the *result*, not the
-execution detail — and to match each piece of work to the cheapest tier that can
-do it. Delegate when that holds; do the work inline when it doesn't.
-
-- Delegate when you need the result, not the detail. Two triggers, often
-  combined — **neither requires parallelism**:
-  - *Independent workstreams* — parts specifiable up front and runnable without
-    coordination mid-flight (concurrently, where the tool allows). If two parts
-    must talk constantly, they are one workstream.
-  - *Context or budget isolation* — a context-heavy or mechanical run (a wide
-    refactor, a multi-step migration, a long grind) worth executing in an
-    execution agent's *own* context window, on a lighter/faster tier, so the
-    orchestrator's context stays clean. This holds for a *single sequential*
-    stream: size and cost justify delegating on their own.
-- Name the split at plan time. When a plan's steps form independent or
-  context-heavy workstreams, surface the delegation split *as part of the plan* —
-  what each execution agent runs and how its result returns — rather than only
-  deciding to delegate mid-execution.
-- Brief each workstream as a self-contained context cache — the same discipline
-  as a handoff. An execution agent starts cold: give it the load-bearing files
-  (`path:line`), the prior art to mirror, the exact build/test commands, and a
-  crisp success/verify criterion. A vague brief gets vague work back.
-- Keep the tiers to their jobs. The orchestrator plans, decomposes, verifies, and
-  integrates; execution agents do bounded, fully-specified work and return the
-  result, not the intermediate detail. Match the tier to the work — execution
-  agents can be lighter/faster than the orchestrator. (Stated by role, not by
-  model name, so it survives model releases.)
-- Verify on return; trust nothing unread. Each returned workstream is checked
-  against its stated success criterion (build, tests, a read of the diff) before
-  it is integrated — the orchestrator owns correctness of the whole.
-- Produce the briefs with `/praxis-handoff` (run it per workstream), not by hand,
-  so each is self-contained. Dispatch a subagent per brief where the tool
-  supports subagents; where it does not, run the briefs inline in sequence or
-  hand them to a fresh session — same brief, different venue.
-- Use judgment on whether to delegate at all. It pays off for multi-workstream or
-  context-heavy work; for a small single-thread change the briefing cost exceeds
-  the savings — just do it inline.
+Delegate when you need the result, not the execution detail. Two triggers,
+neither requiring parallelism: **independent workstreams** (specifiable up
+front, no mid-flight coordination) and **context/budget isolation** (a
+context-heavy or mechanical run worth its own context and a lighter tier —
+holds even for one sequential stream). Name the split at plan time. Produce
+each brief with `{{workflow:praxis-handoff}}`, not by hand, and verify a returned
+workstream against its success criterion before integrating it.