claude-company 0.1.0

package/company/GIT.md

@@ -0,0 +1,119 @@
+# GIT.md - Worktrees, branches, commits, and integration
+
+How this company uses git. Every agent that touches the repository follows
+this page; the CEO enforces it at integration. The goal is that parallel
+teams cannot collide, every commit traces to a work order, and the repository
+tells the truth about what happened.
+
+## The model in one picture
+
+```text
+main                          integration branch. Protected: no direct push
+                              (hook-enforced), merges by the CEO only.
+  task/<slug>                 one branch per workstream, created WITH its
+                              worktree. Lives in .claude/worktrees/<slug>.
+    (developers)              work INSIDE the lead's worktree, on the
+                              disjoint directories their task orders name.
+```
+
+One workstream = one worktree = one branch = one accountable tech lead.
+
+## Worktrees
+
+Create (CEO does this at dispatch):
+
+```bash
+git worktree add .claude/worktrees/<task-slug> -b task/<task-slug>
+```
+
+- **Developers do not get their own worktrees.** A lead's developers share
+  the lead's worktree and are kept apart by directory ownership, which their
+  task orders name exactly. Separate worktrees per developer would multiply
+  dependency installs and stale build artifacts without adding isolation the
+  ownership map does not already give.
+- **One agent per directory, ever.** If two agents need the same directory,
+  the decomposition is wrong; fix the task orders, not the git layout.
+- **QA works in the same worktree read-only** and saves screenshots to
+  `company/evidence/<task-slug>/`, which is committed with the task: the
+  evidence bundle is part of the deliverable.
+- Never nest a worktree inside another worktree, and never run two leads in
+  one worktree.
+
+## Commits
+
+- **Conventional messages, scoped to the workstream:**
+  `feat(waitlist): add signup endpoint`, `fix(api): reject expired tokens`.
+  Subject line 72 characters or less, imperative mood.
+- **Reference the work order.** Every commit on a task branch carries a
+  trailer naming the brief: `Task: <task-slug>`. Cite requirement ids in the
+  body when a commit implements them (`Implements: FR-03, FR-04`).
+- **Stage explicit paths only.** Never `git add -A` or `git add .` from a
+  worktree: symlinked `node_modules` and stray artifacts get staged and can
+  destroy the real thing on checkout. Name the files you mean.
+- **Commit per coherent step**, not per session. A session must not end with
+  uncommitted work unless the report says so and why.
+
+## Sync discipline
+
+- **Rebase at session start.** An agent resuming work in an existing
+  worktree rebases onto main first: `git rebase main`. Same after the CEO
+  applies any change request to a frozen surface.
+- **Conflicts have meaning.** A conflict inside your owned directories is
+  yours to resolve now. A conflict that crosses an ownership boundary means
+  the ownership map is wrong: stop and surface it; do not resolve it by
+  judgment.
+
+## Integration (CEO only)
+
+Merge only after verification (gates rerun on the integrated result,
+ownership diff checked, evidence judged - see `ORCHESTRATOR.md`):
+
+```bash
+git merge --no-ff task/<task-slug>
+```
+
+- **Always `--no-ff`**: the merge commit is the audit record. Its message
+  carries the task slug, the gate summary, and what was verified:
+
+```text
+merge task/waitlist: signup + admin view
+
+Verified: gates green on integrated main, ownership diff clean,
+QA evidence judged against acceptance criteria.
+Task: waitlist
+```
+
+- **Dependency order**: the API side merges before the UI that calls it;
+  within a program wave, providers before consumers.
+- **After every merge**: rerun the gates on main and stamp, then clean up.
+
+## Cleanup
+
+After a task integrates (or is abandoned):
+
+```bash
+git worktree remove .claude/worktrees/<task-slug>
+git branch -d task/<task-slug>
+git worktree prune
+```
+
+- Use `-d`, not `-D`. A branch that will not delete cleanly holds unmerged
+  work: investigate before forcing, because a "failed" agent may have
+  finished on disk without reporting.
+- **Session-start hygiene (CEO):** `git worktree list` and compare against
+  RESUME.md's in-flight table. A worktree nobody claims is either unreported
+  finished work (recover it) or an abandoned task (record the abandonment in
+  STATUS, then remove).
+
+## Hazards (learned the hard way)
+
+- `git add -A` in a worktree with symlinked `node_modules` can stage the
+  symlink and destroy the real directory. Explicit paths only.
+- A dead agent's worktree may contain completed work; a blind respawn
+  double-writes. Read the worktree's `git log` first.
+- A worktree's green gate stamp proves that worktree only. Stale artifacts
+  in worktrees mask contract drift; the integrated-main stamp is the one
+  that counts.
+- Pushing is owner territory: no agent pushes to main/master (hook-blocked).
+  Remote pushes of task branches happen only if the owner has asked for
+  remote backups or PR-based review.

