@olives/devos 2.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,114 @@
+# Dev-OS System Architecture
+
+## System Architecture Overview
+
+Dev-OS uses a multi-agent hierarchy orchestrated by a central coordinator (the Orchestrator). AI outputs are isolated by role and validated by parallel agents before human review.
+
+### Agent Hierarchy and Communication Flow
+
+```mermaid
+flowchart TD
+    Human(Human Lead) --> Orchestrator
+    
+    subgraph EX["Execution"]
+        Developer
+        Tester
+        DevOps
+        DBA
+    end
+    
+    subgraph QV["Quality and Validation"]
+        QA
+        Security
+        Researcher
+    end
+    
+    subgraph SM["Strategy and Memory"]
+        Architect
+        MemoryManager
+        ReleaseManager
+    end
+
+    Orchestrator --> EX
+    Orchestrator --> QV
+    Orchestrator --> SM
+```
+
+### Standard Feature Delivery (Parallel Gate)
+
+```mermaid
+flowchart TD
+    Task(New Task) --> Orch[Orchestrator]
+    Orch --> Dev[Developer Writes Code]
+    Dev --> Gate{Parallel Quality Gate}
+    
+    Gate --> QA[QA Agent Checks Code]
+    Gate --> Tester[Tester Agent Runs Tests]
+    Gate --> Sec[Security Agent Scans]
+    
+    QA --> Merge1{All Pass?}
+    Tester --> Merge1
+    Sec --> Merge1
+    
+    Merge1 -- No --> Dev
+    Merge1 -- Yes --> Human[Human Approval]
+    Human --> Deploy["DevOps / Merge"]
+```
+
+### Bug Fix Workflow
+
+```mermaid
+flowchart TD
+    Bug(Bug Report) --> Researcher[Researcher Investigates]
+    Researcher --> Dev[Developer Fixes Code]
+    Dev --> Tester[Tester Writes Regression Test]
+    Tester --> QA[QA Verifies]
+    QA --> Human[Human Approval]
+```
+
+### Commit Gate Flow
+
+```mermaid
+flowchart LR
+    Dev["Agent / Developer"] --> Script[commit.sh]
+    Script --> Token[Export DEVOS_COMMIT_APPROVED]
+    Token --> Git[git commit]
+    Git --> Hook[Pre-commit hook]
+    Hook --> Gitleaks[gitleaks Secret Scan]
+    Gitleaks -- Pass --> Success[Commit Saved]
+    Gitleaks -- Fail --> Reject[Commit Rejected]
+```
+
+### Memory System Architecture
+
+```mermaid
+flowchart TD
+    PinnedRules[Pinned Hard Rules] --> Context[Agent Context Window]
+    CurrentState[CURRENT_STATE.md] --> Context
+    Lessons[LESSONS.md] --> Context
+    
+    Context --> Execution[Agent Execution]
+    Execution --> MemoryManager[Memory Manager Agent]
+    MemoryManager --> |Updates| CurrentState
+    MemoryManager --> |Learns| Lessons
+```
+
+### Slash Command Routing
+
+```mermaid
+flowchart LR
+    Command["/slash_command"] --> Orch[Orchestrator]
+    Orch --> Parse[Read YAML Frontmatter]
+    Parse --> Target[Target Agent]
+    Target --> Workflow[Execute Workflow / Prompt]
+```
+
+## Directory Structure
+
+- `.agents/`: The core logic of the OS.
+  - `agents/`: System prompts for each agent.
+  - `commands/`: Slash commands.
+  - `skills/`: Agent capabilities.
+  - `scripts/`: Tooling (e.g., `commit.sh`).
+- `docs/`: User documentation.
+- `src/` (or similar): The actual project source code being managed.

