compound-workflow 1.4.0 → 1.4.2

package/README.md

@@ -19,6 +19,7 @@ Runtime assets live in `src/.agents/` and `src/AGENTS.md`. Supports **Cursor**,
 ```bash
 npm install compound-workflow
 npx compound-workflow install
+npx compound-workflow install all
 ```
 
 **2. Choose how you use it:**
@@ -29,7 +30,7 @@ npx compound-workflow install
 
 **What Install does:** Merges `AGENTS.md` (preserves your Repo Config Block), creates standard dirs (`docs/`, `todos/`), writes `opencode.json` (for OpenCode), and—if the project has a `.cursor` directory—creates `.cursor/skills/<skill>`, `.cursor/agents`, `.cursor/commands`, and `.cursor/references` (symlinks into the package). All paths reference `node_modules/compound-workflow`; no file copying.
 
-**CLI options:** `--dry-run` (preview), `--root /path/to/project`, `--no-config` (skip Repo Config Block reminder), `--cursor` (create `.cursor` and wire Cursor symlinks even if `.cursor` does not already exist).
+**CLI options:** `all` / `--all` (full install shortcut; same as `--cursor`), `--dry-run` (preview), `--root /path/to/project`, `--no-config` (skip Repo Config Block reminder), `--cursor` (create `.cursor` and wire Cursor symlinks even if `.cursor` does not already exist).
 
 **Legacy (clone inside repo):** If you cloned this repo inside a host repo and need to copy files without npm, use `./scripts/sync-into-repo.sh` (copy only; does not update opencode.json). Prefer the npm + Install flow above.
 
@@ -57,6 +58,10 @@ flowchart LR
 
 ---
 
+If docs conflict: follow [docs/principles/workflow-baseline-principles.md](docs/principles/workflow-baseline-principles.md), then [src/AGENTS.md](src/AGENTS.md), then command docs under [src/.agents/commands/](src/.agents/commands/).
+
+---
+
 ## Step-by-step: intent and commands
 
 | Step | Intent | Command | Output / note |
@@ -64,8 +69,8 @@ flowchart LR
 | Clarify what to build | Dialogue only; no code | `/workflow:brainstorm [topic]` | `docs/brainstorms/` |
 | Define how (fidelity + confidence) | Plan only; no code; include agentic access + validation contract | `/workflow:plan [description or brainstorm path]` | `docs/plans/` |
 | Ready the queue | Priority/dependencies + executable agentic contract checks for pending todos | `/workflow:triage` | — |
-| Execute | File-based todos; risk-tier testing; evidence-backed completion; no auto-ship | `/workflow:work <plan-path>` | `todos/` |
-| Validate quality | Evidence-based review + agentic executability checks; no fixes by default | `/workflow:review [PR, branch, or current]` | pass / pass-with-notes / fail |
+| Execute | File-based todos; risk-tier testing; evidence-backed implementation; no auto-ship | `/workflow:work <plan-path>` | `todos/` |
+| Validate quality | Independent, evidence-based review for code/config changes (docs-only exempt); no fixes by default | `/workflow:review [PR, branch, or current]` | pass / pass-with-notes / fail |
 | Capture learnings | One solution doc for future use | `/workflow:compound [context]` | `docs/solutions/` |
 | Log and improve | Session log + optional aggregate review | `/metrics` + `/assess weekly 7` (or monthly) | `docs/metrics/daily/`, weekly/monthly |
 
@@ -87,9 +92,11 @@ flowchart LR
 
 `/workflow:work` must not run until `/workflow:triage` has approved executable ready todos.
 
+For code/config changes, `/workflow:work` ends at implementation-complete and requires `/workflow:review` before workflow completion. Docs-only work can close without `/workflow:review`.
+
 #### 5. Validate quality (review)
 
-**Intent:** Evidence-based review + agentic validation coverage checks; no fixes by default. **Command:** `/workflow:review [PR|branch|current]`. **Output:** pass / pass-with-notes / fail.
+**Intent:** Independent, evidence-based review with explicit independence mode (`independent|degraded`) and evidence disclosure; no fixes by default. **Command:** `/workflow:review [PR|branch|current]`. **Output:** pass / pass-with-notes / fail.
 
 #### 6. Capture learnings (compound)
 
