npm package: @jnyross/code-factory
Description: Bootstrap new repos from the Code Factory template.
Latest version: 1.3.2

# Code Factory Template

Code Factory is a repo control-plane for autonomous coding + deterministic review.

This template implements the full pattern:
- one machine-readable contract
- risk-policy gate before expensive CI fanout
- current-head SHA review discipline
- current-head review score gate (5/5 policy)
- 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
- safe auto-merge enablement for eligible PRs
- incident -> harness-gap loop with weekly metrics

## Contract (single source of truth)
All control-plane policy lives in `ARCHITECTURE.yaml` under `control_plane`:
- `riskTierRules`
- `mergePolicy`
- `docsDriftRules`
- `reviewAgent`
- `remediationAgent`
- `browserEvidence`
- `harnessGapLoop`
- `branchProtection`

## Workflow Order
`Control Plane` workflow (`.github/workflows/preflight.yml`) runs jobs in this order:
1. `risk-policy-gate`
2. fanout: `CI Pipeline`, `harness-smoke`, and conditional `Browser Evidence` (only when UI-sensitive paths changed)
3. `risk-policy-finalize`

For `high` tier changes, the gate auto-applies the PR label `high-risk`.

**Greptile** runs as the code review agent via GitHub App. Install the Greptile app and configure `greptile.json` in the repo root. The policy gate uses Greptile's check run directly (`useCheckConclusionOnly: true`).

`greptile-event-handler` workflow (`.github/workflows/greptile-event-handler.yml`) triggers on Greptile check completion: remediation (on failure) and auto-resolve of bot-only threads (on success).

`Auto Merge` workflow (`.github/workflows/auto-merge-agent-prs.yml`) enables GitHub auto-merge for same-repo, non-draft PRs unless the PR has label `no-automerge`.

## SHA Discipline and Reruns
`scripts/control-plane/risk-policy-gate.mjs` enforces:
- review check must be for current PR head SHA
- stale review state is rejected
- actionable findings in review summary comment fail the gate
- review score policy can require machine-readable current-head score (for example 5/5) by tier
- canonical rerun request comment is deduped by marker + `sha:<head>`
- docs-drift checks are targeted to contract-interface paths (`docsDriftRules.requireDocsForPaths`), not all control-plane internals

`control_plane.reviewAgent.scorePolicy` enables deterministic review score gating:
- set `enabled: true`
- configure `requiredScore` / `requiredScale` (for example `5/5`)
- choose tiers with `applyToTiers`
- enforce missing-score behavior with `failIfScoreMissing`
- allow explicit audited bypass with `overrideLabel` (for example `override-5of5`)

## Browser Evidence
For UI-sensitive paths, `Browser Evidence` requires a valid manifest:
- path: `harness/browser-evidence/manifest.json`
- freshness window and required flows defined in `ARCHITECTURE.yaml`

Capture uses Playwright to take real screenshots of required flows. If no `BROWSER_EVIDENCE_BASE_URL` is set, the capture script builds and serves the flowchart app locally.