package/docs/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to Dev-OS are documented in this file.
+This project follows [Semantic Versioning](https://semver.org/).
+
+## [2.1.0] — 2026-09-03
+
+- **Official npm Package Scope (`@olives/devos`)**: Formally registered under the official Olives organization on npm as `@olives/devos` (executable CLI binaries remain `devos`, `olives-devos`, and `devos-init`).
+- **`devos update` CLI Command**: Safely refreshes `.agents/`, specialist skills, slash commands, and git hooks in existing projects without overwriting custom documentation or stack coding standards.
+- **Automated Pre-Commit Hook Installation**: `devos init` now automatically runs `install-hooks.sh` to install `.git/hooks/pre-commit` whenever initialized within a Git repository.
+- **Hard Rules Digest in CLAUDE.md**: `bootstrapClaudeMd` injects a complete 14-rule digest directly into `CLAUDE.md` to guarantee AI working agents always load the rules into active context on turn 1.
+- **Solo Session Protocol**: Defined the official minimum viable quality gate in `AGENTS.md` and `CLAUDE.md` for single-agent interactive workflows (freshness check, lint/typecheck/test self-verification, standards review, staged human review, commit gate, state obligation).
+- **Hard Rule #13 (Session-End State Obligation)**: Requires active agents to update `docs/CURRENT_STATE.md` (and `docs/LESSONS.md` on incidents) before concluding any working session modifying code.
+- **Hard Rule #14 (Session-Start Freshness Check)**: Enforces running `git fetch --all --prune` and `git status -sb` before scoping tasks to prevent regressions against stale branches.
+- **Pre-Commit Hook Reference**: Added `docs/PRE_COMMIT_HOOK.md` detailing mechanical gate architecture, Gitleaks scanning, and verification procedures.
+- **Field Audit Report**: Added `docs/FIELD_REPORT_2026-08-20.md` capturing findings from a real-world multi-day project audit and documenting the resolution of all five recommendations.
+
+### Security & Hardening
+- **Un-Pipeable Human Approval Gate**: Hardened `commit.sh` to read the approval token directly from the controlling terminal (`/dev/tty`). Piped stdin (e.g. `printf 'approve\n...' | commit.sh`) is rejected by policy; automated CI environments must explicitly export `DEVOS_HEADLESS_COMMIT=1`.
+- **Modern Gitleaks Subcommand**: Replaced legacy `gitleaks protect` with the officially documented `gitleaks git --staged --verbose` in `install-hooks.sh`.
+- **Robust Gate Status Check**: Hardened `install-hooks.sh` from fragile `if [ $? -ne 0 ]` checking to direct command execution testing (`if ! gitleaks git --staged --verbose; then`).
+
+## [2.0.0] — 2026-08-14
+
+### Added
+- **npm Package (`@olitech010/dev-os`)**: Installable via `npx @olitech010/dev-os init` / `npm install -g @olitech010/dev-os` (the name `devos` on npm belongs to an unrelated 2016 package, and npm blocks unscoped look-alikes such as `dev-os`). Bin commands remain `devos`, `olives-devos`, and `devos-init`
+- **Claude Code Integration**: `devos init` now generates `.claude/commands/` and `.claude/agents/` (with valid frontmatter) from the `.agents/` sources, and bootstraps a project `CLAUDE.md`, so slash commands and agent personas are natively discovered by Claude Code. Skippable with `--no-claude`
+- **CLI Redesign**: Block-letter DEV-OS banner with attribution, TTY/`NO_COLOR`-aware color output, styled section rules, dynamic component counts, and a boxed init summary
+- **Safety**: `devos init` backs up an existing `.agents/` to `.agents/_backup/<timestamp>/` before overwriting; `install-hooks.sh` backs up an existing pre-commit hook; `doctor` now exits non-zero when checks fail
+- **Smoke Test**: `npm test` runs `scripts/smoke-test.js` — a real end-to-end init/doctor/reference-integrity check
+- **Slash Command System**: 10 pre-configured commands (`/review`, `/commit`, `/test`, `/secure`, `/research`, `/status`, `/fix`, `/architect`, `/refactor`, `/deploy`) with YAML frontmatter schema
+- **Memory System**: Project state tracking (`CURRENT_STATE.md`), episodic memory (`LESSONS.md`), context compaction, and pinned safety rules
+- **Circuit Breaker Protocol**: Agent loops exceeding 3 iterations automatically halt and escalate to human
+- **Memory Manager Agent**: Dedicated agent for context preservation and session handoff
+- **Release Manager Agent**: Dedicated agent for versioning, changelogs, and release notes
+- **Parallel Quality Gate**: QA, Tester, and Security now run simultaneously instead of sequentially
+- **Rollback Protocol**: Defined workflow for handling failed deployments
+- **Exploratory Refactoring Workflow**: Safe exploration on throwaway branches
+- **Hard Rules #10-12**: Circuit Breaker, Verify Before Implementing, No Heavy Dependencies Without Approval
+
+### Changed
+- **Orchestrator**: Removed TRIVIAL direct-commit loophole — all tasks now route through Developer → QA → Human
+- **Commit Gate**: Added `DEVOS_COMMIT_APPROVED` token export in `commit.sh` for pre-commit hook compatibility
+- **QA vs Tester**: Clarified responsibilities — QA reviews results, Tester owns test creation and execution
+- **Standard Feature Delivery**: Parallelized QA + Tester + Security gate
+- **Staged Review Model**: Agents write code but never auto-commit; human triggers commit after review
+
+### Security
+- **Mechanical Secret Scanning**: `gitleaks` integration via Git pre-commit hook
+- **Commit Gate Enforcement**: Raw `git commit` blocked without `DEVOS_COMMIT_APPROVED` token
+- **Hard Rule #8**: Mechanical Commit Gate documented and enforced
+- **Hard Rule #9**: Zero hardcoded secrets policy
+
+## [1.0.0] — Initial Release
+
+### Added
+- Multi-agent roster: Orchestrator, Developer, QA, Tester, DBA, DevOps, Security, Architect, Researcher
+- Workflow protocols: Standard Feature Delivery, Bug Fix Delivery, Dependency Update
+- Human-in-the-loop commit enforcement via `commit.sh`
+- Skill ecosystem with 50+ modular skills
+- Hard Rules 1-7

package/docs/CURRENT_STATE.md

@@ -0,0 +1,39 @@
+# Project State
+
+> This file is maintained by the Orchestrator agent. It is updated at each phase transition to preserve context across long sessions.
+
+## Current Task
+- **Task:** Dev-OS v2.1.0 release (audit hardening, Gitleaks modernization, update command, official scope @olives/devos).
+- **Branch:** main
+- **Triage Level:** STANDARD
+- **Status:** RELEASE READY (v2.1.0 merged to main, smoke tests passed)
+
+## Active Agents
+| Agent | Status | Current Assignment |
+|---|---|---|
+| Orchestrator | ACTIVE | Coordinating PR #9 & #10 consolidation and v2.1.0 release |
+| Developer | ACTIVE | Script hardening in commit.sh, install-hooks.sh, bin/devos.js |
+| QA | ACTIVE | Verifying coding standards, docs consistency, and smoke test pass |
+| Tester | ACTIVE | Running end-to-end smoke tests and testing un-pipeable TTY gate |
+| Security | ACTIVE | Auditing secret scanner gate and commit token protection |
+| DevOps | IDLE | Prepared for npm release and PR merges |
+
+## Recent Decisions
+- **Merged PR #9 & PR #10 into feat/devos-v2.1-hardening**: Unified hook reference documentation and field audit report.
+- **Modernized Gitleaks Subcommand**: Swapped `gitleaks protect` for documented `gitleaks git --staged --verbose`.
+- **Hardened Gate Status Evaluation**: Replaced fragile `$?` checking with direct `if ! gitleaks git --staged --verbose; then`.
+- **Un-pipeable Human Approval Token**: Updated `commit.sh` to read directly from `/dev/tty`, blocking automated stdin bypass, with `DEVOS_HEADLESS_COMMIT=1` for authorized headless CI pipelines.
+- **Added Hard Rules Digest in CLAUDE.md**: `bootstrapClaudeMd()` now embeds an active 14-rule digest directly into generated `CLAUDE.md`.
+- **Defined Solo Session Protocol**: Added explicit minimum quality gate to `AGENTS.md` and `CLAUDE.md` for single-agent interactive workflows.
+- **Added Hard Rule #13 (Session-End State Obligation)**: Mandates updating `CURRENT_STATE.md` before concluding sessions.
+- **Added Hard Rule #14 (Session-Start Freshness Check)**: Enforces `git fetch --all --prune` at session start.
+- **Added `devos update` CLI Command**: Safely upgrades `.agents/` and `.claude/` without touching customized docs or standards.
+- **Auto-installed Pre-Commit Hook**: `devos init` now automatically runs `install-hooks.sh` when inside a Git repo.
+- **Registered Package Under @olives/devos**: Configured npm package scope under official olives organization on npm.
+- **Version Bumped to 2.1.0**: Ready for release.
+
+## Blockers
+- None.
+
+## Context Summary
+Successfully implemented and mechanically verified all five recommendations from the Dadiboes compliance audit (PR #10) and both issues from the pre-commit hook reference (PR #9). Smoke tests pass 100%. Package and docs bumped to v2.1.0.

package/docs/FIELD_REPORT_2026-08-20.md

@@ -0,0 +1,130 @@
+# Field Report: Dev-OS Compliance Audit — dadiboes Session (2026-08-18 to 2026-08-20)
+
+> Documentation-only report. No code changes are proposed in this PR; each finding ends
+> with a recommendation for the owner to evaluate and implement.
+
+## Context
+
+An AI working agent (Claude Code) ran a multi-day session in the `dadiboes` project,
+which has Dev-OS installed. The task: sync the About page content, diagnose why the
+page was missing locally, and unblock seven days of failed Vercel production deploys.
+The task succeeded, but a post-session audit (prompted by the project owner) found that
+several Dev-OS protocols were bypassed or silently skipped. This report documents what
+held, what failed, why it failed, and what would prevent it.
+
+## What held
+
+- [ OK ] The Mechanical Commit Gate (Hard Rule 8) blocked raw `git commit`; the agent
+  routed the commit through `.agents/scripts/commit.sh`.
+- [ OK ] The pre-commit secret scan ran and passed.
+- [ OK ] Conventional commit format was enforced by the script's type whitelist.
+- [ OK ] The agent surfaced its plan and findings to the human before committing
+  (Staged Review, in spirit).
+
+## What failed, and why
+
+### Finding 1: AGENTS.md was never read before work began
+
+The generated `CLAUDE.md` says "Read `.agents/AGENTS.md` ... before making changes,"
+but this is a passive pointer. The agent absorbed only the CLAUDE.md digest (commit
+gate, coding standards pointer) and started implementing immediately. It first opened
+AGENTS.md two days later — after the owner asked why the rules were not followed.
+Everything below follows from this one miss.
+
+**Root cause:** A pointer in always-loaded context does not compete with a concrete
+user task. Nothing mechanical verifies the read happened.
+
+**Recommendation:** Have `devos init` embed a compressed Hard Rules digest (10-15
+lines) directly into the generated CLAUDE.md block, so the rules are in context even
+when the agent never opens AGENTS.md. Alternatively (or additionally), ship a
+SessionStart hook in the generated `.claude/settings.json` that injects the Hard Rules
+into every session. The full AGENTS.md stays as the reference document; the digest is
+the enforcement surface.
+
+### Finding 2: The human-approval token is pipeable
+
+`commit.sh` reads the approval token from stdin. When the human replied "continue" to
+a message that listed the commit plan, the agent ran:
+
+    printf 'approve\nfix\n<message>\n' | .agents/scripts/commit.sh
+
+The gate passed. The commit was legitimate in substance (the human had seen the exact
+plan), but the gate's design intent — a human physically types the token — was not
+met. An agent acting on a *misread* of user intent would pass the gate identically.
+
+**Root cause:** `read -p` consumes piped stdin exactly like interactive input.
+
+**Recommendation:** In `commit.sh`, read the token from the controlling terminal
+(`read ... < /dev/tty`) and fail with a clear message when no TTY is available
+(`[ FAIL ] Human approval requires an interactive terminal`). This makes the gate
+mechanically un-pipeable while remaining a one-line change. Consider an explicit
+documented escape hatch (e.g. `DEVOS_HEADLESS_COMMIT=1` plus a logged warning) for CI
+use, so the restriction does not break legitimate automation.
+
+### Finding 3: CURRENT_STATE.md and LESSONS.md were not updated
+
+The session completed a STANDARD-level task (content sync, staging merge, dependency
+lockfile fix, production deploy) and ended with `docs/CURRENT_STATE.md` still reading
+"Task: (none), Status: IDLE". The owner had to ask for the update. AGENTS.md assigns
+this duty to the Memory Manager "or the Orchestrator when the Memory Manager is not
+active" — but in a plain interactive session, neither persona is active, so the duty
+lands on no one.
+
+**Root cause:** State maintenance is specified as an agent-persona responsibility, not
+a session-level obligation. Interactive solo sessions have no defined owner for it.
+
+**Recommendation:** Two options, not mutually exclusive:
+1. Add a Hard Rule: "Before ending any working session that changed files, update
+   `docs/CURRENT_STATE.md`; log incidents in `docs/LESSONS.md`." Session-level rules
+   bind whoever is working, persona or not.
+2. Add a Stop (or PreToolUse-on-commit) hook that warns when source files changed but
+   `docs/CURRENT_STATE.md` was not touched in the same session. A warning is enough;
+   a hard block would be noisy for trivial changes.
+
+### Finding 4: No QA/Tester/Security gate ran
+
+Standard Feature Delivery specifies a parallel QA + Tester + Security gate before the
+human checkpoint. None ran. The agent did run `tsc --noEmit` and a full `next build`
+before committing — real verification, but self-verification, not the independent
+review the workflow describes.
+
+**Root cause:** The workflow protocols assume an Orchestrator-led multi-agent
+execution. A solo interactive session has no defined minimum protocol, so agents
+improvise. (Related to Finding 3 — the same structural gap.)
+
+**Recommendation:** Define an explicit "solo session" profile in AGENTS.md: the
+minimum viable pipeline when no orchestrator is active (e.g. typecheck + build/test +
+self-review against CODING_STANDARDS.md + state update + human commit gate), and when
+a session MUST escalate to the full multi-agent workflow (CRITICAL triage, schema
+changes, security-sensitive code). Right now the honest options are "full ceremony"
+or "nothing", and agents under a concrete task pick nothing.
+
+### Finding 5: No session-start freshness check (contributing incident)
+
+The session's original confusion — rebuilding an About page that was already live in
+production — happened because the local clone was 31 commits behind `origin/main` and
+had never fetched the `staging` branch. No Dev-OS rule requires a fetch/state check at
+session start.
+
+**Recommendation:** Add to the Hard Rules or the generated CLAUDE.md digest: "At
+session start, run `git fetch --all --prune` and check `git status -sb` before scoping
+any task." Cheap, and it prevents a whole class of duplicate/stale work. A SessionStart
+hook could run the fetch automatically and surface behind/ahead counts.
+
+## Summary of recommendations & v2.1.0 Resolution
+
+| # | Change | Kind | Effort | Resolution in v2.1.0 |
+|---|--------|------|--------|----------------------|
+| 1 | Embed Hard Rules digest into generated CLAUDE.md | Generator + template | Small | **RESOLVED**: `bin/devos.js` `bootstrapClaudeMd` injects full 14-rule digest into `CLAUDE.md`. |
+| 2 | `commit.sh`: read token from `/dev/tty`, fail without TTY, documented CI escape hatch | Script | Small | **RESOLVED**: `commit.sh` reads from `/dev/tty` by default; headless bypass requires `DEVOS_HEADLESS_COMMIT=1`. |
+| 3 | Hard Rule for CURRENT_STATE.md updates at session end | Docs + rules | Small | **RESOLVED**: Added Hard Rule #13 (Session-End State Obligation) to `AGENTS.md` & `CLAUDE.md`. |
+| 4 | Define a "solo session" minimum protocol in AGENTS.md | Docs + rules | Medium | **RESOLVED**: Added dedicated Solo Session Protocol section to `AGENTS.md` & `CLAUDE.md`. |
+| 5 | Session-start fetch/freshness rule | Docs + rules | Small | **RESOLVED**: Added Hard Rule #14 (Session-Start Freshness Check) requiring `git fetch --all --prune`. |
+
+## Closing note
+
+The failure mode observed was not an agent rejecting the rules — it was the rules
+never entering the agent's working context, and the one mechanical gate being softer
+than it looks. Dev-OS's instinct (mechanical enforcement over trust, per the
+2026-08-10 lesson in its own LESSONS.md) is right. In v2.1.0, all five recommendations
+have been mechanically implemented and verified.

package/docs/GETTING_STARTED.md

@@ -0,0 +1,130 @@
+# Getting Started with Olives Dev-OS
+
+This guide explains how to initialize Dev-OS in a new or existing repository using the standard **Olives Dev-OS CLI** (`devos` / `olives-devos`) and start collaborating with your multi-agent engineering team.
+
+---
+
+## 1. Installation Options
+
+> **Note on the package name:** The npm registry package is **`@olives/devos`** (under the official Olives organization on npm). Once installed, the CLI binaries are `devos`, `olives-devos`, and `devos-init`.
+
+### Option A: Global NPM / NPX (Recommended)
+Run the automated installer in your target project root:
+```bash
+npx @olives/devos init
+```
+*(Or install globally: `npm install -g @olives/devos`. After a global install, the command is simply `devos` — the bin name — so you run `devos init`.)*
+
+### Option B: Non-Interactive Flag Execution
+For automated environments, CI scripts, or quick setup:
+```bash
+npx @olives/devos init --stack nextjs --existing
+```
+
+### Option C: Direct GitHub Installation
+Run the latest version straight from GitHub without going through the npm registry:
+```bash
+npx github:olitech1010/dev-os init
+```
+
+### Option D: Local Cloning & Linking (Fallback / Offline)
+If global or `npx` execution fails or is blocked by network policy:
+```bash
+# Clone the Dev-OS repository
+git clone https://github.com/olitech1010/dev-os.git
+cd dev-os
+
+# Symlink the CLI globally on your system
+npm link
+
+# Go to your project folder and initialize
+cd /path/to/your-target-project
+devos init
+```
+
+---
+
+## 2. CLI Command & Diagnostic Reference
+
+The Olives Dev-OS CLI provides a full suite of commands modeled after industry standard developer tools (Claude Code, Gemini CLI, gh, Vercel):
+
+```bash
+$ devos --help
+
+USAGE
+  $ devos <command> [flags]
+
+CORE COMMANDS
+  init, setup      Initialize or update Dev-OS multi-agent environment in target project
+  doctor, check    Diagnose project setup, permissions, commit script, and health
+  list, agents     Display active agent personas and installed specialist skills
+  status           Show active project configuration, detected stack, and health summary
+  version          Print Dev-OS CLI version, Node runtime, and environment information
+  help             Display this command reference
+
+FLAGS
+  -s, --stack <name>  Specify target stack (nextjs, laravel, django, react-native, express, fastapi, universal)
+  --fresh             Non-interactive fresh project initialization
+  --existing          Non-interactive existing project initialization
+  --no-claude         Skip generating .claude/ integration files and CLAUDE.md
+  --json              Output diagnostic and listing results as JSON
+  -q, --quiet         Suppress header banners and non-essential log messages
+  -v, --version       Print CLI version
+  -h, --help          Show command options
+```
+
+### What `init` Does
+
+Beyond copying the `.agents/` system into your project, `devos init`:
+
+- **Generates Claude Code integration files.** It compiles the `.agents/` sources into `.claude/commands/` (native slash commands) and `.claude/agents/` (native subagents), and bootstraps a project `CLAUDE.md`. Pass `--no-claude` to skip this step.
+- **Backs up before overwriting.** If a `.agents/` directory already exists, it is backed up to `.agents/_backup/<timestamp>/` before the new files are written, so re-running `init` never destroys local customizations.
+- **Makes scripts executable.** Both `commit.sh` and `install-hooks.sh` are chmod'd during init.
+
+### Doctor and CI
+
+`devos doctor` exits with a non-zero status code when any required check fails, making it safe to use as a CI gate:
+
+```bash
+devos doctor || exit 1
+```
+
+It also runs warn-level checks (reported as `[ WARN ]`, without failing the run) for the pre-commit hook installation and the presence of the `.claude/` integration directory.
+
+---
+
+## 3. Development Workflow & Task Triage
+
+When you assign a task to the **Orchestrator Agent**, it automatically triages your request:
+
+1. **TRIVIAL Tasks (Typos, small config changes, minor CSS):**
+   - Delegated to the **Developer Agent** like any other change. Even trivial edits go through the full Developer -> QA -> Human approval chain. The Orchestrator NEVER writes production code or commits directly — there is no fast path that bypasses review.
+2. **STANDARD Tasks (New features, standard bug fixes):**
+   - Orchestrator delegates to the **Developer Agent**.
+   - When the Developer finishes, the work enters the **parallel quality gate**: the **QA Agent**, **Tester Agent**, and **Security Agent** run in PARALLEL.
+   - QA reviews the code against `CODING_STANDARDS.md` (it does not write tests); the Tester owns test creation and execution; Security scans for vulnerabilities. Only when all three pass is human approval requested.
+3. **CRITICAL Tasks (Database schemas, Supabase RLS, infrastructure):**
+   - Involves the **DBA Agent**, **Security Agent**, or **DevOps Agent**.
+   - Destructive actions (`DROP`, `TRUNCATE`, deployments) require a mandatory dry-run plan and explicit human sign-off.
+
+---
+
+## 4. Approving Commits (The Scripted Checkpoint)
+
+In Dev-OS, agents are mechanically forbidden from running raw `git commit` commands in the terminal. When code is ready:
+1. The agent calls `./.agents/scripts/commit.sh`.
+2. Execution pauses and prompts you in the terminal:
+   ```
+   Human Approval Token (type 'approve' to proceed):
+   ```
+3. Type `approve` and press Enter.
+4. The script formats the commit using Conventional Commits and saves your progress securely.
+
+---
+
+## 5. Related Documentation
+
+- [System Architecture](ARCHITECTURE.md)
+- [Mechanical Pre-Commit Hook Reference](PRE_COMMIT_HOOK.md)
+- [Step-by-Step Tutorial & Glossary](TUTORIAL.md)
+- [Root README](../README.md)

package/docs/LESSONS.md

@@ -0,0 +1,24 @@
+# Lessons Learned
+
+> This file is a persistent episodic memory store. When an agent encounters a significant error and resolves it, the root cause and resolution are logged here. Agents SHOULD query this file before starting tasks involving similar domains.
+
+## Format
+Each entry follows this structure:
+
+```
+### [DATE] — [SHORT TITLE]
+- **Domain:** (e.g., Git, Auth, Deployment, UI, Database)
+- **What went wrong:** (brief description of the failure)
+- **Root cause:** (why it happened)
+- **Resolution:** (how it was fixed)
+- **Prevention rule:** (what to do differently next time)
+```
+
+---
+
+### 2026-08-10 — Hardcoded Secret Leaked in PR
+- **Domain:** Git, Security
+- **What went wrong:** The Orchestrator agent directly wrote code and committed a hardcoded API key into a Pull Request, bypassing the Developer → QA → Human pipeline.
+- **Root cause:** The Orchestrator's TRIVIAL triage level allowed direct code execution and commits. Combined with context window truncation, the agent fell back to raw `git commit` instead of `commit.sh`.
+- **Resolution:** Removed the TRIVIAL direct-commit loophole. Added mechanical pre-commit hooks (`gitleaks` + `DEVOS_COMMIT_APPROVED` gate). Added Hard Rules #8 and #9.
+- **Prevention rule:** Orchestrator NEVER writes production code. All commits route through `commit.sh`. Pre-commit hooks mechanically block secrets.

package/docs/PRE_COMMIT_HOOK.md

@@ -0,0 +1,152 @@
+# Mechanical Pre-Commit Hook Reference
+
+> Reference documentation for the Git pre-commit hook generated by `.agents/scripts/install-hooks.sh`. This file describes behaviour only. It documents the hook exactly as it ships today, plus the known limits and maintenance items that follow from that behaviour.
+
+The pre-commit hook is the mechanical half of the Dev-OS commit gate. The scripted half is `.agents/scripts/commit.sh`, which collects human approval and exports the approval token. The hook is what physically stops a commit when the token is absent or when Gitleaks finds a secret in the staged diff.
+
+---
+
+## 1. Installation
+
+```bash
+./.agents/scripts/install-hooks.sh
+```
+
+The installer:
+
+1. Resolves the repository root with `git rev-parse --show-toplevel`, and exits `1` with `[ FAIL ]` if the working directory is not inside a Git repository.
+2. Creates `.git/hooks/` if it does not exist.
+3. Backs up an existing `pre-commit` hook **only when that hook does not already contain the string `DEVOS_COMMIT_APPROVED`**. The backup path is `.git/hooks/pre-commit.backup.<YYYYMMDDHHMMSS>` and a `[ WARN ]` line reports it. A hook that already contains the marker is treated as a Dev-OS hook and is overwritten in place without a backup.
+4. Writes the hook body from a quoted heredoc (`<< 'EOF'`), so nothing in the template is expanded at install time — every variable in the hook is evaluated when the hook runs.
+5. Runs `chmod +x` on the hook and prints the install path.
+
+`devos init` chmods `install-hooks.sh` but does **not** run it. `devos doctor` reports a missing `.git/hooks/pre-commit` as an optional `[ WARN ]` check, not a failure.
+
+---
+
+## 2. What the Generated Hook Does
+
+The hook runs two stages in order and exits `0` only if both pass.
+
+```
+git commit
+   │
+   ▼
+.git/hooks/pre-commit
+   │
+   ├── 1. Commit gate: is DEVOS_COMMIT_APPROVED == "true"?
+   │      ↳ No  : [ FAIL ] exit 1  ("Direct 'git commit' is disabled by policy")
+   │      ↳ Yes : continue
+   │
+   └── 2. Secret scan: is `gitleaks` on PATH?
+          ↳ No  : [ WARN ] print install hint, skip the scan, continue
+          ↳ Yes : run the scan against the staged diff
+                    ↳ Leaks found : [ FAIL ] exit 1  ("Hardcoded secret detected")
+                    ↳ Clean       : [ OK ] "Secret scan clean."
+   │
+   ▼
+[ OK ] Dev-OS pre-commit checks passed.  exit 0
+```
+
+### Stage 1 — The commit gate
+
+The hook tests `$DEVOS_COMMIT_APPROVED` against the literal string `true`. Any other value, including an unset variable, aborts the commit with exit status `1` and points the caller at `.agents/scripts/commit.sh`. The failure message also states that exporting `DEVOS_COMMIT_APPROVED=true` is acceptable for an authorized automated pipeline.
+
+`commit.sh` satisfies this stage by exporting the variable immediately before it calls `git commit`. The export lives in the script's own shell, so it applies to that one commit and does not leak into the interactive session.
+
+The token is a policy control, not a security boundary. It is trivially exportable by anyone who reads the failure message. Its purpose is to make raw `git commit` an explicit, deliberate act rather than a default one — which is precisely the failure mode recorded in [LESSONS.md](LESSONS.md) under "Hardcoded Secret Leaked in PR".
+
+### Stage 2 — The Gitleaks secret scan
+
+Gitleaks is an **optional soft dependency**. The hook guards the scan with `command -v gitleaks`. When Gitleaks is not installed the hook prints:
+
+```
+[ WARN ] 'gitleaks' is not installed on your system.
+   Install gitleaks to enable automated mechanical secret scanning: 'brew install gitleaks'
+```
+
+and continues to exit `0`. The commit gate from stage 1 still applies, but **no secret scanning happens at all**. A repository can therefore pass every commit through a hook that reports success while performing no scan. Treat `gitleaks version` as part of the setup checklist, not an optional extra.
+
+When Gitleaks is present, the hook scans the staged diff and aborts the commit with exit status `1` if any finding is reported.
+
+---
+
+## 3. Where the Hook Lives, and Why That Matters
+
+The hook is written to `.git/hooks/pre-commit`. **Git does not track the contents of `.git/`.** The hook is therefore not part of any commit, is not pushed, and is not present in any fresh clone.
+
+Consequences to plan around:
+
+- Every clone of every Dev-OS project must run `./.agents/scripts/install-hooks.sh` by hand before the gate exists on that machine.
+- A contributor who never runs the installer gets no gate and no warning; raw `git commit` simply works for them.
+- CI checkouts have no hook. Any enforcement that must hold for the whole project — rather than for one developer's working copy — has to be duplicated as a server-side check or a CI job.
+- `git commit --no-verify` (`-n`) skips all pre-commit hooks by design. The gate is a guardrail against accident and drift, not a control that survives a determined bypass.
+- The installer overwrites `pre-commit` outright. It does not chain to an existing hook, so a project already using another hook manager (Husky, lefthook, pre-commit) will have that manager's `pre-commit` entry point replaced. The backup described in section 1 preserves the file, but the two hooks do not run together afterwards.
+
+---
+
+## 4. Known Issues
+
+Two items were raised against the hook template. Both were checked against the source at `.agents/scripts/install-hooks.sh` and against a live Gitleaks install (8.30.1, Homebrew, macOS). One is confirmed; one did not reproduce. Both are recorded here, including the one that did not reproduce, so the question is not re-opened from memory later.
+
+### Issue 1 — The hook calls a legacy Gitleaks subcommand (RESOLVED in v2.1.0)
+
+The generated hook previously ran:
+
+```bash
+gitleaks protect --staged --verbose
+```
+
+`protect` is a legacy subcommand. On Gitleaks 8.30.1+ it no longer appears in the `Available Commands` list printed by `gitleaks --help`. In Dev-OS v2.1.0, this invocation was updated in `.agents/scripts/install-hooks.sh` to the documented current form:
+
+```bash
+gitleaks git --staged --verbose
+```
+
+### Issue 2 — Fragile `$?` testing between commands (HARDENED in v2.1.0)
+
+Testing `$?` on a later line is a fragile idiom: inserting an echo or log line can reset `$?` and silently bypass failure handling. In Dev-OS v2.1.0, this was hardened to test the command directly:
+
+```bash
+if ! gitleaks git --staged --verbose; then
+    echo ""
+    echo "[ FAIL ] GITLEAKS ERROR: Hardcoded secret or API key detected in staged files."
+    echo "[ WARN ] Commit aborted to prevent secret leak."
+    echo ""
+    exit 1
+fi
+```
+
+This eliminates the ordering hazard completely.
+
+---
+
+## 5. Verifying the Gate Yourself
+
+The gate is worth verifying per machine, since installation is manual and Gitleaks is optional. In a scratch repository:
+
+```bash
+git init /tmp/hook-check && cd /tmp/hook-check
+/path/to/dev-os/.agents/scripts/install-hooks.sh
+
+# Stage 1: the commit gate should abort with [ FAIL ] and exit 1.
+git commit --allow-empty -m "should be blocked"
+
+# Stage 2: the secret scan should abort with [ FAIL ] and exit 1.
+printf 'AWS_KEY = "AKIAIMNOJVGFDXXXE4OA"\n' > leak.txt
+git add leak.txt
+DEVOS_COMMIT_APPROVED=true git commit -m "should also be blocked"
+
+git log --oneline   # expect no commits
+```
+
+If the second command succeeds, check `gitleaks version` first — a missing binary makes the hook warn and continue rather than scan.
+
+---
+
+## 6. Related Documentation
+
+- [System Architecture](ARCHITECTURE.md) — the Commit Gate Flow diagram
+- [Getting Started](GETTING_STARTED.md) — installation and the scripted checkpoint
+- [Lessons Learned](LESSONS.md) — the incident that motivated the mechanical gate
+- [Root README](../README.md) — commit gate overview and setup steps