@jnyross/code-factory 1.1.1 → 1.1.4

package/README.md

@@ -7,6 +7,7 @@ This template implements the full pattern:
 - risk-policy gate before expensive CI fanout
 - current-head SHA review discipline
 - canonical rerun comment dedupe
+- optional deterministic remediation agent loop
 - bot-only thread auto-resolve after clean rerun
 - browser evidence verification for UI/user-flow changes
 - incident -> harness-gap loop with weekly metrics
@@ -17,8 +18,10 @@ All control-plane policy lives in `ARCHITECTURE.yaml` under `control_plane`:
 - `mergePolicy`
 - `docsDriftRules`
 - `reviewAgent`
+- `remediationAgent`
 - `browserEvidence`
 - `harnessGapLoop`
+- `branchProtection`
 
 ## Workflow Order
 `Control Plane` workflow (`.github/workflows/preflight.yml`) runs jobs in this order:
@@ -30,6 +33,8 @@ For `high` tier changes, the gate auto-applies the PR label `high-risk`.
 
 `Code Review Agent` workflow (`.github/workflows/auto-review.yml`) runs in parallel and is enforced by SHA-aware policy checks.
 
+`remediation-agent` workflow (`.github/workflows/remediation-agent.yml`) can be enabled for in-branch automated fixes after actionable review findings.
+
 ## SHA Discipline and Reruns
 `scripts/control-plane/risk-policy-gate.mjs` enforces:
 - review check must be for current PR head SHA
@@ -48,6 +53,8 @@ npm run harness:ui:capture-browser-evidence
 npm run harness:ui:verify-browser-evidence
 ```
 
+In CI, capture + verify are both run in `Browser Evidence` job.
+
 ## Harness Gap Loop
 `harness-gap-loop` workflow:
 - creates a `harness-gap` issue when a `production-regression` issue appears
@@ -64,8 +71,35 @@ npm run harness:ui:capture-browser-evidence
 npm run harness:ui:verify-browser-evidence
 npm run harness:risk-tier
 npm run harness:weekly-metrics
+npm run spec:normalize
+npm run spec:validate
+npm run spec:check
+```
+
+## Branch Protection
+Merge blocking is enforced via GitHub branch protection requiring `risk-policy-finalize`.
+
+- `code-factory --github` now applies this automatically.
+- For repos created from GitHub template UI, run:
+
+```bash
+node scripts/control-plane/apply-branch-protection.mjs owner/repo
 ```
 
+Note: GitHub may require a paid plan (or public repo) for private-repo branch protection.
+
+## Remediation Agent
+Optional, disabled by default:
+- add a self-hosted runner for the repo
+- set repository variable `ENABLE_REMEDIATION=true`
+- optional variables: `REMEDIATION_ENGINE`, `REMEDIATION_CODEX_MODEL`, `REMEDIATION_VALIDATE_CMD`
+
+When enabled, failed review-agent runs can trigger deterministic in-branch remediation:
+1. read current-head actionable findings
+2. run local CLI agent (`codex`/`claude`/`opencode`/custom)
+3. run validation command
+4. commit + push fix to same PR branch
+
 ## Agent Loop Files
 - `ARCHITECTURE.yaml`
 - `AGENTS.md`
@@ -111,6 +145,15 @@ Compatibility alias:
 - `opencode` (default model `minimax-coding-plan/MiniMax-M2.5`)
 - `custom`
 
