# Pillar #8 — Outputs projects/<client>/<skill>/<run\_id>/ convention for skill outputs + evidence # Convention — projects//// ``` ## §3 Proposed Convention ### 3.1 Root location All skill outputs, evidence artifacts, and forge deliverables write under: ``` ~/projects//// ``` Where: - `` — client slug (e.g., `bilko`, `drop`, `intesa`) or `alai` for internal ALAI work. - `` — one of: skill name (e.g., `task-postflight`), `mc-` (for MC-scoped work), or `forge` (for forged prompts/artifacts). - `` — `YYYY-MM-DD--` (sortable by date, traceable to MC, unique per run). ### 3.2 Path table | Output type | Path pattern | Concrete example | |---|---|---| | Skill output (generic) | `~/projects////` | `~/projects/alai/task-postflight/2026-05-05-99292-a1b2c3/` | | Builder evidence | `~/projects//mc-/evidence/` | `~/projects/bilko/mc-10611/evidence/` | | Forge artifacts | `~/projects//mc-/forge/` | `~/projects/alai/mc-99102/forge/` | | Brief (input) | `/brief.md` | `~/projects/alai/task-postflight/2026-05-05-99292-a1b2c3/brief.md` | | Outcome (output) | `/outcome.md` | `~/projects/alai/task-postflight/2026-05-05-99292-a1b2c3/outcome.md` | | Supplemental evidence | `/evidence/` | `~/projects/alai/task-postflight/2026-05-05-99292-a1b2c3/evidence/` | | Provenance record | `/.provenance.json` | `~/projects/alai/task-postflight/2026-05-05-99292-a1b2c3/.provenance.json` | ### 3.3 run_id format ``` YYYY-MM-DD-- ``` Example: `2026-05-05-99292-a1b2c3` - **YYYY-MM-DD** — ISO date of run start. Enables `ls -t` chronological sort. - **** — Mission Control task id. Enables direct lookup via `mc.js show`. - **** — 6-character random hex. Prevents collision when the same MC triggers multiple runs in one day. For runs not tied to a specific MC (e.g., background daemon output), use `mc-0` as the mcid segment. ### 3.4 `.provenance.json` schema ```json { "mc_id": "99292", "agent": "codecraft", "model": "claude-sonnet-4-6", "timestamp": "2026-05-05T21:26:00Z", "skill": "task-postflight", "client": "alai", "run_id": "2026-05-05-99292-a1b2c3" } ``` All fields are string. `timestamp` is ISO 8601 UTC. Written at run start (not completion) so partial runs are recoverable. ### 3.5 brief.md The brief is the input contract for the run. It is written by the invoking agent before execution begins. Content: MC task description + acceptance criteria (or equivalent task spec). For skills invoked by task-postflight, the AC list IS the brief. For codecraft builds, the Mehanik-cleared BUILD-BLUEPRINT section is the brief. Brief is written first, outcome last. If a run crashes, the brief survives and the run is recoverable. --- ``` # Tool Support — output-path.js ``` ## §4 Tool Support ### 4.1 `output-path.js` helper **Location:** `~/system/tools/output-path.js` **CLI interface:** ```bash node ~/system/tools/output-path.js resolve \ --client alai \ --skill task-postflight \ --mc 99292 ``` Returns: absolute path to the run directory. Creates directory (and `evidence/` subdirectory) if missing. Writes `.provenance.json` on first call. **Flags:** | Flag | Required | Description | |---|---|---| | `--client` | yes | Client slug or `alai` | | `--skill` | yes | Skill name or `mc-` for builder evidence | | `--mc` | yes | MC task id (numeric string) | | `--model` | no | Model name for provenance (default: unknown) | | `--agent` | no | Agent persona name for provenance (default: unknown) | **Idempotent contract:** Given identical `--client`, `--skill`, `--mc` arguments, the tool always returns the same path. On subsequent calls, the directory already exists — no error, no duplicate. The `run_id` is derived deterministically from the mc_id and the date of first creation (stored in `.provenance.json`), not regenerated on each call. **Exit codes:** `0` = success + path printed to stdout. `1` = missing required flag (error to stderr). ### 4.2 Node.js library counterpart ```js const { resolve } = require('~/system/tools/output-path'); const runDir = resolve({ client: 'alai', skill: 'task-postflight', mc: '99292', agent: 'codecraft', model: 'claude-sonnet-4-6' }); // Returns: '/Users/makinja/projects/alai/task-postflight/2026-05-05-99292-a1b2c3' // Side effects: mkdir -p, writes .provenance.json if not present ``` The library is a thin wrapper around the same logic as the CLI. It does not start a subprocess. Both the CLI and library are the same file — the CLI entry point is a `if (require.main === module)` guard. ### 4.3 No new infrastructure `output-path.js` uses only Node.js built-ins (`fs`, `path`, `crypto`). No npm dependencies. No network calls. No database writes. It is a pure path-calculator with side-effect-free idempotency. --- ``` # 3-Phase Migration Plan ``` ## §5 Migration Phases Migration is additive. No existing file is moved. No existing convention is broken. Each phase adds structure; nothing removes it. ### Phase 1 — Week 1: Tool exists, new invocations opt in **Deliverable:** `~/system/tools/output-path.js` exists and is tested. Documentation page on BookStack (Agentic OS shelf). Release note in HiveMind. **Behavior change:** New skill invocations that are aware of the helper call `output-path.js resolve` to get their run directory. Old invocations continue to write to `/tmp/-evidence/` or wherever they currently write. Both paths coexist. **Migration bar:** Zero. No skill is forced to change. No existing output moves. **Success signal:** At least one skill uses the new convention and the resulting directory exists under `~/projects/`. ### Phase 2 — Week 2-3: Three highest-volume skills opt in **Target skills (by observed invocation frequency):** 1. `task-postflight` — runs after every MC completion 2. `codecraft` sub-agent — runs for every build/design task dispatched to CodeCraft 3. `proveo` sub-agent — runs for every validation task **Changes per skill:** - `brief.md` written at invocation start (from MC description). - Outcome written to `/outcome.md` instead of terminal-only report. - Evidence written to `/evidence/` instead of `/tmp/-evidence/`. - `.provenance.json` written by `output-path.js` on first call. **Backward compat:** Skills also write a symlink at the old `/tmp/-evidence/` location pointing to the new canonical path, for a 2-week grace period. After grace period, symlinks are removed (not the targets). **Migration bar:** Opt-in. Each skill's maintainer (or the dispatching orchestrator) adds one `output-path.js resolve` call to the skill's preamble. ### Phase 3 — Deferred (month+): Linter and audit **Deferred until Phases 1-2 are stable (≥2 weeks of clean runs).** - **Audit script:** `~/system/tools/output-audit.js` scans /tmp/ for `*-evidence` directories older than 7 days. Reports count and size. Does NOT move or delete. Runs as a weekly LaunchAgent. - **Lint hook:** A `pre-mc-ready` hook checks evidence references in the MC outcome field. If any reference points to `/tmp/` or `~/Public/` instead of `~/projects/`, hook emits a warning (stderr). NOT a block. Warning only. - **Scope:** Phase 3 is intentionally deferred. Do not build it during Phase 1 or 2. Its value depends on Phase 2 adoption proving the convention stable. ### What NEVER happens - Auto-move of any existing file or directory. - Destructive consolidation of `/tmp/` contents. - Breaking changes to any skill that does not opt in. - Forced migration of `~/Public/` deliverables (CEO-facing files stay where CEO puts them). --- ``` # Enforcement Options A+B ``` ## §6 Enforcement Three options, ranked by intrusiveness: ### Option A — Lint-on-mc-ready (least intrusive) [RECOMMENDED] A `pre-mc-ready` bash hook intercepts `mc.js ready ` calls. It reads the MC outcome/evidence field and checks whether any path reference points to a non-canonical location (`/tmp/`, `~/Public/`, `~/Downloads/`). If so, it emits a **warning to stderr** — not a block. The operator sees the warning, can investigate, and the `ready` transition proceeds regardless. - **Implementation:** ~30 lines of bash added to existing hook chain. - **Risk:** Near zero. Warn-only means no false positives block work. - **Adoption:** Immediate — no skill changes needed. ### Option B — Skill SDK helper (opt-in) [RECOMMENDED alongside A] Skills call `output-path.js resolve` as the first action of their preamble. This is not enforced by a hook — it is adopted voluntarily by each skill's author. The helper enforces canonical paths structurally (you cannot call it and get a non-canonical path). - **Implementation:** One `require()` or one bash call per skill. - **Risk:** Zero. Opt-in. Non-adopting skills are unaffected. - **Adoption:** Gradual, driven by Phase 2 opt-in targets. ### Option C — pre-tool-use hook blocking ~/Downloads/ and ~/Public/ writes (most intrusive) [DEFERRED] A `pre-tool-use` bash hook intercepts any file Write or Bash command that targets `~/Downloads/` or `~/Public/` when a `MC_ACTIVE_TASK` environment variable is set. Blocks the write and redirects to canonical path. - **Risk:** High false positive rate. CEO legitimately writes to `~/Public/` for grant deliverables. Blocking these creates friction with no benefit. - **Decision: Deferred.** Do not build Option C until Phase 2 proves the convention stable and Option A/B adoption is measurable. **Recommendation: Implement Option A + Option B together. Option C deferred indefinitely until evidence of need.** --- ``` # Skill Examples (3) ``` ## §7 Per-Skill Examples ### 7.1 task-postflight **Current behavior:** Evidence written to `/tmp/postflight-/` (when it exists at all). Outcome is terminal output only. Brief (the AC list) exists only in the MC description, not alongside the output. **After Phase 2:** ``` ~/projects/alai/task-postflight/2026-05-05-99292-a1b2c3/ brief.md # AC list copied from mc.js show at invocation start outcome.md # Final pass/fail report with per-AC verdicts evidence/ # Raw command outputs, curl responses, screenshots 01-curl-health.txt 02-grep-section.txt .provenance.json # {mc_id, agent, model, timestamp, skill, client, run_id} ``` **Replaces:** `/tmp/postflight-/` and terminal-only reporting. **Brief source:** `node ~/system/tools/mc.js show ` description field, written verbatim at run start. ### 7.2 codecraft build / design task **Current behavior:** Evidence written to `/tmp/-evidence/` (codecraft convention). Brief (the Mehanik-cleared BUILD-BLUEPRINT excerpt) is in the orchestrator's dispatch prompt only — not persisted alongside output. Code diffs, if produced, go to terminal or arbitrary file locations. **After Phase 2:** ``` ~/projects//mc-/evidence/ brief.md # BUILD-BLUEPRINT section relevant to this MC diff.patch # git diff of changes made (if applicable) outcome.md # Sub-agent final report (the CODECRAFT SUB-AGENT REPORT block) evidence/ 01-build-output.txt 02-test-results.txt .provenance.json ``` **Replaces:** `/tmp/-evidence/` and scattered diff files. **Brief source:** MC description + BUILD-BLUEPRINT section passed in the dispatch prompt, written to `brief.md` before any tool calls begin. ### 7.3 proveo validation **Current behavior:** Validation reports go to terminal. Evidence written to `/tmp/proveo--*.txt` (flat files, no directory). Result summary is in the MC outcome field (text string) only. No machine-readable result file. **After Phase 2:** ``` ~/projects//mc-/evidence/ brief.md # AC list + source-of-truth directory stated at invocation outcome.md # Human-readable pass/fail report with per-AC verdicts result.json # Machine-readable: {mc_id, pass_count, fail_count, acs: [...]} evidence/ 01-ac1-curl.txt 02-ac2-grep.txt 03-ac3-wc.txt .provenance.json ``` **Replaces:** `/tmp/proveo--*.txt` flat files and terminal-only reporting. **Brief source:** AC list from `mc.js show ` + any source-of-truth paths stated in the MC description. --- ```