Generate/update evidence manifest:
```bash
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
- runs weekly metrics (`npm run harness:weekly-metrics`)

## Local Command Set
```bash
npm run typecheck
npm run lint
npm test
npm run build:ci --if-present
npm run harness:legal-chat:smoke
npm run harness:ui:pre-pr
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
npm run control-plane:bootstrap-repo-settings -- owner/repo
```

In this template, `typecheck`, `lint`, and `test` delegate to the `flowchart` subproject.

## Greptile Setup
`code-factory` now attempts to enable the new repository in the Greptile GitHub App installation immediately after repo creation.

1. Install the [Greptile GitHub App](https://github.com/apps/greptile) for your account/org.
2. Create repos with `code-factory` (default behavior auto-enables Greptile access).
3. Ensure `greptile.json` exists in the repo root (this template includes a default).
4. Set `statusCheck: true` in `greptile.json` so the policy gate can enforce the Greptile check.
5. The contract uses `checkName: "Greptile Review"` and `useCheckConclusionOnly: true` (check conclusion is authoritative).

Notes:
- Auto-enable requires your `gh` auth user to have permission to add repos to the app installation.
- To skip this step for one run, pass `--no-greptile`.
- To target a non-default app slug, pass `--greptile-app-slug <slug>` (default: `greptile`).

## Branch Protection
Merge blocking is enforced via GitHub branch protection requiring `risk-policy-finalize`.

- `code-factory` applies this automatically when it creates the GitHub repo (default behavior).
- For repos created from GitHub template UI, run:

```bash
node scripts/control-plane/apply-branch-protection.mjs owner/repo
```

Repository settings that make safe auto-merge practical are also bootstrapped:
- enable auto-merge
- enable squash merges
- delete merged branches

For repos created from GitHub template UI, run:
```bash
node scripts/control-plane/bootstrap-repo-settings.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_CODEX_PROFILE`, `REMEDIATION_CLAUDE_MODEL`, `REMEDIATION_OPENCODE_MODEL`, `REMEDIATION_VALIDATE_CMD`, `REMEDIATION_AGENT_CMD` (required for `custom` engine)

When enabled, failed Greptile checks trigger deterministic in-branch remediation:
1. verify current PR head matches event SHA (skip if stale)
2. read review context (Greptile comments or summary)
3. run local CLI agent (`codex`/`claude`/`opencode`/custom)
4. run validation command
5. commit + push fix to same PR branch

## Agent Loop Files
- `ARCHITECTURE.yaml`
- `AGENTS.md`
- `prd.json`
- `progress.txt` (auto-created by `ralph.sh` on first run)

## Tool Rule Files
- `.cursorrules`
- `CLAUDE.md`
- `.agent/rules/CodeFactory.md`
- `prompt_template.txt`
- `chatgpt_architecture_prd_prompt.txt`
- `chatgpt_prd_format_prompt.txt`

## CLI Install
```bash
npm install -g @jnyross/code-factory
```
Or see [npm package](https://www.npmjs.com/package/@jnyross/code-factory).

## Create a New Project
Default (local scaffold + create/push GitHub repo):
```bash
code-factory my-next-app ~/Projects
```

Local only (opt out of GitHub creation):
```bash
code-factory my-next-app ~/Projects --no-github
```

Examples:
```bash
code-factory my-next-app --owner my-org --repo my-org/my-next-app --public
```

Compatibility alias:
- `new-project` points to the same CLI command as `code-factory`.

## Ralph Runner
`ralph.sh` supports engines:
- `codex` (default)
- `claude`
- `opencode` (uses your OpenCode default unless `OPENCODE_MODEL` is set)
- `custom`

And supports runner modes:
- `--mode pr` (default): task execution is PR/control-plane driven.
- `--mode local`: preserves the legacy local-only loop behavior.

Before task execution, `ralph.sh` 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)

### PR mode loop (enforced order)
For each incomplete task in `prd.json`, PR mode runs:
1. create/switch `task/<id>-<slug>`
2. run coding agent
3. run deterministic local checks with fixed env:
   - `TZ=UTC`
   - `LC_ALL=C`
   - `CI=true`
   - `CODE_FACTORY_DETERMINISTIC_SEED=<fixed>`
   - commands: `npm run typecheck && npm run lint && npm test`
4. commit (only if changed), push branch
5. create or reuse open PR for the branch
6. capture + verify browser evidence (required for UI-sensitive changes)
7. wait for required checks + review-agent state on **current head SHA only**
8. if actionable findings exist: run remediation loop, push, rerun gates
9. only then mark task complete in `prd.json` and append `progress.txt`

If any gate is missing, failing, stale, or inconclusive, completion is blocked.

### Completion artifact
Each task produces a hard artifact:

`artifacts/completion/<TASK_ID>.json`

The artifact includes:
- task metadata (`task_id`, branch, PR, `head_sha`)
- UTC timestamps
- command exit codes
- acceptance-criteria evidence
- `final_status` (`complete` or `failed`)
- fail-closed failure reasons

Task completion is only allowed when artifact `final_status` is `complete`.

### Defaults
- `RUN_MODE=pr`
- `SPEC_REPAIR_ENABLED=true`
- `SPEC_REPAIR_MAX_RETRIES=3`

Deterministic completion contract:
- checks run with fixed env: `TZ=UTC`, `LC_ALL=C`, `CI=true`
- task completion artifact is written to `artifacts/completion/<TASK_ID>.json`
- artifact includes task/head metadata, command results, acceptance evidence, and final status
- tasks are marked complete only after all mode-specific gates pass

Examples:
```bash
./ralph.sh --once --mode pr
./ralph.sh --once --mode local
AGENT_ENGINE=claude ./ralph.sh --once --mode pr
AGENT_ENGINE=opencode ./ralph.sh --once --mode pr
```

## Ralph PR Mode Runbook
Per open task, PR mode executes this deterministic sequence:
1. create/switch to task branch
2. run selected local agent
3. run local preflight (`typecheck`, `lint`, `test`) under fixed env
4. commit and push branch
5. create/update PR
6. run control-plane scripts against current PR head SHA:
   - `risk-policy-gate.mjs --mode preflight`
   - `review-agent.mjs`
   - `risk-policy-gate.mjs --mode finalize` (wait/retry for required checks)
7. if review/actionable findings are detected, run `remediation-loop.mjs`, push, and re-check
8. if `control_plane.taskAdvancementPolicy.requireMergedPrBeforeNextTask=true`, wait until PR is merged (or timeout/fail per policy)
9. only mark task complete after finalize gate + score policy + merge requirement are all satisfied

Useful knobs:
- `BASE_BRANCH` (default `main`)
- `TASK_BRANCH_PREFIX` (default `ralph/task`)
- `PR_CHECK_TIMEOUT_SECONDS` / `PR_CHECK_POLL_SECONDS`
- `PR_REMEDIATION_MAX_PASSES` (default `10`)
- `PR_DRY_RUN=true` or `--pr-dry-run` for dry-ish local smoke runs