+Before task execution, `ralph.sh` now runs a spec gate:
+1. normalize `ARCHITECTURE.yaml` + `prd.json` into canonical format
+2. validate both files strictly
+3. if still invalid, auto-repair with your selected local engine and retry (bounded)
+
+Defaults:
+- `SPEC_REPAIR_ENABLED=true`
+- `SPEC_REPAIR_MAX_RETRIES=3`
+
 Examples:
 ```bash
 ./ralph.sh --once

package/bin/code-factory.mjs

@@ -21,6 +21,8 @@ Options:
   --owner <owner>       GitHub owner/org for --github (defaults to gh auth user)
   --repo <name|owner/name>
                         GitHub repo name override (default: slugified project name)
+  --no-branch-protection
+                        Skip automatic main branch protection setup for --github
   --template-url <url>  Override template repository URL for this run
   -h, --help            Show help
 
@@ -61,6 +63,7 @@ function parseArgs(rawArgs) {
     visibility: "private",
     owner: null,
     repo: null,
+    branchProtection: true,
     templateUrl: DEFAULT_TEMPLATE_URL
   };
 
@@ -107,6 +110,11 @@ function parseArgs(rawArgs) {
       continue;
     }
 
+    if (arg === "--no-branch-protection") {
+      options.branchProtection = false;
+      continue;
+    }
+
     if (arg === "-h" || arg === "--help") {
       usage(0);
     }
@@ -149,6 +157,43 @@ function deriveGitHubRepo(projectName, options) {
   return { owner, repo };
 }
 
+function configureBranchProtection({ owner, repo }) {
+  const requiredChecks = ["risk-policy-finalize"];
+  const payload = {
+    required_status_checks: {
+      strict: true,
+      contexts: requiredChecks
+    },
+    enforce_admins: false,
+    required_pull_request_reviews: {
+      dismiss_stale_reviews: true,
+      require_code_owner_reviews: false,
+      required_approving_review_count: 1
+    },
+    restrictions: null,
+    required_conversation_resolution: true,
+    allow_force_pushes: false,
+    allow_deletions: false
+  };
+
+  execFileSync(
+    "gh",
+    [
+      "api",
+      "--method",
+      "PUT",
+      `repos/${owner}/${repo}/branches/main/protection`,
+      "--input",
+      "-"
+    ],
+    {
+      stdio: ["pipe", "inherit", "inherit"],
+      input: JSON.stringify(payload),
+      encoding: "utf8"
+    }
+  );
+}
+
 function createProject(projectName, destinationDir, options) {
   const targetPath = resolve(destinationDir, projectName);
 
@@ -161,6 +206,7 @@ function createProject(projectName, destinationDir, options) {
   run("git", ["-C", targetPath, "init", "-q"]);
   run("git", ["-C", targetPath, "add", "."]);
   run("git", ["-C", targetPath, "commit", "-q", "-m", "Initial commit from Code Factory template"]);
+  run("git", ["-C", targetPath, "branch", "-M", "main"]);
 
   if (options.github) {
     const { owner, repo } = deriveGitHubRepo(projectName, options);
@@ -169,6 +215,18 @@ function createProject(projectName, destinationDir, options) {
 
     run("gh", ["repo", "create", fullRepo, visibilityFlag, "--source", targetPath, "--remote", "origin", "--push"]);
     console.log(`GitHub repo created: https://github.com/${fullRepo}`);
+
+    if (options.branchProtection) {
+      try {
+        configureBranchProtection({ owner, repo });
+        console.log("Main branch protection applied (required check: risk-policy-finalize).");
+      } catch (error) {
+        console.warn(
+          "Warning: failed to apply branch protection automatically. " +
+            "Run scripts/control-plane/apply-branch-protection.mjs in the new repo."
+        );
+      }
+    }
   }
 
   console.log("Your new Code Factory project is ready!");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jnyross/code-factory",
-  "version": "1.1.1",
+  "version": "1.1.4",
   "description": "Bootstrap new repos from the Code Factory template.",
   "type": "module",
   "license": "MIT",
@@ -25,12 +25,16 @@
     "new-project": "bin/code-factory.mjs"
   },
   "scripts": {
+    "control-plane:apply-branch-protection": "node scripts/control-plane/apply-branch-protection.mjs",
     "harness:risk-tier": "node scripts/control-plane/risk-tier.mjs",
     "harness:legal-chat:smoke": "node scripts/control-plane/harness-smoke.mjs",
     "harness:ui:capture-browser-evidence": "node scripts/control-plane/capture-browser-evidence.mjs",
     "harness:ui:verify-browser-evidence": "node scripts/control-plane/verify-browser-evidence.mjs",
     "harness:ui:pre-pr": "npm run harness:ui:capture-browser-evidence && npm run harness:ui:verify-browser-evidence",
-    "harness:weekly-metrics": "node scripts/control-plane/weekly-metrics.mjs"
+    "harness:weekly-metrics": "node scripts/control-plane/weekly-metrics.mjs",
+    "spec:normalize": "node scripts/control-plane/normalize-specs.mjs --write",
+    "spec:validate": "node scripts/control-plane/validate-specs.mjs",
+    "spec:check": "npm run spec:normalize && npm run spec:validate"
   },
   "files": [
     "bin",