package/company/IDEATION.md

@@ -0,0 +1,102 @@
+# IDEATION.md - How this company thinks before it builds
+
+Great builds die in the first five minutes, when the first workable idea gets
+mistaken for the best one. This playbook is how the company generates and
+selects ideas - for products, features, and architectures - at a
+production-grade bar.
+
+Two standing doctrines:
+
+1. **Diverge before you converge.** Never spec, design, or build the first
+   idea that works. Generate a real option space (the patterns below), then
+   converge with explicit criteria. The road not taken is recorded in the
+   options memo so the client can see it and veto the choice.
+2. **Autonomous posture.** Ideation never interviews the client. The company
+   runs the patterns itself, converges to a recommendation, and delivers an
+   options memo (`company/templates/OPTIONS-TEMPLATE.md`) with veto rights.
+   The only exceptions are the standing owner-escalation topics (money,
+   business policy), which land as decisions in the memo, not questions
+   mid-flow.
+
+## The patterns (pick by goal, use at least three categories per divergence)
+
+**Goal: quantity - fill the option space fast (8-15 directions)**
+
+1. **Perspective multiplication.** Generate ideas as N distinct stakeholders
+   would see the problem: the daily power user, the first-time user, the
+   admin, the attacker, the support engineer, the CFO, the competitor. Each
+   perspective must produce at least one idea the others would not.
+2. **Feature decomposition (SCAMPER).** Take the current or obvious solution
+   and systematically Substitute, Combine, Adapt, Modify/Magnify, Put to
+   other uses, Eliminate, Reverse each major attribute. Eliminate is the
+   most underused: what if this feature simply did not exist - what would
+   users do, and is THAT the product?
+
+**Goal: depth - refine promising directions**
+
+3. **Constraint variation.** Re-solve the same problem under artificial
+   constraints, one at a time: 10x less budget, zero new dependencies, must
+   ship in a day, must work offline, one-tenth the UI. Constraints expose
+   which parts of a design are load-bearing and which are habit.
+4. **Chain refinement.** Take the strongest idea and run three explicit
+   passes: strip it to its irreducible core; find the weakest assumption and
+   redesign without it; then add back only what earns its place.
+
+**Goal: breakthrough - escape the local maximum**
+
+5. **Inversion.** State the goal, then design for the opposite: "how would we
+   guarantee users churn / data corrupts / the team ships slowly" - then read
+   the anti-design as a checklist of what the real design must prevent. The
+   negative space usually contains at least one requirement nobody listed.
+6. **Extreme scaling.** Redesign as if usage were 100x, then as if it were
+   1/100th (a single user who pays 100x). The 100x version surfaces the
+   architecture; the 1/100th version surfaces the actual value.
+7. **Analogical transfer.** Name three domains that solved a structurally
+   similar problem (logistics, gaming, banking, biology) and port their
+   mechanism, not their surface. Say the mapping out loud: "X is to us what
+   the dispatch board is to trucking."
+
+**Goal: differentiation - win against alternatives**
+
+8. **Competitive positioning matrix.** List the real alternatives (including
+   "do nothing" and spreadsheets), score them on the two axes clients
+   actually feel, and design for the empty quadrant. An idea that lands in
+   an occupied quadrant needs a 10x edge or a different quadrant.
+
+**Goal: customer-centric - features that matter**
+
+9. **Journey friction walk.** Walk the primary persona's end-to-end journey
+   step by step; at each step ask what they feel, what they wait for, what
+   they re-enter, what they screenshot to send someone. Every friction point
+   is a feature candidate ranked by frequency x pain.
+10. **Assumption challenge.** List the premises the request smuggles in
+    ("users want a dashboard", "this needs accounts"), then generate one
+    idea per premise that drops it. Half of production-grade simplicity is
+    a premise someone refused.
+
+## Output discipline (applies to every divergence)
+
+- Ideas are NUMBERED, in a table: `# | Idea | Reasoning | Production risks |
+  Trade-offs`. Reasoning is mandatory - an idea without a why is a slogan.
+- Convergence uses explicit, written criteria (client value, production
+  risk, cost to build, cost to operate, reversibility) - never vibes.
+- Production-grade filter before any idea reaches the memo: how does it
+  fail, how is it observed, what does it cost at 10x, can it be rolled back,
+  what does it force on future modules?
+- The memo records winners AND the strongest rejected option with the reason
+  it lost. If the strongest rejected option keeps winning arguments later,
+  the convergence was wrong - reopen it.
+
+## Who runs what
+
+- **product-manager**: divergence is mandatory before any spec (8-15
+  directions, at least 3 pattern categories); the spec carries an "options
+  considered" section.
+- **architect**: the solutioning gate - 2-3 scored architecture options
+  before any program build; the memo shows the scoring.
+- **ideation-strategist**: deep divergence on demand. For big engagements
+  the CEO spawns 2-3 strategists in parallel with different assigned lenses
+  and synthesizes their outputs into one memo.
+- **CEO**: classifies fuzzy or new-idea requests as `ideation` engagements,
+  synthesizes memos, owns the recommendation, and proceeds on it unless the
+  client vetoes.