@@ -151,8 +158,14 @@ Full “when to use what” and reference standards: [src/AGENTS.md](src/AGENTS.
 
 - **Todo completion requires evidence:** acceptance/success criteria plus quality gates must be recorded before `complete`.
 
+- **Independent review policy:** code/config changes require `/workflow:review` before workflow completion; docs-only changes are exempt.
+
+- **Standards baseline policy:** code/config changes must pass `skill: standards` as a hard gate (declarative flow, immutable transforms, maintainability boundaries) in both `/workflow:work` and `/workflow:review`; docs-only changes are exempt.
+
 - **Quality gate fallback:** if `lint_command` or `typecheck_command` is missing from repo config, workflow asks once for run-provided commands and continues only if they pass.
 
+- **Artifact policy:** do not create ad-hoc artifacts outside canonical outputs (`docs/plans`, `todos`, `docs/solutions`, `docs/metrics`) unless explicitly requested.
+
 - Add a separate shipping command if you want automated commit/PR and quality gates.
 
 ---
@@ -176,4 +189,5 @@ If your project does not already have `.cursor/`, run `npx compound-workflow ins
 **Source of truth**
 
 - Workflows and commands: [src/.agents/](src/.agents/)
+- Baseline principles (tie-breaker): [docs/principles/workflow-baseline-principles.md](docs/principles/workflow-baseline-principles.md)
 - Principles and skill index: [src/AGENTS.md](src/AGENTS.md)

package/package.json

@@ -1 +1,31 @@
-{"name":"compound-workflow","version":"1.4.0","description":"Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/cjerochim/compound-workflow.git"},"bin":{"compound-workflow":"scripts/install-cli.mjs"},"files":["src","scripts",".cursor-plugin",".claude-plugin","skills"],"scripts":{"check:pack-readme":"node scripts/check-pack-readme.mjs"},"engines":{"node":">=18"},"devDependencies":{"@semantic-release/git":"^10.0.1","@semantic-release/npm":"^13.1.4","semantic-release":"^25.0.3"}}
+{
+  "name": "compound-workflow",
+  "version": "1.4.2",
+  "description": "Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cjerochim/compound-workflow.git"
+  },
+  "bin": {
+    "compound-workflow": "scripts/install-cli.mjs"
+  },
+  "files": [
+    "src",
+    "scripts",
+    ".cursor-plugin",
+    ".claude-plugin",
+    "skills"
+  ],
+  "scripts": {
+    "check:pack-readme": "node scripts/check-pack-readme.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^13.1.4",
+    "semantic-release": "^25.0.3"
+  }
+}

package/scripts/check-workflow-contracts.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const root = process.cwd();
+
+const requiredChecks = [
+  {
+    file: "docs/principles/workflow-baseline-principles.md",
+    pattern: "tie-breaker",
+    description: "baseline principles tie-breaker rule",
+  },
+  {
+    file: "src/AGENTS.md",
+    pattern: "## Contract Precedence",
+    description: "AGENTS contract precedence section",
+  },
+  {
+    file: "src/AGENTS.md",
+    pattern: "No ad-hoc artifacts outside canonical outputs",
+    description: "canonical artifact policy in AGENTS",
+  },
+  {
+    file: "src/AGENTS.md",
+    pattern: "Standards baseline is mandatory for code/config changes.",
+    description: "standards hard-gate policy in AGENTS",
+  },
+  {
+    file: "README.md",
+    pattern: "If docs conflict:",
+    description: "README conflict resolution note",
+  },
+  {
+    file: "README.md",
+    pattern: "code/config changes require `/workflow:review`",
+    description: "README review gate policy",
+  },
+  {
+    file: "README.md",
+    pattern: "Standards baseline policy:",
+    description: "README standards baseline guardrail",
+  },
+  {
+    file: "src/.agents/commands/workflow/plan.md",
+    pattern: "Contract precedence:",
+    description: "plan command precedence note",
+  },
+  {
+    file: "src/.agents/commands/workflow/triage.md",
+    pattern: "Contract precedence:",
+    description: "triage command precedence note",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "Contract precedence:",
+    description: "work command precedence note",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "HARD GATE - WORKTREE FIRST",
+    description: "worktree hard-gate wording in work command",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern:
+      "No file writes, implementation commands, test/lint/typecheck commands, or dependency-install commands may run before this gate passes.",
+    description: "pre-gate write/command prohibition in work command",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "workflow_complete: false (pending /workflow:review current)",
+    description: "implementation-complete pending-review status in work command",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "Standards Compliance Gate (REQUIRED for code/config changes)",
+    description: "required standards gate in work command",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "This gate cannot run until the isolation/worktree gate is passed and recorded (`gate_status: passed`).",
+    description: "standards gate ordering with worktree gate",
+  },
+  {
+    file: "src/.agents/commands/workflow/review.md",
+    pattern: "Contract precedence:",
+    description: "review command precedence note",
+  },
+  {
+    file: "src/.agents/commands/workflow/review.md",
+    pattern: "Independent Reviewer Pass (REQUIRED)",
+    description: "required independent reviewer pass in review command",
+  },
+  {
+    file: "src/.agents/commands/workflow/review.md",
+    pattern: "review_independence_mode: independent|degraded",
+    description: "explicit review independence mode in review command",
+  },
+  {
+    file: "src/.agents/commands/workflow/review.md",
+    pattern: "what was skipped and why",
+    description: "review skipped-pass disclosure requirement",
+  },
+  {
+    file: "src/.agents/commands/workflow/review.md",
+    pattern: "standards_compliance: pass|pass-with-notes|fail",
+    description: "review standards compliance output field",
+  },
+  {
+    file: "src/.agents/commands/workflow/review.md",
+    pattern: "standards `MUST` violations => blocking finding and review recommendation `fail`",
+    description: "review must-violation fail criteria",
+  },
+  {
+    file: "src/.agents/skills/standards/SKILL.md",
+    pattern: "## Mandatory Baseline (Declarative, Immutable, Maintainable)",
+    description: "standards mandatory baseline section",
+  },
+  {
+    file: "src/.agents/skills/standards/SKILL.md",
+    pattern: "### MUST NOT",
+    description: "standards must-not checklist",
+  },
+];
+
+const forbiddenChecks = [
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "## When to Use Reviewer Agents",
+    description: "legacy optional reviewer section in work command",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "**Don't use by default.**",
+    description: "legacy skip-by-default reviewer wording in work command",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "skip specialist reviewers by default",
+    description: "legacy skip-by-default specialist reviewer wording",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "Follow project coding standards (see AGENTS.md)",
+    description: "legacy advisory-only coding standards wording in work command",
+  },
+];
+
+const failures = [];
+
+const readFile = (relativePath) => {
+  const absolutePath = path.join(root, relativePath);
+  if (!fs.existsSync(absolutePath)) {
+    failures.push(`Missing file: ${relativePath}`);
+    return "";
+  }
+  return fs.readFileSync(absolutePath, "utf8");
+};
+
+for (const check of requiredChecks) {
+  const contents = readFile(check.file);
+  if (!contents.includes(check.pattern)) {
+    failures.push(`Missing required contract text (${check.description}) in ${check.file}`);
+  }
+}
+
+for (const check of forbiddenChecks) {
+  const contents = readFile(check.file);
+  if (contents.includes(check.pattern)) {
+    failures.push(`Found forbidden contract text (${check.description}) in ${check.file}`);
+  }
+}
+
+if (failures.length > 0) {
+  console.error("Workflow contract drift check failed:");
+  for (const failure of failures) console.error(`- ${failure}`);
+  process.exit(1);
+}
+
+console.log("Workflow contract check passed.");

package/scripts/install-cli.mjs

@@ -2,7 +2,7 @@
 /**
  * compound-workflow install
  * One action: opencode.json (load from package) + AGENTS.md merge + dirs + Repo Config Block.
- * Run from project: npx compound-workflow install [--root <dir>] [--dry-run] [--no-config]
+ * Run from project: npx compound-workflow install [all|--all] [--root <dir>] [--dry-run] [--no-config]
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -14,11 +14,12 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function usage(exitCode = 0) {
   const msg = `
 Usage:
-  npx compound-workflow install [--root <projectDir>] [--dry-run] [--no-config] [--cursor]
+  npx compound-workflow install [all|--all] [--root <projectDir>] [--dry-run] [--no-config] [--cursor]
 
 One action: writes opencode.json (loads from package), merges AGENTS.md, creates dirs,
 and prompts for Repo Config Block (unless --no-config).
 
+  all, --all    Full install shortcut (enables Cursor integration; creates .cursor if needed)
   --root <dir>   Project directory (default: cwd)
   --dry-run      Print planned changes only
   --no-config   Skip Repo Config Block prompt (only write opencode.json + AGENTS.md + dirs)
@@ -35,6 +36,7 @@ function parseArgs(argv) {
     if (a === "--dry-run") out.dryRun = true;
     else if (a === "--no-config") out.noConfig = true;
     else if (a === "--cursor") out.cursor = true;
+    else if (a === "--all" || a === "all") out.cursor = true;
     else if (a === "--root") {
       const v = argv[i + 1];
       if (!v) usage(1);
@@ -309,7 +311,7 @@ function ensureCursorSkills(targetRoot, dryRun, cursorReady) {
   const blocked = [];
   for (const name of skillNames) {
     const linkPath = path.join(skillsDir, name);
-    const targetRel = path.join("..", "..", "..", "node_modules", "compound-workflow", "src", ".agents", "skills", name);
+    const targetRel = path.join("..", "..", "node_modules", "compound-workflow", "src", ".agents", "skills", name);
     const targetAbs = path.resolve(path.dirname(linkPath), targetRel);
     let needCreate = true;
     try {
@@ -345,12 +347,53 @@ function verifyCursorIntegration(targetRoot) {
   for (const check of checks) {
     const linkPath = path.join(cursorDir, check.rel);
     const expectedAbs = path.join(targetRoot, "node_modules", "compound-workflow", "src", ".agents", check.rel);
-    if (!symlinkPointsTo(linkPath, expectedAbs)) issues.push(`${check.name} is missing or not linked to package`);
+    if (!fs.existsSync(linkPath)) issues.push(`${check.name} is missing`);
+    else {
+      const stat = fs.lstatSync(linkPath);
+      if (stat.isSymbolicLink() && !symlinkPointsTo(linkPath, expectedAbs)) {
+        issues.push(`${check.name} symlink points to unexpected target`);
+      }
+    }
+  }
+
+  const packageSkillsDir = path.join(packageRoot, "src", ".agents", "skills");
+  if (fs.existsSync(packageSkillsDir)) {
+    const missingSkills = [];
+    for (const name of fs.readdirSync(packageSkillsDir)) {
+      const skillPath = path.join(packageSkillsDir, name);
+      if (!fs.statSync(skillPath).isDirectory()) continue;
+      if (!fs.existsSync(path.join(skillPath, "SKILL.md"))) continue;
+      const cursorSkill = path.join(cursorDir, "skills", name, "SKILL.md");
+      if (!fs.existsSync(cursorSkill)) missingSkills.push(name);
+    }
+    if (missingSkills.length) {
+      issues.push(
+        `.cursor/skills is missing ${missingSkills.length} package skill(s), e.g. ${missingSkills[0]}`
+      );
+    }
   }
 
-  const workCommand = path.join(cursorDir, "commands", "workflow", "work.md");
-  if (!fs.existsSync(workCommand)) {
-    issues.push(".cursor/commands/workflow/work.md is not reachable after integration");
+  const packageRoots = [
+    { label: "commands", pkgDir: path.join(packageRoot, "src", ".agents", "commands"), cursorSubdir: "commands" },
+    { label: "agents", pkgDir: path.join(packageRoot, "src", ".agents", "agents"), cursorSubdir: "agents" },
+    { label: "references", pkgDir: path.join(packageRoot, "src", ".agents", "references"), cursorSubdir: "references" },
+  ];
+  for (const item of packageRoots) {
+    if (!fs.existsSync(item.pkgDir)) continue;
+    const pkgFiles = walkFiles(item.pkgDir, () => true);
+    let missingCount = 0;
+    let firstMissing = null;
+    for (const abs of pkgFiles) {
+      const rel = path.relative(item.pkgDir, abs);
+      const targetFile = path.join(cursorDir, item.cursorSubdir, rel);
+      if (!fs.existsSync(targetFile)) {
+        missingCount++;
+        if (!firstMissing) firstMissing = rel;
+      }
+    }
+    if (missingCount) {
+      issues.push(`.cursor/${item.label} is missing ${missingCount} package file(s), e.g. ${firstMissing}`);
+    }
   }
   return issues;
 }
@@ -359,7 +402,7 @@ function ensureCursorIntegration(targetRoot, dryRun, forceCursor) {
   const cursorDir = path.join(targetRoot, ".cursor");
   let cursorReady = fs.existsSync(cursorDir);
   if (!fs.existsSync(cursorDir)) {
-    if (!forceCursor) return { issues: [] };
+    if (!forceCursor) return { issues: [], status: "skipped-no-cursor" };
     if (dryRun) console.log("[dry-run] Would create .cursor directory (Cursor)");
     else {
       fs.mkdirSync(cursorDir, { recursive: true });
@@ -388,7 +431,7 @@ function ensureCursorIntegration(targetRoot, dryRun, forceCursor) {
   if (!dryRun) {
     for (const issue of verifyCursorIntegration(targetRoot)) issues.push(issue);
   }
-  return { issues };
+  return { issues, status: "configured" };
 }
 
 function writeOpenCodeJson(targetRoot, dryRun) {
@@ -540,6 +583,11 @@ function main() {
   ensureSkillsSymlink(targetRoot, args.dryRun);
   reportOpenCodeIntegration(targetRoot, args.dryRun);
   const cursorReport = ensureCursorIntegration(targetRoot, args.dryRun, args.cursor);
+  if (cursorReport.status === "skipped-no-cursor") {
+    console.log("Cursor integration: skipped (.cursor missing). Run install with `all` or `--cursor` to create it.");
+  } else {
+    console.log("Cursor integration: verified skills, agents, commands, and references.");
+  }
   writeAgentsMd(targetRoot, args.dryRun);
   ensureDirs(targetRoot, args.dryRun);
 

package/src/.agents/commands/install.md

@@ -1,8 +1,8 @@
 ---
 name: install
 invocation: install
-description: Install compound-workflow in this project (one action)—opencode.json, AGENTS.md, dirs, and Repo Config Block.
-argument-hint: "[--dry-run] [--root <path>] [--no-config]"
+description: Install compound-workflow in this project (one action)—opencode.json, AGENTS.md, dirs, Repo Config Block, and optional Cursor wiring.
+argument-hint: "[all|--all] [--dry-run] [--root <path>] [--no-config] [--cursor]"
 ---
 
 # /install
@@ -24,6 +24,7 @@ Run in the **workspace root** (or the directory the user specifies):
 
 ```bash
 npx compound-workflow@latest install
+npx compound-workflow@latest install all
 ```
 
 Or with a specific root and flags:
@@ -32,11 +33,14 @@ Or with a specific root and flags:
 npx compound-workflow install --root /path/to/project
 npx compound-workflow install --dry-run
 npx compound-workflow install --no-config
+npx compound-workflow install --cursor
 ```
 
+- **all / --all**: Full install shortcut; same as `--cursor` (creates `.cursor` if missing, then wires skills/agents/commands/references).
 - **--dry-run**: Print planned changes only; no writes.
 - **--root &lt;path&gt;**: Target project directory (default: current directory).
 - **--no-config**: Skip Repo Config Block reminder; only write opencode.json, AGENTS.md merge, and dirs.
+- **--cursor**: Force Cursor integration (create `.cursor` if missing, then wire skills/agents/commands/references).
 
 Do not copy files from a compound-workflow clone; the Install CLI uses the package from `node_modules/compound-workflow`.
 

package/src/.agents/commands/workflow/plan.md

@@ -13,6 +13,8 @@ argument-hint: "[feature description, bug report, improvement idea, or brainstor
 
 Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown plan files that follow project conventions and best practices. This command provides flexible detail levels to match your needs.
 
+Contract precedence: if this command conflicts with other workflow docs, follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then this command.
+
 This workflow MUST choose a planning fidelity and confidence level before final plan construction:
 
 - Fidelity: `Low | Medium | High`

package/src/.agents/commands/workflow/review.md

@@ -9,6 +9,8 @@ argument-hint: "[PR number, GitHub URL, branch name, or 'current']"
 
 Run a structured, evidence-based **code** review. This command produces findings and recommendations; it does not implement fixes by default.
 
+Contract precedence: if this command conflicts with other workflow docs, follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then this command.
+
 **If the user provides a document path** (e.g. a plan or spec): redirect to the `technical-review` skill for technical correctness (no edits), and/or the `document-review` skill to refine the document. This command does not review documents.
 
 Guardrails (unless explicitly requested):
@@ -101,6 +103,11 @@ Protected artifacts:
 
 - `Task learnings-researcher(<target context>)` (related prior solutions)
 - `Task lint(<changed files context>)` only if `lint_command` is configured in the Repo Config Block
+- Run the standards compliance pass using `skill: standards` as mandatory baseline for code/config changes:
+  - evaluate declarative flow
+  - evaluate immutable transforms
+  - evaluate maintainability boundaries
+  - evaluate hidden mutable state
 - Verify agentic executability from plan/todo artifacts when available:
   - access prerequisites are explicit
   - validation commands are explicit and reproducible
@@ -115,6 +122,19 @@ Protected artifacts:
 - If changes touch existing behavior and risk is medium/high: `Task git-history-analyzer(<target context>)`
 - If changes depend on framework/library behavior and version constraints: `Task framework-docs-researcher(<topic>)`
 
+### Phase 3.5: Independent Reviewer Pass (REQUIRED)
+
+Before final verdict, run an explicit independent pass and record:
+
+- `review_independence_mode: independent|degraded`
+- `independence_evidence`: what independent pass ran
+- `skipped_passes`: what was skipped and why
+
+Mode rules:
+
+- `independent` (default): run a distinct fresh-context reviewer pass (separate reviewer/agent perspective from the main synthesis).
+- `degraded`: only when independent reviewer tooling/path is unavailable. Must include explicit disclosure that confidence is reduced and why fallback was used.
+
 Then perform the main review synthesis across:
 
 - change summary (surface area, high-risk files)
@@ -124,17 +144,30 @@ Then perform the main review synthesis across:
 - risk and failure modes
 - operational considerations (monitoring, rollback)
 - readability/maintainability
+- standards compliance using `skill: standards` (MUST/MUST NOT baseline)
 
 ### Phase 4: Synthesis + Verdict
 
 Provide:
 
 - Review recommendation: `pass | pass-with-notes | fail`
+- `review_independence_mode: independent|degraded`
+- `verdict_confidence: normal|degraded` (use `degraded` only when `review_independence_mode=degraded`)
+- `standards_compliance: pass|pass-with-notes|fail`
+  - `fail`: one or more standards MUST violations (blocking)
+  - `pass-with-notes`: no MUST violations, but SHOULD-level maintainability concerns
+  - `pass`: no material standards violations
 - Top risks (1–5 bullets)
 - Findings list:
   - severity (`critical | high | medium | low`)
   - evidence (file references or commands/output)
   - recommended action (concise)
+  - standards classification:
+    - standards `MUST` violations => blocking finding and review recommendation `fail`
+    - standards `SHOULD` violations => non-blocking finding and review recommendation `pass-with-notes`
+- Independence evidence summary:
+  - what independent pass ran
+  - what was skipped and why
 - What ran vs skipped (selected agents/passes)
 - Validation coverage summary:
   - tests: pass|fail|not-run

package/src/.agents/commands/workflow/triage.md

@@ -12,6 +12,8 @@ Turn todo items into a prioritized executable queue.
 This command does not implement fixes. It approves and organizes work so `/workflow:work` can execute without ambiguity.
 Output of this command is the only executable queue for `/workflow:work`.
 
+Contract precedence: if this command conflicts with other workflow docs, follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then this command.
+
 ## Inputs
 
 - Default: triage all active todos under `todos/` (`pending` + `ready`)

package/src/.agents/commands/workflow/work.md

@@ -13,6 +13,8 @@ Execute a work plan efficiently while maintaining quality and finishing features
 
 This command takes a plan file and executes it systematically. The focus is on completing the work while understanding requirements quickly, following existing patterns, and maintaining quality throughout.
 
+Contract precedence: if this command conflicts with other workflow docs, follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then this command.
+
 Non-goals (unless explicitly requested):
 
 - Creating commits
@@ -89,22 +91,7 @@ The input must be a plan file path.
    - Prefer `test_command` and optional `test_fast_command` from `AGENTS.md`.
    - If missing, ask once for the repo's test command and suggest adding it to `AGENTS.md`.
 
-1.6. **Agentic Access + Validation Preflight (HARD GATE)**
-
-   Contract checksum (MUST all be true before implementation):
-
-   - triage completed for this plan
-   - isolation gate recorded (`worktree_decision`, context, `gate_status: passed`)
-   - blocking spikes execute before dependent build todos
-
-   Before any implementation commands:
-
-   - Verify each `ready` todo has an executable Agentic Execution Contract:
-     - access preconditions are explicit
-     - validation path is explicit (commands/routes/checks)
-     - evidence expectations are explicit
-     - quality gate commands are explicit or marked for ask-once fallback
-   - If a todo lacks this contract, move it to `pending` for triage before coding.
+1.6. **Run-Scoped Quality Gate Fallback Setup (PREP STEP)**
 
    Ask-once fallback policy for missing lint/typecheck config:
 
@@ -113,6 +100,8 @@ The input must be a plan file path.
    - Continue only when provided commands run successfully.
    - If commands are not provided or fail, do not mark related todos complete.
 
+   Note: full execution preflight (triage + contract checks + isolation checks) runs after todo creation/triage in Step 3.5.
+
 1.75. **Resolve Plan Scope Contract (REQUIRED)**
 
    Before any environment setup or implementation, resolve the plan's scope contract:
@@ -132,11 +121,15 @@ The input must be a plan file path.
    - `migration`: identify migration verification + rollback checks before executing todos.
    - `full_remediation`: complete all known gaps in the scoped area before completion.
 
-2. **Setup Environment (HARD GATE)**
+2. **Setup Environment (HARD GATE - WORKTREE FIRST)**
 
    Determine how to isolate the work for this plan.
 
-   No implementation commands or code edits may run before this gate passes.
+   This gate MUST run immediately after Step 1.75.
+
+   No file writes, implementation commands, test/lint/typecheck commands, or dependency-install commands may run before this gate passes.
+
+   Allowed before gate: read-only inspection only (e.g., `ls`, `rg`, `cat`, `git status`, `git branch`).
 
    Default: use a worktree. Opt-out requires explicit user confirmation.
 
@@ -154,6 +147,8 @@ The input must be a plan file path.
 
    If Yes: ask for the new branch name (e.g., `feat/<slug>`, `fix/<slug>`).
 
+   If the user does not explicitly choose "No", proceed with "Yes" by default.
+
    3) If worktree is chosen, run:
 
    ```bash
@@ -231,6 +226,23 @@ The input must be a plan file path.
    - Do not proceed to Phase 2 until triage completes and execution order is explicit.
    - If triage leaves no unblocked `ready` todos, stop and report pending/deferred/blocked items.
 
+3.5. **Execution Preflight (HARD GATE before Phase 2)**
+
+   Contract checksum (MUST all be true before implementation):
+
+   - triage completed for this plan
+   - isolation gate recorded (`worktree_decision`, execution context, `gate_status: passed`)
+   - blocking spikes execute before dependent build todos
+
+   Before any implementation commands:
+
+   - Verify each `ready` todo has an executable Agentic Execution Contract:
+     - access preconditions are explicit
+     - validation path is explicit (commands/routes/checks)
+     - evidence expectations are explicit
+     - quality gate commands are explicit or marked for ask-once fallback
+   - If a todo lacks this contract, move it to `pending` for triage before coding.
+
 ### Phase 2: Execute
 
 1. **Task Execution Loop**
@@ -382,7 +394,7 @@ The input must be a plan file path.
    - The plan should reference similar code - read those files first
    - Match naming conventions exactly
    - Reuse existing components where possible
-   - Follow project coding standards (see AGENTS.md)
+   - Load and follow `skill: standards` as the mandatory baseline for declarative, immutable, maintainable implementation quality
    - When in doubt, grep for similar implementations
 
  3. **Test Continuously**
@@ -431,19 +443,40 @@ The input must be a plan file path.
    - If `test_command` is not configured, ask once for the project's test command and suggest adding it to `AGENTS.md`.
    - If `lint_command` or `typecheck_command` is not configured, ask once for run-provided commands and use them for this run.
 
-2. **Consider Reviewer Agents** (Optional)
+2. **Prepare Review Handoff (REQUIRED for code/config changes)**
+
+   If this run changed code or configuration, prepare an explicit `/workflow:review current` handoff summary:
+
+   - files changed
+   - validations run and outcomes
+   - known risks or unresolved notes
+
+   Docs-only runs may skip this handoff using the docs-only review exemption.
+
+3. **Standards Compliance Gate (REQUIRED for code/config changes)**
 
-   Use for complex, risky, or large changes.
+   For code/config changes, standards compliance is a hard gate before todo completion:
 
-   If this repo defines preferred review agents in `AGENTS.md`, follow that.
+   - Use `skill: standards` as the source of truth.
+   - This gate cannot run until the isolation/worktree gate is passed and recorded (`gate_status: passed`).
+   - Record standards evidence in todo Work Log using the standards evidence format:
+     - declarative flow
+     - immutable transforms
+     - maintainability boundaries
+     - hidden mutable state check
+   - If any mandatory standards line fails:
+     - do not rename todo to `*-complete-*.md`
+     - move todo back to `pending`
+     - add `tags: [blocker]`
+     - record blocking rationale + remediation steps in Work Log
 
-   If not configured, skip specialist reviewers by default.
+   Docs-only runs: mark this gate `not_applicable` and continue.
 
-3. **Final Validation**
+4. **Final Validation**
    - All todo files created for this plan are marked complete
    - All tests pass
    - Linting/typechecking/formatting checks pass (configured or run-provided via ask-once fallback)
-   - Code follows existing patterns
+   - Code follows existing patterns and passes the standards compliance gate
    - UI validation completed (if applicable)
    - No console errors or warnings
    - Scope contract satisfied:
@@ -451,21 +484,26 @@ The input must be a plan file path.
      - `migration`: migration verification and rollback checks are documented as passing
      - `full_remediation`: scoped remediation goals are complete per `completion_expectation`
 
-4. **Update Plan Status**
+5. **Update Plan Status**
 
    If the input document has YAML frontmatter with a `status` field, update it to `completed`:
    ```
    status: active  →  status: completed
    ```
 
-5. **Notify User**
+6. **Notify User**
      - Summarize what was completed
      - Note any follow-up work needed
      - Suggest next steps if applicable
 
-   Risk-based recommendation:
+   Completion policy:
 
-   - If the plan fidelity is `high` or confidence is `low`, recommend running `/workflow:review current` before considering the work complete.
+   - If this run changed code or configuration, report status as:
+     - `implementation_complete: true`
+     - `workflow_complete: false (pending /workflow:review current)`
+   - If this run is docs-only (no code/config changes), report status as:
+     - `implementation_complete: true`
+     - `workflow_complete: true (docs-only review exemption)`
 
 Stop here by default.
 
@@ -475,11 +513,11 @@ If the user wants to ship (commits/PR/screenshots), handle that as a separate ex
 
 ## Key Principles
 
-### Start Fast, Execute Faster
+### Execute with Deterministic Gates
 
-- Get clarification once at the start, then execute
-- Don't wait for perfect understanding - ask questions and move
-- The goal is to **finish the feature**, not create perfect process
+- Resolve unclear requirements early, then execute decisively
+- Keep hard gates explicit and non-skippable
+- Optimize for correct, verifiable completion
 
 ### The Plan is Your Guide
 
@@ -498,7 +536,7 @@ If the user wants to ship (commits/PR/screenshots), handle that as a separate ex
 - Follow existing patterns
 - Write tests for new code
 - Run linting/typechecking/formatting as configured in `AGENTS.md` (or run-provided via ask-once fallback)
-- Use reviewer agents for complex/risky changes only
+- For code/config changes, require `/workflow:review current` before declaring workflow completion
 
 ### Ship Complete Features
 
@@ -521,25 +559,23 @@ Before marking work complete, verify:
 - [ ] For `partial_fix`, unresolved work is captured as `pending/deferred` todos
 - [ ] If shipping is requested, capture any required artifacts (screenshots, release notes) per repo conventions
 
-## When to Use Reviewer Agents
+## Review Completion Gate
 
-**Don't use by default.** Use reviewer agents only when:
+For code/config changes, completion of `/workflow:work` is implementation-complete only. Workflow completion requires `/workflow:review current`.
 
-- Large refactor affecting many files (10+)
-- Security-sensitive changes (authentication, permissions, data access)
-- Performance-critical code paths
-- Complex algorithms or business logic
-- User explicitly requests thorough review
+Docs-only exception:
 
-For most features: tests + linting + following patterns is sufficient.
+- If no code/config files changed, `/workflow:work` may close as workflow-complete without `/workflow:review`.
+- When taking this exemption, explicitly state "docs-only review exemption" in the final summary.
 
 ## Common Pitfalls to Avoid
 
 - **Analysis paralysis** - Don't overthink, read the plan and execute
 - **Skipping clarifying questions** - Ask now, not after building wrong thing
 - **Skipping the worktree hard gate** - No implementation before Step 2 gate passes
+- **Starting writes before isolation gate** - no file writes or run commands before Step 2
 - **Ignoring plan references** - The plan has links for a reason
 - **Testing at the end** - Test continuously or suffer later
 - **Forgetting todo updates** - Update todo files and plan checkboxes or lose track of progress
 - **80% done syndrome** - Finish the feature, don't move on early
-- **Over-reviewing simple changes** - Save reviewer agents for complex work
+- **Skipping required review on code/config changes** - workflow completion requires `/workflow:review current`

package/src/.agents/skills/standards/SKILL.md

@@ -5,6 +5,43 @@ description: General coding practices, implementation styles, and patterns for t
 
 # Altai Code Standards
 
+## Mandatory Baseline (Declarative, Immutable, Maintainable)
+
+These rules are mandatory for code/config implementation work. They are pass/fail gates, not advisory guidance.
+
+### MUST
+
+- **MUST keep orchestration declarative** in containers/controllers: describe state transitions and event flow explicitly instead of imperative step-by-step control logic.
+- **MUST use immutable transforms** for domain and controller data operations (`input -> output`), returning new values instead of mutating existing objects/arrays.
+- **MUST keep domain logic in pure entity functions** (no side effects, no hidden mutable module state, no IO in entity transforms/predicates).
+- **MUST keep maintainability boundaries clear**:
+  - containers wire/select/send and avoid business rules
+  - controllers manage state transitions and delegate reusable logic to entities
+  - presentation components remain UI-focused
+- **MUST keep branching complexity controlled** with early exits and extracted helpers when conditional logic grows.
+
+### MUST NOT
+
+- **MUST NOT implement mutation-heavy imperative handlers** that modify shared state in-place across multiple steps.
+- **MUST NOT use hidden mutable accumulators** (`let` variables mutated through control flow) when a pure transform is feasible.
+- **MUST NOT mix business decision logic into containers/presentation** when it belongs in domain entities/controllers.
+- **MUST NOT allow branching sprawl** in controllers/containers (deep nesting, chained `else-if`, or nested ternaries for workflow logic).
+- **MUST NOT complete code/config work without standards evidence** recorded in work/review outputs.
+
+### Required Evidence Format (Work and Review)
+
+Use this format when reporting standards compliance in execution or review evidence:
+
+```markdown
+standards_compliance:
+- declarative_flow: pass|fail (evidence: file:line)
+- immutable_transforms: pass|fail (evidence: file:line)
+- maintainability_boundaries: pass|fail (evidence: file:line)
+- hidden_mutable_state: pass|fail (evidence: file:line)
+```
+
+If any mandatory line is `fail`, code/config work is not complete.
+
 ## Core Principles
 
 1. **Simplicity over cleverness** - Prefer straightforward solutions

package/src/AGENTS.md

@@ -44,6 +44,15 @@ This workspace currently implements `brainstorm`, `plan`, `triage`, `work`, `rev
 
 Use the canonical command names (`/workflow:plan`, `/workflow:work`, `/workflow:review`, etc.). This template does not ship aliases.
 
+## Contract Precedence
+
+If workflow documents conflict, resolve them in this order:
+
+1. `docs/principles/workflow-baseline-principles.md`
+2. This file (`src/AGENTS.md`) non-negotiables and repo config
+3. Workflow command specs (`src/.agents/commands/workflow/*.md`)
+4. Skill docs (`src/.agents/skills/*/SKILL.md`)
+
 ## Non-negotiables (Structure Integrity)
 
 - **Commands are the public API.** Keep `/workflow:*` command docs stable; add capability via skills/agents, not new command variants.
@@ -56,11 +65,13 @@ Use the canonical command names (`/workflow:plan`, `/workflow:work`, `/workflow:
 - **Triage before execution is mandatory.** `/workflow:work` must not execute todos until a `/workflow:triage` pass has prioritized the queue and validated dependencies/ready state for the current plan.
 - **Spike governance is explicit and ordered.** Risky plans must evaluate spike need, spike candidates must declare initial priority/dependencies/unblocks/timebox/deliverable, triage confirms those assumptions, and `/workflow:work` executes blocking spikes before dependent build todos.
 - **Agentic access/testability is mandatory in planning.** Every plan must include an executable access + validation contract so work/review can run deterministically.
+- **Independent review is required for code/config changes.** `/workflow:review` must emit `review_independence_mode: independent|degraded`, plus independence evidence and skipped-pass disclosure.
+- **Standards baseline is mandatory for code/config changes.** `/workflow:work` and `/workflow:review` must apply `skill: standards` as a hard gate for declarative flow, immutable transforms, and maintainability boundaries.
 - **Todo completion requires evidence.** A todo may move to `complete` only after success criteria evidence and quality gate evidence are recorded in Work Log.
 - **Blockers change todo state immediately.** Blocked work must move from `ready` back to `pending` with `tags: [blocker]` and an options+recommendation decision record.
 - **Quality gates are enforced with ask-once fallback.** If `lint_command` or `typecheck_command` is missing, ask once per run and continue only when commands are provided and pass.
 - **Skills are invoked only by trigger.** `document-review` only when user selects "Review and refine" (or explicit request); guardrail skills (PII/financial/audit/data) only when the feature touches that domain.
-- **No new files/directories by default** beyond `docs/plans/...` for planning output.
+- **No ad-hoc artifacts outside canonical outputs** (`docs/plans`, `todos`, `docs/solutions`, `docs/metrics`) unless explicitly requested.
 - **Plan file is the artifact.** Post-generation options are actions on the artifact; they do not change the workflow shape.
 - **Tighten over expand.** Resolve ambiguity, standardize naming, enforce sections—avoid adding new process steps unless they reduce rework.