@tosanoob/acs 0.1.0

package/src/hooks/post-commit.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# acs post-commit hook — validation + commit hash patch
+# Runs AFTER every commit. Never blocks. Always exits 0.
+# Installed by: acs init
+set -uo pipefail
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+CHANGELOGS_DIR="$REPO_ROOT/.ai/changelogs"
+ERRORS_FILE="$REPO_ROOT/.ai/.errors"
+
+# ── Guard: amend re-entry ────────────────────────────────────────────────────
+# When this hook amends the commit (to patch Commit: PENDING), git re-fires
+# the post-commit hook. Exit immediately to prevent infinite amend loops.
+if [ -n "${ACS_AMEND_RUNNING:-}" ]; then
+  exit 0
+fi
+
+# ── Guard: [acs] tag ─────────────────────────────────────────────────────────
+# Doc commits (enrichment, rename) skip validation.
+COMMIT_MSG=$(git log -1 --format='%s' 2>/dev/null || echo "")
+if echo "$COMMIT_MSG" | grep -qF '[acs]'; then
+  exit 0
+fi
+
+# ── Get the commit hash that was just made ───────────────────────────────────
+COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null) || exit 0
+SHORT_HASH="${COMMIT_HASH:0:8}"
+
+# ── Patch "PENDING" in any changelog written by pre-commit ──────────────────
+# The pre-commit hook wrote Commit: PENDING because the hash wasn't known yet.
+if [ -d "$CHANGELOGS_DIR" ]; then
+  for f in "$CHANGELOGS_DIR"/changelog-*.md; do
+    [ -f "$f" ] || continue
+    if grep -q '^Commit: PENDING$' "$f" 2>/dev/null; then
+      # Patch the PENDING placeholder with the real hash
+      sed -i "s/^Commit: PENDING$/Commit: $COMMIT_HASH/" "$f"
+      # Stage the patched file and amend silently.
+      # ACS_AMEND_RUNNING prevents the hook from re-entering on the amend.
+      git add "$f" 2>/dev/null
+      ACS_AMEND_RUNNING=1 GIT_EDITOR=true git commit --amend --no-edit 2>/dev/null || true
+      break
+    fi
+  done
+fi
+
+# ── Schema validation ────────────────────────────────────────────────────────
+# Find the changelog for this commit and validate its schema.
+REQUIRED_SECTIONS=(
+  "## What Changed"
+  "## Why (AI Context)"
+  "## Architectural Impact"
+  "## Patterns Used"
+  "## Integration Points"
+  "## Gotchas"
+  "## How to Extend"
+)
+
+CHANGELOG_FILE=""
+if [ -d "$CHANGELOGS_DIR" ]; then
+  for f in "$CHANGELOGS_DIR"/changelog-*.md; do
+    [ -f "$f" ] || continue
+    if grep -q "^Commit: $COMMIT_HASH" "$f" 2>/dev/null; then
+      CHANGELOG_FILE="$f"
+      break
+    fi
+  done
+fi
+
+if [ -z "$CHANGELOG_FILE" ]; then
+  # No changelog found for this commit — log and exit
+  mkdir -p "$REPO_ROOT/.ai"
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] MISSING_CHANGELOG commit=$SHORT_HASH msg='$COMMIT_MSG'" >> "$ERRORS_FILE"
+  exit 0
+fi
+
+# Validate each required section exists
+VALIDATION_FAILED=0
+for section in "${REQUIRED_SECTIONS[@]}"; do
+  if ! grep -qF "$section" "$CHANGELOG_FILE" 2>/dev/null; then
+    mkdir -p "$REPO_ROOT/.ai"
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] SCHEMA_ERROR commit=$SHORT_HASH file=$(basename "$CHANGELOG_FILE") missing='$section'" >> "$ERRORS_FILE"
+    VALIDATION_FAILED=1
+  fi
+done
+
+# Check for secret-looking patterns in generated content
+SECRET_PATTERNS=(
+  "-----BEGIN.*PRIVATE KEY-----"
+  "sk-[a-zA-Z0-9]{32}"
+  "ghp_[a-zA-Z0-9]{36}"
+  "AKIA[0-9A-Z]{16}"
+)
+for pattern in "${SECRET_PATTERNS[@]}"; do
+  if grep -qE "$pattern" "$CHANGELOG_FILE" 2>/dev/null; then
+    mkdir -p "$REPO_ROOT/.ai"
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] SECRET_PATTERN_DETECTED commit=$SHORT_HASH file=$(basename "$CHANGELOG_FILE") pattern='$pattern'" >> "$ERRORS_FILE"
+    VALIDATION_FAILED=1
+  fi
+done
+
+if [ "$VALIDATION_FAILED" -eq 1 ]; then
+  # Rename to .FAILED so acs status can find it
+  mv "$CHANGELOG_FILE" "${CHANGELOG_FILE%.md}.FAILED.md" 2>/dev/null || true
+fi
+
+# Always exit 0 — never block the developer
+exit 0