package/company/LOOPS.md

@@ -0,0 +1,108 @@
+# LOOPS.md - Standing operation (loop engineering) [EXPERIMENTAL]
+
+**Experimental and strictly opt-in.** Nothing in this page runs unless the
+owner explicitly invokes `/autopilot` or schedules it themselves. No agent,
+including the CEO, starts a loop on its own initiative. The intended moment
+is the end phase of a product: the main build shipped interactively, and the
+loop burns down the backlog, polish items, and worry ledger in bounded,
+reviewable ticks.
+
+Prompting the company task by task is mode one. Mode two is the loop: the
+company runs on a heartbeat, discovers its own work, executes it through the
+normal pipeline, and surfaces only what needs the owner. This page is the
+doctrine for running unattended without becoming a runaway process.
+
+The premise (loop engineering, 2026): the human stops being the person who
+prompts the agent and becomes the person who designs the system that
+prompts, checks, and reruns the agent. claude-company already carries the
+load-bearing parts of that system - worktrees, maker/checker separation,
+persistent state, skills, hooks. The loop adds the heartbeat and the
+discipline around it.
+
+## The iron rules (before any loop runs)
+
+1. **No loop without a mechanical verifier.** Every iteration ends at the
+   gates and the evidence protocol, same as interactive work. A loop that
+   trusts its own narration is a mistake generator with a scheduler.
+2. **No loop without a cap.** Every loop declares, before it starts: max
+   engagements per run, max attempts per failure, and when it must stop and
+   surface. A loop with no ceiling spends until the tokens run out.
+3. **The owner's attention is the scarce resource.** The loop optimizes for
+   review throughput: small integrated deliveries with evidence bundles,
+   never a week of unreviewed output. Unread loop output is comprehension
+   debt - the company ships code nobody understands.
+4. **Loops accelerate understood work; they never replace thinking.** Fuzzy
+   or novel asks still route through ideation and specs. The loop is for
+   the backlog, the red gates, and the worry ledger - not for inventing
+   strategy unattended.
+
+## The heartbeat (one iteration)
+
+Each tick of the standing loop is one pass of the operating loop, bounded:
+
+```mermaid
+flowchart LR
+    A([tick]) --> B["Triage: gates on main,
+    WORRIES P0/P1, open CRs,
+    in-flight tasks, BACKLOG"]
+    B --> C{anything
+    actionable?}
+    C -->|no| D([sleep - long interval])
+    C -->|owner-only items| E([surface + sleep])
+    C -->|yes| F["Pick ONE: unblock beats
+    new work; red beats green;
+    P0 worry beats backlog"]
+    F --> G[Run it through the
+    normal pipeline]
+    G --> H[Verify + integrate
+    + record state]
+    H --> I{caps hit? owner
+    decision needed?}
+    I -->|yes| E
+    I -->|no| A
+```
+
+Triage order is fixed: red gates on main first, then in-flight work to
+unblock or integrate, then P0/P1 worries, then open CRs, then the top of
+`company/state/BACKLOG.md`. New backlog work starts only when nothing above
+it needs attention.
+
+## Stop-and-surface conditions (every loop honors all of these)
+
+| Condition | Why the loop must not push through |
+|---|---|
+| An owner-escalation item (money, deploy, scope, policy) | Those decisions are never made unattended |
+| The same gate red twice on the same cause | Design problem, not an agent problem |
+| Per-run engagement cap reached | Review throughput is the bottleneck, not generation |
+| Two consecutive ticks with nothing actionable | An idle loop burning tokens is waste; lengthen the interval or stop |
+| Any hook block the loop cannot self-serve per the recipe | The enforcement layer outranks the loop |
+
+## Running it
+
+The `/autopilot` skill is the payload; Claude Code's native loop primitives
+are the scheduler. Pick by attendance:
+
+| Mode | How | Fits |
+|---|---|---|
+| Attended burst | `/autopilot` once | Clear a backlog while you watch the reports land |
+| Semi-attended | `/loop /autopilot` (self-paced) | You are around; the company self-paces its ticks and you can interrupt |
+| Unattended | `/schedule` a cloud routine running `/autopilot` | Overnight/weekend triage and small deliveries, capped tight |
+
+Unattended runs get the tightest caps: fewer engagements per run, quick and
+feature class only (never program, never hotfix), and every delivery waits
+merged-but-unreported until the owner reads the evidence.
+
+## State the loop lives on
+
+The loop is stateless between ticks by design; everything it knows is in
+files (the model forgets, the repo remembers):
+
+- `company/state/BACKLOG.md` - the discovered-work queue. The owner drops
+  wishes here in one line each; triage, audits, and QA findings append
+  candidates. The loop pulls from the top; nothing enters the pipeline
+  without becoming a classified engagement first.
+- `company/state/RESUME.md` - what the last tick finished and what the next
+  should do first.
+- `company/state/STATUS.md`, `WORRIES.md`, `DECISIONS.md`, `adherence.log` -
+  the same truth the interactive company keeps; the loop reads them at every
+  tick and writes them after every action.

package/company/METHOD.md

@@ -0,0 +1,151 @@
+# METHOD.md - How this company works
+
+claude-company turns a repository into a small software company run by AI agents
+under one accountable orchestrator (the CEO, your main Claude session). This file
+is the method. Every agent reads it once and holds to it. The CEO's private
+runbook is `ORCHESTRATOR.md` (repo root); subagents never read that file.
+
+The thesis, in one line: **gates are enforced, not narrated.** Process that lives
+only in prose gets skipped under pressure. Here, the load-bearing rules are
+backed by hooks and scripts that mechanically block; the prose explains why.
+
+## The five mechanisms
+
+1. **Canon before code (and spec before feature).** Features become spec-ready
+   before any build. A spec (see `company/templates/SPEC-TEMPLATE.md`) carries
+   stable requirement IDs (FR/BR/OQ) and a build-readiness section. Agents
+   implement against the spec's derived brief and never resolve an ambiguity by
+   personal judgment - they implement the brief's stated fallback and tag the
+   site (`// OQ-XX-NN assumption`), or file a change request. Autonomy comes
+   from removing decisions from agents, not from making agents guess well.
+
+2. **Ownership boundaries are hard.** Every dispatched agent owns an explicit
+   set of directories named in its brief; everything else is read-only to it.
+   Workstreams are directory-disjoint by construction, and building agents work
+   in isolated git worktrees (one worktree, one branch, one accountable lead
+   per workstream - mechanics in `company/GIT.md`). Nobody fixes things they
+   notice outside their scope - they report them.
+
+3. **Frozen surfaces change only by change request.** The registry is
+   `company/frozen-surfaces.json` (enforced by a PreToolUse hook). An agent that
+   needs a frozen surface changed STOPS and files a CR in
+   `company/change-requests/`; it never patches locally. The CR queue is the
+   integration risk made visible. The bureaucracy is the point.
+
+4. **Gates are the definition of done.** "It works locally" is not a state this
+   company recognizes. The gate suite (`company/run-gates.sh`, defined per
+   project in `company/gates.config`, contract in `company/GATES.md`) decides,
+   never an agent's self-report. Every gate is blocking, none is ever waived,
+   and commits are hook-blocked while gates are red or stale.
+
+5. **Verify, never trust - and never let the producer grade itself.** The agent
+   that built something never judges it done. Developers report with evidence;
+   tech leads re-check against the brief; QA drives the running product and
+   captures screenshots but does not judge them; leads and the CEO judge. The
+   CEO re-runs gates, diff-checks ownership, and spot-reads before integrating.
+
+## The client posture
+
+The owner is a CLIENT of this company, not its process operator. Frictionless
+on the outside, hard-gated on the inside:
+
+- **All paperwork is self-generated.** Specs, briefs, task state, gate
+  config - agents produce every artifact. The templates in
+  `company/templates/` are for agents; a client is never asked to fill,
+  read, or approve one.
+- **Hooks teach the machine, not the human.** When a hook blocks, its message
+  is a recipe the blocked agent follows to make itself compliant (write the
+  brief, set the task state, run the gates) - compliance is self-service,
+  enforcement stays mechanical.
+- **Defaults over questions.** Every decision that is not on the owner
+  escalation list gets an opinionated default, applied immediately and
+  recorded (DECISIONS.md, OQ fallbacks, STATUS notes) where the owner can
+  veto it later. Asking is the exception; the escalation list is the whole
+  list of exceptions.
+- **Interruptions are batched.** The client hears from the company twice per
+  engagement in the common case: owner decisions (batched, once) and
+  delivery (evidence bundle: what shipped, gate ladder, screenshots, what is
+  next). Process narration is noise.
+- **Uninitialized is not an error.** The orchestrator self-onboards on first
+  contact - audits, wires gates, applies frozen defaults - instead of sending
+  the client to a setup command.
+
+## The hierarchy
+
+```
+Owner (human)
+  CEO           - the main session. Dispatches, arbitrates CRs, verifies,
+                  integrates, reports upward. Codes only glue and small fixes.
+  Staff roles   - product-manager (Phase 0 specs), architect (boundaries,
+                  ownership map, wave plan), auditor (read-only pre-merge audit)
+  Tech leads    - one per workstream. Decompose the brief, spawn and manage
+                  their own developers, fill the gaps between developers' work,
+                  drive QA, run gates, report upward with evidence.
+  Developers    - build exactly what their task order says, inside owned
+                  directories, in a worktree.
+  QA engineers  - drive the built surface (Playwright), capture evidence
+                  screenshots: loaded / empty / error / after-action.
+```
+
+Depth is capped at two below the CEO by construction (CEO -> lead -> dev/QA).
+Deeper pyramids multiply handoff drift and token cost without adding judgment.
+
+Communication travels through typed artifacts, not conversation: spec -> brief ->
+report -> STATUS. A brief is sealed and self-contained; a report follows
+`company/templates/REPORT-TEMPLATE.md` and contains facts, not adjectives.
+
+## Ceremony scales with the task
+
+The CEO classifies every incoming request; nobody hand-picks ceremony:
+
+| Class | What | Path |
+|---|---|---|
+| `ideation` | The ask is ideas/direction, or too fuzzy to build without guessing | Brainstorm engagement per `company/IDEATION.md`: parallel strategists diverge, CEO converges, client gets an options memo; the winner reclassifies as quick/feature/program. |
+| `quick` | Small bug, copy change, config tweak | Brief only. One developer or the CEO itself. No Phase 0. Gates still gate. |
+| `feature` | New user-visible capability, or anything touching a frozen surface, an invariant, or money | Phase 0 spec -> spec-ready gate -> brief -> one tech lead + team -> QA evidence -> verify -> integrate |
+| `program` | Multi-workstream build (a v1, a big subsystem) | Architect produces ownership map + wave plan. Waves are merge barriers: a wave's exit criteria must be green on main before the next wave starts. One lead per workstream, parallel within a wave. |
+| `hotfix` | Production is on fire | Declared by the CEO in `company/state/active-task.json` (`"type": "hotfix"`). Hooks log the bypass instead of blocking. Retroactive spec/tests within a day. |
+
+## The context discipline
+
+Spec context and build context are kept apart deliberately:
+
+- The **spec** is rich and human-facing. The builder never reads it.
+- The **brief** (`company/templates/BRIEF-TEMPLATE.md`) is the lean execution
+  slice derived from the spec: mission, read-first list, owned directories,
+  invariants in play, frozen surfaces nearby, ordered scope, DoD, fallbacks,
+  out-of-scope. A vague brief is the main cause of a bad agent run.
+- Agents read: the project's `CLAUDE.md`, their brief, and what the brief's
+  "Read first" list cites. Nothing else is assumed.
+
+## State the company maintains
+
+All under `company/state/`, all owned by the CEO:
+
+| File | Job |
+|---|---|
+| `STATUS.md` | Current truth board. Red stays red until proven green. Never average a status. |
+| `RESUME.md` | Session handoff: done / running / next, plus the facts every spawn prompt needs. Read first on every session start. |
+| `WORRIES.md` | Terse ledger of suspected-but-unproven risks: `P (P0-P3) \| Worry \| What \| Logic`. A row graduates OUT when it becomes a CR, a STATUS risk, or a verified fix. |
+| `DECISIONS.md` | Owner escalations and their outcomes. |
+| `active-task.json` | The machine-readable pointer to the task in flight (read by hooks). |
+| `gates.status` | The stamped gate result (written only by the gate runner). |
+| `adherence.log` | Every hook block and bypass, one line each. Proof the system enforces. |
+
+## What is never decided below the owner
+
+1. Weakening any design invariant or frozen surface's guarantees.
+2. Money and billing behavior.
+3. Deploys, prod migrations, cutover. Merge is integration; deploy is a manual
+   owner step, never in any script or agent's tooling.
+4. Scope changes beyond a brief.
+5. A gate failing twice on the same cause after a respawn - that signals a
+   design problem, not an agent problem. Stop and surface.
+6. Business-policy open questions. Agents run on tagged fallbacks; the owner
+   answers the question.
+
+## Writing discipline
+
+All writing in this repository stays hook-clean: straight quotes, ' - ' rather
+than em dashes, three dots rather than the ellipsis character, and no stock AI
+filler phrases. The `no_slop` PreToolUse hook enforces this mechanically.