package/src/hooks/pre-commit.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# acs pre-commit hook — enforcement layer
+# Ensures every commit includes a changelog in .ai/changelogs/
+# Installed by: acs init
+set -euo pipefail
+
+ACS_CMD="${ACS_CMD:-acs}"
+
+# ── Guard 1: [acs] tag ──────────────────────────────────────────────────────
+# Enrichment and doc commits include [acs] in the message. Skip them.
+COMMIT_MSG_FILE="${GIT_DIR:-.git}/COMMIT_EDITMSG"
+if [ -f "$COMMIT_MSG_FILE" ]; then
+  if grep -qF '[acs]' "$COMMIT_MSG_FILE" 2>/dev/null; then
+    exit 0
+  fi
+fi
+
+# ── Guard 2: changelog already staged ───────────────────────────────────────
+# Claude Code (primary path) stages the changelog before committing.
+# If a .ai/changelogs/ file is already staged, nothing to do.
+if git diff --cached --name-only 2>/dev/null | grep -q '^\.ai/changelogs/'; then
+  exit 0
+fi
+
+# ── Guard 3: merge commit ────────────────────────────────────────────────────
+# Don't generate changelogs for merge commits.
+if [ -f "${GIT_DIR:-.git}/MERGE_HEAD" ]; then
+  exit 0
+fi
+
+# ── Generate changelog ───────────────────────────────────────────────────────
+# At this point: no AI tool staged a changelog. We write one.
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+CHANGELOGS_DIR="$REPO_ROOT/.ai/changelogs"
+mkdir -p "$CHANGELOGS_DIR"
+
+# Timestamp + suffix for filename
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H-%M-%S")
+SUFFIX=$(head -c 2 /dev/urandom | od -An -tx1 | tr -d ' \n' | head -c 4)
+FILENAME="changelog-${TIMESTAMP}Z-${SUFFIX}.md"
+FILEPATH="$CHANGELOGS_DIR/$FILENAME"
+
+# Get diff of staged changes
+STAGED_DIFF=$(git diff --cached --stat 2>/dev/null || echo "")
+STAGED_FILES=$(git diff --cached --name-only 2>/dev/null | head -20 || echo "")
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+AUTHOR=$(git config user.name 2>/dev/null || echo "unknown")
+AUTHOR_EMAIL=$(git config user.email 2>/dev/null || echo "")
+
+# Load llm_command from acs.config.json if present
+LLM_CMD=""
+ACS_CONFIG="$REPO_ROOT/acs.config.json"
+if [ -f "$ACS_CONFIG" ]; then
+  LLM_CMD=$(node -e "try{const c=require('$ACS_CONFIG');process.stdout.write(c.llm_command||'')}catch(e){}" 2>/dev/null || "")
+fi
+
+if [ -n "$LLM_CMD" ]; then
+  # ── AI path: call LLM for rich changelog ──────────────────────────────────
+  CONSTITUTION=""
+  if [ -f "$REPO_ROOT/.ai/CONSTITUTION.md" ]; then
+    CONSTITUTION=$(head -100 "$REPO_ROOT/.ai/CONSTITUTION.md")
+  fi
+
+  PROMPT="You are writing an AI changelog for a git commit. Based on the staged diff below, generate a changelog following the exact schema. Every section requires minimum 2 sentences.
+
+STAGED FILES:
+$STAGED_FILES
+
+STAGED DIFF (summary):
+$STAGED_DIFF
+
+PROJECT CONSTITUTION (for Patterns Used section):
+$CONSTITUTION
+
+Generate the changelog now. Start with the header fields, then each ## section. Do not add any text before the # AI Changelog line.
+
+# AI Changelog
+Commit: PENDING
+Date: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+Author: $AUTHOR <$AUTHOR_EMAIL>
+Branch: $BRANCH
+AI-Tool: ${ACS_AI_TOOL:-unknown}
+Session-Quality: INFERRED
+
+## What Changed
+[fill in]
+
+## Why (AI Context)
+[fill in]
+
+## Architectural Impact
+[fill in]
+
+## Patterns Used
+[fill in]
+
+## Integration Points
+[fill in]
+
+## Gotchas
+[fill in]
+
+## How to Extend
+[fill in]"
+
+  # Call LLM (headless subprocess)
+  CHANGELOG_CONTENT=$(echo "$PROMPT" | timeout 60 $LLM_CMD 2>/dev/null) || CHANGELOG_CONTENT=""
+
+  if [ -n "$CHANGELOG_CONTENT" ]; then
+    echo "$CHANGELOG_CONTENT" > "$FILEPATH"
+  else
+    # LLM failed — fall through to minimal changelog
+    LLM_CMD=""
+  fi
+fi
+
+if [ -z "$LLM_CMD" ]; then
+  # ── Minimal path: no LLM, write metadata + file list ──────────────────────
+  FILE_COUNT=$(echo "$STAGED_FILES" | grep -c . || echo "0")
+  NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  cat > "$FILEPATH" << CHANGELOG
+# AI Changelog
+Commit: PENDING
+Date: $NOW
+Author: $AUTHOR <$AUTHOR_EMAIL>
+Branch: $BRANCH
+AI-Tool: none
+Session-Quality: NO_AI
+
+## What Changed
+$FILE_COUNT file(s) staged for this commit: $STAGED_FILES. This changelog was generated by the acs fallback hook without AI assistance.
+
+## Why (AI Context)
+No AI tool active during this commit. This is a human-authored commit captured by the acs pre-commit fallback hook. Context can be enriched later by running \`acs retry\` inside a Claude Code or Codex session.
+
+## Architectural Impact
+Not assessed — no AI session context available. Run \`acs retry\` to enrich this changelog with architectural analysis.
+
+## Patterns Used
+Not assessed — no AI session context available. Run \`acs retry\` to add pattern analysis.
+
+## Integration Points
+Not assessed — no AI session context available. Run \`acs retry\` to identify integration points.
+
+## Gotchas
+Not assessed — no AI session context available. Run \`acs retry\` to add gotcha notes.
+
+## How to Extend
+Not assessed — no AI session context available. Run \`acs retry\` to add extension guidance.
+CHANGELOG
+fi
+
+# Stage the changelog
+git add "$FILEPATH"
+
+# Note: commit hash is "PENDING" here — post-commit hook patches it
+exit 0

package/src/skills/claude-code/SKILL.md

@@ -0,0 +1,100 @@
+# ACS — AI Context Sync
+
+This project uses **ai-context-sync (acs)**. The `.ai/` directory is the team's shared AI memory. Read it before starting. Write to it after committing.
+
+## Before Starting Any Task
+
+1. Read `.ai/CONSTITUTION.md` — project patterns, conventions, anti-patterns (latest section for each heading)
+2. Read the 5 most recent files in `.ai/changelogs/` (sorted by filename, newest-last, read from the end)
+3. If any `.ai/.pending-*` files exist, offer to enrich them (see Enrichment below)
+
+## After Every Git Commit
+
+**If you ran `git commit` as part of your work**, generate and write a changelog immediately after:
+
+1. Get the commit hash: run `git rev-parse HEAD`
+2. Get the diff: run `git show HEAD --format= -p`
+3. Read `.ai/CONSTITUTION.md` (for patterns reference)
+4. Generate the changelog (see Schema below)
+5. Write it to `.ai/changelogs/changelog-<ISO-timestamp>Z-<4-char-hex>.md`
+   - Timestamp format: `2026-04-03T15-30-00` (colons replaced with hyphens)
+   - 4-char hex: use any unique suffix (e.g. first 4 chars of commit hash)
+6. Stage and commit: `git add .ai/changelogs/<filename> && git commit -m "chore(ai): document commit <short-hash> [acs]"`
+
+The `[acs]` tag in the commit message prevents the pre-commit hook from generating another changelog for this doc commit.
+
+## Changelog Schema
+
+```
+# AI Changelog
+Commit: <full commit hash>
+Date: <ISO 8601 timestamp>
+Author: <git author name and email>
+Branch: <current branch>
+AI-Tool: claude-code
+Session-Quality: INFERRED
+
+## What Changed
+[Factual description of the diff. What files changed and what they do now. Never hallucinate — only describe what's in the diff. Minimum 2 sentences.]
+
+## Why (AI Context)
+[The reasoning behind this change. What problem it solves, what decision was made, what alternatives were considered. Minimum 2 sentences.]
+
+## Architectural Impact
+[What this changes about the system design. How it affects other parts of the codebase. Or "Minimal — no architectural change detected." Minimum 2 sentences.]
+
+## Patterns Used
+[Which patterns from CONSTITUTION.md this follows. Or "Pattern not yet established in CONSTITUTION.md." Minimum 2 sentences.]
+
+## Integration Points
+[What other files, services, or APIs reference or depend on what changed. Or "None detected." Minimum 2 sentences.]
+
+## Gotchas
+[Non-obvious things about this change that the next developer should know. Or "None identified." Minimum 2 sentences.]
+
+## How to Extend
+[Where the next developer should start if they need to build on this. File:line references where possible. Minimum 2 sentences.]
+```
+
+## Slash Commands
+
+### /acs-why `<file>`
+Explain why a file looks the way it does.
+
+1. Run: `git log --follow --format="%H" -- <file>`
+2. For each commit hash, run `acs find-changelog <hash>` or scan `.ai/changelogs/` for files containing `Commit: <hash>`
+3. Read all matching changelogs
+4. Synthesize: "Here's the history of `<file>` and the reasoning behind its current state..."
+
+Default: show all changelogs. If there are more than ~15, summarize the oldest ones and show the 5 most recent in full.
+
+### /acs-onboard
+Generate a complete project briefing for a new developer or AI agent.
+
+1. Read `.ai/CONSTITUTION.md` (full)
+2. Read the 20 most recent changelogs from `.ai/changelogs/`
+3. Synthesize: architecture, patterns, recent work, in-flight features, gotchas
+
+### /acs-commit
+Propose a conventional commit message for the current staged changes.
+
+1. Run: `git diff --cached`
+2. Read `.ai/CONSTITUTION.md` for naming conventions
+3. Propose a Conventional Commits message: `type(scope): description`
+4. Show the proposal and ask for confirmation before committing
+
+## Enrichment (acs retry)
+
+If `.ai/.pending-<hash>` files exist (created by `acs retry`), offer to enrich them:
+"I see N commits with minimal changelogs. Want me to enrich them now?"
+
+For each pending file:
+1. Read the pending file (contains: commit hash, diff, author, branch)
+2. Generate a full changelog using the schema above
+3. Find the matching changelog in `.ai/changelogs/` (by Commit: field)
+4. Overwrite it with the enriched content
+5. Stage: `git add .ai/changelogs/<filename>`
+
+After enriching all pending files:
+- Delete all `.ai/.pending-*` files
+- `git add .ai/changelogs/ && git commit -m "chore(ai): enrich N changelogs [acs]"`

package/src/skills/codex/acs-context.md

@@ -0,0 +1,62 @@
+# ACS Context — AI Context Sync
+
+This project uses **ai-context-sync (acs)**. The `.ai/` directory is the team's shared AI memory.
+
+## Before Starting Any Task
+
+1. Read `.ai/CONSTITUTION.md` — project coding patterns and conventions
+2. Read the 5 most recent files in `.ai/changelogs/` to understand recent work
+
+## After Every Git Commit
+
+After committing code, generate and write a changelog to `.ai/changelogs/`:
+
+**Filename:** `changelog-<YYYY-MM-DDTHH-MM-SS>Z-<4chars>.md`
+(Use hyphens instead of colons in the timestamp for filesystem compatibility)
+
+**Content schema:**
+```
+# AI Changelog
+Commit: <full commit hash>
+Date: <ISO timestamp>
+Author: <name email>
+Branch: <branch>
+AI-Tool: codex
+Session-Quality: INFERRED
+
+## What Changed
+[2+ sentences: what files changed and what they do now]
+
+## Why (AI Context)
+[2+ sentences: the reasoning, decisions, alternatives considered]
+
+## Architectural Impact
+[2+ sentences: system design impact, or "Minimal — no architectural change."]
+
+## Patterns Used
+[2+ sentences: patterns from CONSTITUTION.md used, or "Pattern not yet established."]
+
+## Integration Points
+[2+ sentences: dependencies and callers affected, or "None detected."]
+
+## Gotchas
+[2+ sentences: non-obvious notes for next developer, or "None identified."]
+
+## How to Extend
+[2+ sentences: where to start for follow-on work]
+```
+
+After writing the file, commit it:
+```
+git add .ai/changelogs/<filename>
+git commit -m "chore(ai): document commit <short-hash> [acs]"
+```
+
+The `[acs]` tag prevents the pre-commit hook from looping.
+
+## Key Commands
+
+- `acs why <file>` — see the history and reasoning behind a file
+- `acs onboard` — full project briefing from accumulated context
+- `acs status` — check for commits missing changelogs
+- `acs retry` — enrich minimal changelogs with AI context

package/src/skills/shared/AGENTS.md.tmpl

@@ -0,0 +1,22 @@
+# AI Context Sync (acs)
+
+This repository uses **ai-context-sync** to maintain AI team memory in `.ai/`.
+
+## Before Starting Any Task
+
+1. Read `.ai/CONSTITUTION.md` — coding patterns, conventions, anti-patterns for this project
+2. Read the 5 most recent `.ai/changelogs/` files — what changed recently and why
+
+## After Making Commits
+
+Write a changelog to `.ai/changelogs/changelog-<timestamp>Z-<suffix>.md` after each commit.
+See the acs SKILL.md or `agents/acs-context.md` for the full schema.
+
+Commit the changelog: `git add .ai/changelogs/ && git commit -m "chore(ai): document commit <hash> [acs]"`
+
+## Key Commands
+
+- `acs why <file>` — why does this file look like this?
+- `acs onboard` — full project briefing
+- `acs status` — what's missing context?
+- `acs retry` — enrich minimal changelogs

package/src/templates/CONSTITUTION.md.tmpl

@@ -0,0 +1,32 @@
+# AI Constitution — {{PROJECT_NAME}}
+<!-- Managed by acs. Add new sections with: acs update-constitution -->
+<!-- AI tools: read only the most recent section for each heading -->
+
+## [{{DATE}}] How to Code Here
+
+### Stack & Patterns
+<!-- Describe the main technologies and architectural patterns used -->
+- Language/Runtime: [e.g., TypeScript/Node.js, Python/FastAPI, Go]
+- Key frameworks: [e.g., React, Express, Django]
+- Testing: [e.g., Vitest for unit, Playwright for E2E]
+
+### File Organization
+<!-- How is code organized? What goes where? -->
+- Source: `src/` — application code
+- Tests: `tests/` — mirrors src/ structure
+- [Add more conventions here]
+
+### Naming Conventions
+- Files: [e.g., kebab-case for modules, PascalCase for components]
+- Functions: [e.g., camelCase, verb-first for actions]
+- Variables: [e.g., camelCase, descriptive names preferred]
+
+### Anti-Patterns (Never Do)
+<!-- Things that caused bugs or were explicitly decided against -->
+- [e.g., Don't use any — use unknown and narrow the type]
+- [e.g., Don't commit secrets — use env vars]
+
+### Key Entry Points
+<!-- Where should a new developer start reading? -->
+- [e.g., src/index.ts — CLI entry point]
+- [e.g., src/core/ — core business logic]

package/src/templates/aiignore.default

@@ -0,0 +1,45 @@
+# .aiignore — files never sent to AI for changelog generation
+# Syntax identical to .gitignore
+# Generated by acs init — customize as needed
+
+# === Secrets (always redacted) ===
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+secrets/
+credentials/
+**/*secret*
+**/*_secret*
+
+# === Large generated files (too expensive to summarize) ===
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+*.lock
+dist/
+build/
+.next/
+.nuxt/
+node_modules/
+__pycache__/
+*.pyc
+.venv/
+vendor/
+
+# === Binary / non-text files ===
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.ico
+*.svg
+*.pdf
+*.zip
+*.tar.gz
+*.tgz
+*.wasm
+*.bin
+*.exe