package/company/frozen-surfaces.json

@@ -0,0 +1,17 @@
+{
+  "$comment": "Frozen-surface registry. Read by .claude/hooks/guard_frozen.py, which blocks Edit/Write to matching paths. Patterns are fnmatch globs tested against the project-relative path and the basename. Populate 'surfaces' for YOUR project during /company-init or /onboard (the architect proposes them; the owner approves). Changes to frozen surfaces go through company/change-requests/, applied by the CEO in a dedicated gated PR. The 'always' list is claude-company's own baseline and applies to every project.",
+  "version": 1,
+  "surfaces": [],
+  "always": [
+    ".env",
+    ".env.*",
+    "*.lock",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "poetry.lock",
+    "Cargo.lock",
+    "company/state/gates.status",
+    "company/state/adherence.log"
+  ]
+}

package/company/gates.config

@@ -0,0 +1,5 @@
+{"$comment": "Define your project's mechanical gates. Every gate is blocking. See company/GATES.md.",
+ "gates": [
+   {"name": "tests", "command": "echo 'CONFIGURE ME: replace with your test command' && exit 1", "blocking": true},
+   {"name": "lint", "command": "echo 'CONFIGURE ME' && exit 1", "blocking": true}
+ ]}

package/company/run-gates.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# run-gates.sh - the claude-company gate runner.
+# Reads company/gates.config, runs each gate command from the project root,
+# prints a gate ladder, then stamps results via .claude/hooks/gate_stamp.py.
+# Every gate is blocking: exits non-zero if any gate fails.
+set -euo pipefail
+
+# --- resolve project root -------------------------------------------------
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+  PROJECT_ROOT="$CLAUDE_PROJECT_DIR"
+elif PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"; then
+  :
+else
+  PROJECT_ROOT="$(pwd)"
+fi
+
+CONFIG="$PROJECT_ROOT/company/gates.config"
+STAMPER="$PROJECT_ROOT/.claude/hooks/gate_stamp.py"
+
+# --- colors ---------------------------------------------------------------
+if [ -t 1 ]; then
+  C_RED=$'\033[31m'; C_GREEN=$'\033[32m'; C_YELLOW=$'\033[33m'; C_BOLD=$'\033[1m'; C_RESET=$'\033[0m'
+else
+  C_RED=''; C_GREEN=''; C_YELLOW=''; C_BOLD=''; C_RESET=''
+fi
+
+warn() { printf '%s\n' "${C_YELLOW}warning:${C_RESET} $*" >&2; }
+
+# --- no config / empty config ---------------------------------------------
+if [ ! -f "$CONFIG" ]; then
+  echo "no gates configured - see company/GATES.md"
+  exit 0
+fi
+
+# --- parse config into "name<TAB>base64(command)" lines -------------------
+# base64-encode the command so arbitrary shell text survives the line format.
+GATE_LINES="$(python3 - "$CONFIG" <<'PY'
+import base64, json, sys
+try:
+    with open(sys.argv[1]) as f:
+        data = json.load(f)
+except Exception as e:
+    sys.stderr.write("failed to parse gates.config: %s\n" % e)
+    sys.exit(3)
+gates = data.get("gates") or []
+for g in gates:
+    name = str(g.get("name", "")).strip()
+    cmd = g.get("command", "")
+    if not name or not cmd:
+        continue
+    enc = base64.b64encode(cmd.encode("utf-8")).decode("ascii")
+    sys.stdout.write("%s\t%s\n" % (name, enc))
+PY
+)"
+
+if [ -z "$GATE_LINES" ]; then
+  echo "no gates configured - see company/GATES.md"
+  exit 0
+fi
+
+# --- run each gate --------------------------------------------------------
+echo "${C_BOLD}Running gates from ${PROJECT_ROOT}${C_RESET}"
+echo
+
+NAMES=""
+OKS=""
+DETAILS_FILE="$(mktemp -t rungates.XXXXXX)"
+LADDER_FILE="$(mktemp -t rungates.XXXXXX)"
+trap 'rm -f "$DETAILS_FILE" "$LADDER_FILE"' EXIT
+
+ANY_FAIL=0
+
+# Read tab-separated lines without a subshell (so vars persist in bash 3.2).
+while IFS=$'\t' read -r NAME ENC; do
+  [ -n "$NAME" ] || continue
+  CMD="$(printf '%s' "$ENC" | base64 --decode 2>/dev/null || printf '%s' "$ENC" | base64 -D)"
+
+  echo "${C_BOLD}-> gate: ${NAME}${C_RESET}"
+  START=$(date +%s)
+  OUT_FILE="$(mktemp -t rungates.XXXXXX)"
+  # Run from the project root. Do not let a failing gate abort the runner.
+  set +e
+  ( cd "$PROJECT_ROOT" && eval "$CMD" ) >"$OUT_FILE" 2>&1
+  RC=$?
+  set -e
+  END=$(date +%s)
+  DUR=$((END - START))
+
+  # Echo the gate output so the user sees it, then keep the last line as detail.
+  cat "$OUT_FILE"
+  LAST_LINE="$(awk 'NF{last=$0} END{print last}' "$OUT_FILE")"
+  rm -f "$OUT_FILE"
+
+  if [ "$RC" -eq 0 ]; then
+    STATUS="PASS"; OK="true"
+  else
+    STATUS="FAIL"; OK="false"; ANY_FAIL=1
+  fi
+
+  # Record for the ladder and for stamping (base64 the detail for safe transport).
+  DENC="$(printf '%s' "$LAST_LINE" | base64 | tr -d '\n')"
+  printf '%s\t%s\t%s\n' "$NAME" "$OK" "$DENC" >>"$DETAILS_FILE"
+  printf '%s\t%s\t%ss\n' "$NAME" "$STATUS" "$DUR" >>"$LADDER_FILE"
+  echo
+done <<EOF
+$GATE_LINES
+EOF
+
+# --- print the gate ladder ------------------------------------------------
+echo "${C_BOLD}Gate ladder${C_RESET}"
+printf '%-24s %-6s %s\n' "GATE" "RESULT" "TIME"
+printf '%-24s %-6s %s\n' "------------------------" "------" "------"
+while IFS=$'\t' read -r NAME STATUS DUR; do
+  [ -n "$NAME" ] || continue
+  if [ "$STATUS" = "PASS" ]; then COLOR="$C_GREEN"; else COLOR="$C_RED"; fi
+  printf '%-24s %s%-6s%s %s\n' "$NAME" "$COLOR" "$STATUS" "$C_RESET" "$DUR"
+done <"$LADDER_FILE"
+echo
+
+# --- stamp results --------------------------------------------------------
+RESULTS_JSON="$(python3 - "$DETAILS_FILE" <<'PY'
+import base64, json, sys
+gates = []
+with open(sys.argv[1]) as f:
+    for line in f:
+        line = line.rstrip("\n")
+        if not line:
+            continue
+        parts = line.split("\t")
+        if len(parts) < 3:
+            continue
+        name, ok, denc = parts[0], parts[1], parts[2]
+        try:
+            detail = base64.b64decode(denc.encode("ascii")).decode("utf-8", "replace")
+        except Exception:
+            detail = ""
+        gates.append({"name": name, "ok": ok == "true", "detail": detail})
+sys.stdout.write(json.dumps({"gates": gates}))
+PY
+)"
+
+if [ -f "$STAMPER" ]; then
+  if python3 "$STAMPER" --results "$RESULTS_JSON"; then
+    :
+  else
+    warn "gate_stamp.py exited non-zero; gate results were reported above but may not be stamped"
+  fi
+else
+  warn "gate stamper not found at $STAMPER - skipping stamp (results reported above)"
+fi
+
+# --- final exit code ------------------------------------------------------
+if [ "$ANY_FAIL" -ne 0 ]; then
+  echo "${C_RED}${C_BOLD}gates FAILED${C_RESET}"
+  exit 1
+fi
+echo "${C_GREEN}${C_BOLD}all gates passed${C_RESET}"
+exit 0

package/company/state/DECISIONS.md

@@ -0,0 +1,9 @@
+# DECISIONS - owner escalations and outcomes
+
+_Questions only the owner may answer (money, invariants, deploys, scope,
+business policy), with what was decided and when. Agents run on tagged
+fallbacks until a row lands here._
+
+| # | Date | Question | Decision | Affects |
+|---|---|---|---|---|
+| - | - | - | - | - |