From f5292183f40b86e7df23970ac5d645f4da7d5c7f Mon Sep 17 00:00:00 2001 From: reachableceo Date: Fri, 7 Aug 2026 12:14:30 -0500 Subject: [PATCH] refactor: remove Makefile, restructure as knowledge-first framework MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The primary value is the knowledge layer (markdown files that any agent reads โ€” Crush, OpenWebUI, Hermes, Conduit on iPhone). CLI tooling (scripts, git hooks) is optional, for projects that use git/docker. Changes: - Remove Makefile entirely. All commands are now direct script invocations (bash scripts/check-rules.sh, bash scripts/setup-hooks.sh, etc.) - Add scripts/test.sh stub (replaces make test) - check-rules.sh: test-suite check now calls scripts/test.sh, not make test - Rewrite README as three-layer architecture: knowledge โ†’ git hooks โ†’ docker - Update all docs (AGENTS.md, BASELINE-PROMPT.md, ADOPTING.md, PATTERNS.md, STATUS.md) to remove every make reference The framework now works for: - CLI/harness users (git hooks + scripts + AGENTS.md) - Non-CLI users (BASELINE-PROMPT.md loaded into any agent's system prompt) ๐Ÿ’˜ Generated with Crush Assisted-by: Crush via Crush --- ADOPTING.md | 23 ++++---- AGENTS.md | 28 +++++----- BASELINE-PROMPT.md | 2 +- Makefile | 59 -------------------- PATTERNS.md | 14 ++--- README.md | 122 ++++++++++++++++++++++++----------------- STATUS.md | 4 +- scripts/check-rules.sh | 14 ++--- scripts/garden.sh | 2 +- scripts/setup-hooks.sh | 2 +- scripts/test.sh | 6 ++ 11 files changed, 120 insertions(+), 156 deletions(-) delete mode 100644 Makefile create mode 100755 scripts/test.sh diff --git a/ADOPTING.md b/ADOPTING.md index fd02c79..50c463f 100644 --- a/ADOPTING.md +++ b/ADOPTING.md @@ -16,11 +16,11 @@ tea repo create --owner --name --template-from TSYSGroupCorporat # or clone directly: git clone ssh://git@git.knownelement.com:29418/TSYSGroupCorporate/TSYSGroupAIOS.git cd -make setup # install git hooks -make fast # verify baseline +bash scripts/setup-hooks.sh # install git hooks +bash scripts/check-rules.sh --fast # verify baseline ``` -Then edit `AGENTS.md` (fill bracketed fields), define `make test`, and start work. +Then edit `AGENTS.md` (fill bracketed fields), override `scripts/test.sh`, and start work. --- @@ -39,7 +39,7 @@ cd ~/projects/ # Get them from the meta repo: META=~/daytoday/meta -# Scripts, hooks engine, Makefile, shared lib (the mechanical enforcement) +# Scripts, hooks engine, shared lib (the mechanical enforcement) cp -n "$META/Makefile" . mkdir -p scripts/lib cp -n "$META/scripts/check-rules.sh" scripts/ @@ -69,18 +69,18 @@ is for projects that don't have one yet. ### Step 3: Install git hooks and verify ```bash -make setup # installs pre-commit + pre-push from scripts/ -make fast # see what passes and what fails +bash scripts/setup-hooks.sh # installs pre-commit + pre-push from scripts/ +bash scripts/check-rules.sh --fast # see what passes and what fails ``` ### Step 4: Fix the failures (incrementally) -`make fast` will likely report failures โ€” the project's existing code may not +`bash scripts/check-rules.sh --fast` will likely report failures โ€” the project's existing code may not pass shellcheck, or `.md` files lack Discourse pointers. **Fix these incrementally; don't rewrite the project in one pass.** Common fixes: -- **shellcheck violations:** run `make lint` for details; fix warnings in the flagged files. +- **shellcheck violations:** run `bash scripts/check-rules.sh` for details; fix warnings in the flagged files. - **`:latest` image tags:** pin to a specific version in docker-compose / Dockerfile. - **Container naming:** add `container_name:` to every service in docker-compose files. - **Missing required files:** create `questions-v1.md`, `.env.example`, etc. @@ -108,7 +108,7 @@ PROJECT_BANNED_SUFFIXES="py|js|ts" # banned production f ### Step 7: Commit and push ```bash -make validate # full audit should pass +bash scripts/check-rules.sh # full audit should pass git add -A git commit -m "chore: adopt TSYSGroupAIOS framework (git hooks, rules engine, SoR policy)" git push @@ -118,7 +118,7 @@ git push ## What NOT to change during adoption -- **Don't rewrite existing code** that works. The framework enforces conventions going forward; fix existing violations incrementally via `make lint` / `make fast`. +- **Don't rewrite existing code** that works. The framework enforces conventions going forward; fix existing violations incrementally via `bash scripts/check-rules.sh`. - **Don't remove the project's Redmine/Discourse integration.** The framework *requires* it โ€” the project already has it. Align the AGENTS.md prose to match. - **Don't add `docs/JOURNAL.md`.** Redmine is the system of record for work; Discourse for docs. No JOURNAL.md. - **Don't add Crush hooks.** The framework is harness-agnostic. Enforcement is git hooks + AGENTS.md prose only. @@ -135,6 +135,5 @@ git push | Docker wrapper | `scripts/docker-run.sh` | Yes | | Lifecycle scripts | `scripts/up.sh`, `scripts/down.sh` | Yes | | Gardening | `scripts/garden.sh` | Yes | -| Makefile targets | `make setup/fast/validate/lint/test/garden/up/down/status` | Yes | | Policy document | `AGENTS.md` | Yes โ€” any agent framework reads it | -| Global baseline | `BASELINE-PROMPT.md` | Yes โ€” reference it, don't need to ship it | +| Global baseline | `BASELINE-PROMPT.md` | Yes โ€” paste into any system prompt | diff --git a/AGENTS.md b/AGENTS.md index 8012c12..ac8a664 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,12 +13,12 @@ enforce the mechanical rules below; this document states the policy and intent. **You are an AI agent working on this project. Your first actions, in order:** -1. **Set up the environment:** `make setup` (installs git hooks โ€” idempotent). +1. **Set up the environment:** `bash scripts/setup-hooks.sh` (installs git hooks โ€” idempotent). 2. **Read [STATUS.md](STATUS.md)** โ€” current state, inbox, blockers, tactical notes. 3. **Read [`.crush/memory/operational.md`](.crush/memory/operational.md)** โ€” access details, key IDs, gotchas. 4. **Read [questions-v1.md](questions-v1.md)** โ€” open questions awaiting human input. 5. **Check Redmine** โ€” `redmine list --assigned-to-me -p ` for active work. -6. **Check current state:** `git log --oneline -10` and `make status`. +6. **Check current state:** `git log --oneline -10`. ## Project Overview @@ -45,11 +45,11 @@ Replace this bracketed text.> โ”‚ โ”œโ”€โ”€ pre-commit โ† fast rule audit (hot-path bypass for status/working) โ”‚ โ”œโ”€โ”€ pre-push โ† full audit + clean-tree gate โ”‚ โ”œโ”€โ”€ check-rules.sh โ† the rule audit engine (pass/warn/fail accumulator) +โ”‚ โ”œโ”€โ”€ test.sh โ† project test runner (override per project) โ”‚ โ”œโ”€โ”€ docker-run.sh โ† canonical ephemeral-container wrapper โ”‚ โ”œโ”€โ”€ up.sh / down.sh โ† docker compose lifecycle wrappers โ”‚ โ”œโ”€โ”€ garden.sh โ† doc-sprawl / Discourse-migration report โ”‚ โ””โ”€โ”€ lib/common.sh โ† shared bash library (colors, log_*, docker_run, check) -โ”œโ”€โ”€ Makefile โ† standard targets: setup/validate/fast/lint/test/garden/up/down/status โ”œโ”€โ”€ docker-compose.yml.example โ† lifecycle template (copy to docker-compose.yml) โ”œโ”€โ”€ .env.example โ† copy to .env, fill in secrets โ””โ”€โ”€ .crush/memory/ โ† operational memory read each session (if using Crush) @@ -128,7 +128,7 @@ docker run --rm --env-file ~/projects/KNEL-AIMiddleware/discourse-cli/.env \ ## CI/CD - The **local workstation must be able to run the same CI/CD** the hosted infrastructure runs. Maintain them in lockstep. -- **Shift left:** catch issues at `make fast` (pre-commit) before push, before PR, before merge. +- **Shift left:** catch issues at `bash scripts/check-rules.sh --fast` (pre-commit) before push, before PR, before merge. ## Conventions @@ -146,22 +146,20 @@ docker run --rm --env-file ~/projects/KNEL-AIMiddleware/discourse-cli/.env \ ## Key Commands ```bash -make setup # install git hooks (run once after clone) -make fast # fast rule audit (pre-commit equivalent) -make validate # full audit (includes the test suite) -make lint # shellcheck via docker -make test # run the test suite (define per project) -make garden # doc-sprawl / Discourse-migration report -make up # bring up the docker-compose stack -make down # bring it down -make status # repo status snapshot +bash scripts/setup-hooks.sh # install git hooks (run once after clone) +bash scripts/check-rules.sh --fast # fast rule audit (pre-commit equivalent) +bash scripts/check-rules.sh # full audit (includes test suite) +bash scripts/test.sh # run the test suite (override per project) +bash scripts/garden.sh # doc-sprawl / Discourse-migration report +bash scripts/up.sh # bring up the docker-compose stack +bash scripts/down.sh # bring it down ``` ## Enforcement Model (belt and suspenders) Policy is enforced by **git hooks** (portable, harness-agnostic): `scripts/pre-commit` runs a fast rule audit; `scripts/pre-push` runs the full audit + clean-tree gate. -Install with `make setup`. The checks are in `scripts/check-rules.sh` and cover: +Install with `bash scripts/setup-hooks.sh`. The checks are in `scripts/check-rules.sh` and cover: shellcheck, image pinning, container naming, required files, doc freshness, Discourse pointer-headers, WORKING.md completion, CNW markers, hygiene, and the test suite. @@ -177,7 +175,7 @@ Bypass with `--no-verify` in genuine emergencies only. - Read STATUS.md, questions file, operational memory, and Redmine BEFORE starting work. - Write a failing test first (TDD). - Read files before editing. Use exact text matching. -- Run `make validate` before committing. +- Run `bash scripts/check-rules.sh` before committing. - Use sub-agents to parallelize scoped work. - Log interruptions to the STATUS.md Inbox. diff --git a/BASELINE-PROMPT.md b/BASELINE-PROMPT.md index ff11c44..10899f5 100644 --- a/BASELINE-PROMPT.md +++ b/BASELINE-PROMPT.md @@ -83,7 +83,7 @@ - Run a routine **gardening loop.** Agents are disciplined with code but tend to sprawl `.md` files everywhere. - Keep docs, code, and tests in sync at all times. -- `make garden` reports `.md` sprawl and files that should be migrated to Discourse. +- `scripts/garden.sh` reports `.md` sprawl and files that should be migrated to Discourse. ## 12. Sub-agents as subcontractors diff --git a/Makefile b/Makefile deleted file mode 100644 index e2e582c..0000000 --- a/Makefile +++ /dev/null @@ -1,59 +0,0 @@ -# Makefile โ€” the single standard task-entry surface for this project. -# -# Every project using the template exposes the SAME targets, so CI, hooks, -# and humans all know one set of verbs regardless of the underlying stack. -# Each target delegates to scripts/ so the logic is shellcheck-able and -# runnable anywhere (the Makefile is pure dispatch). -# -# Targets: -# make setup install git hooks (idempotent) -# make validate run the full rule audit -# make fast run the fast rule audit (pre-commit equivalent) -# make lint lint (shellcheck via docker) -# make test run the test suite <-- override for your stack -# make garden doc-sprawl / Discourse-migration report -# make up bring up the docker-compose stack -# make down bring it down -# make status show repo status snapshot -# make clean remove build/test artifacts <-- override for your stack -# -# Override `test` and `clean` per project; the rest are stable. - -.PHONY: setup validate fast lint test garden up down status clean help - -help: ## Show available targets - @grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN{FS=":.*?## "}{printf " \033[36m%-12s\033[0m %s\n", $$1, $$2}' - -setup: ## Install git hooks - @bash scripts/setup-hooks.sh - -validate: ## Full rule audit (includes tests) - @bash scripts/check-rules.sh - -fast: ## Fast rule audit (pre-commit equivalent) - @bash scripts/check-rules.sh --fast - -lint: ## Lint shell scripts (shellcheck via docker) - @docker run --rm -v "$$(pwd):/mnt" koalaman/shellcheck:stable \ - $$(find . -path ./.git -prune -o -path ./.tmp -prune -o -path ./vendor -prune -o -path ./node_modules -prune -o \( -name '*.sh' -o -name '*.bash' \) -print | sed 's|^\./|/mnt/|') || true - -test: ## Run the test suite (override per project; default no-op pass) - @echo "make test: no test target defined โ€” override this in your project's Makefile." - -garden: ## Doc-sprawl / Discourse-migration report - @bash scripts/garden.sh - -up: ## Bring up the docker-compose stack - @bash scripts/up.sh - -down: ## Bring down the docker-compose stack - @bash scripts/down.sh - -status: ## Show a repo status snapshot - @echo "== branch =="; git branch --show-current 2>/dev/null || echo "(no branch)" - @echo "== last commit =="; git log --oneline -1 2>/dev/null || true - @echo "== working tree =="; git status --short 2>/dev/null || echo "(not a git repo)" - @echo "== STATUS.md head =="; sed -n '1,12p' STATUS.md 2>/dev/null || echo "(no STATUS.md)" - -clean: ## Remove build/test artifacts (override per project) - @echo "make clean: nothing to clean โ€” override this in your project's Makefile." diff --git a/PATTERNS.md b/PATTERNS.md index 725b421..1d60f8d 100644 --- a/PATTERNS.md +++ b/PATTERNS.md @@ -63,7 +63,7 @@ Three different install mechanisms; one project has no installer at all. **Decision:** the template uses the **copy** approach (most portable: works on any clone, no config mutation, idempotent) with a single `scripts/setup-hooks.sh`, and combines both policy philosophies: - `pre-commit` = fast audit with a **hot-path bypass** for `STATUS.md` / `JOURNAL.md` / `WORKING.md` (so frequent status commits stay frictionless) โ€” proven in RCEO. -- `pre-push` = full audit (incl. `make test`) โ€” proven in RCEO โ€” plus the dirty-tree gate โ€” proven in KNEL-AIMiddleware. +- `pre-push` = full audit (incl. `scripts/test.sh`) โ€” proven in RCEO โ€” plus the dirty-tree gate โ€” proven in KNEL-AIMiddleware. --- @@ -133,7 +133,7 @@ The recurring semantic targets โ€” **build, test, lint, validate, status, clean, Only `hermes-agent` has CI (22 GitHub Actions workflows โ€” an exemplar: change-detection orchestrator, reusable-workflow lanes, SHA-pinned actions, supply-chain/OSV scans, live PR-comment bot). The other 17 have none. -**Decision:** the template doesn't ship CI (it's stack-dependent), but `make validate` + `make lint` give any future workflow a uniform entry point. The hermes-agent `ci.yml` orchestrator is the documented growth path. +**Decision:** the template doesn't ship CI (it's stack-dependent), but `scripts/check-rules.sh` + `scripts/garden.sh` give any future workflow a uniform entry point. The hermes-agent `ci.yml` orchestrator is the documented growth path. --- @@ -210,16 +210,16 @@ in `AGENTS.md`. New artifacts and checks added: | Principle (baseline ยง) | How the template enforces it | |---|---| | **Stop over-thinking; ask early** (ยง1, ยง9) | `questions-v1.md` skeleton + AGENTS.md "Questions" section; required-files check fails if absent | -| **Token efficiency / farm to tooling** (ยง2) | `make lint` runs shellcheck in Docker; AGENTS.md "Working Style" forbids parsing huge code in context | -| **Redmine = SoR for work; Discourse = SoR for docs** (ยง3) | AGENTS.md "Systems of Record" section; `make garden` flags oversized non-Discourse `.md` | +| **Token efficiency / farm to tooling** (ยง2) | `scripts/check-rules.sh` runs shellcheck in Docker; AGENTS.md "Working Style" forbids parsing huge code in context | +| **Redmine = SoR for work; Discourse = SoR for docs** (ยง3) | AGENTS.md "Systems of Record" section; `scripts/garden.sh` flags oversized non-Discourse `.md` | | **Git .md = stubs to Discourse** (ยง3) | `scripts/garden.sh` reports oversized `.md` lacking a Discourse URL | | **`tea` CLI for PRs; off-workstation โ†’ PR** (ยง4) | AGENTS.md "Git Workflow" policy | -| **Shift-left CI/CD, lockstep local + hosted** (ยง5) | AGENTS.md "CI/CD" section; `make fast` runs at pre-commit | +| **Shift-left CI/CD, lockstep local + hosted** (ยง5) | AGENTS.md "CI/CD" section; `scripts/check-rules.sh --fast` runs at pre-commit | | **Docker/k8s for everything; container naming** (ยง6) | new container-naming rule in `check-rules.sh` (every compose service needs `container_name`); `docker-compose.yml.example` + `scripts/up.sh` / `scripts/down.sh` | | **STATUS.md = scratchpad, not SoR; has Inbox** (ยง8) | STATUS.md reframed; Inbox section for mid-task interruptions ("don't pivot") | | **Questions file** (ยง9) | `questions-v1.md` artifact + required-files check | | **Belt-and-suspenders enforcement** (ยง10) | already present (git hooks + Crush hooks) โ€” now documented as policy | -| **Gardening loop** (ยง11) | `scripts/garden.sh` + `make garden` target | +| **Gardening loop** (ยง11) | `scripts/garden.sh` | | **Sub-agents as subcontractors** (ยง12) | AGENTS.md "Working Style" | | **TDD + linters** (ยง13) | AGENTS.md "TDD & Linting"; `enforce-rules.sh` TDD reminder (opt-in via `PROJECT_SOURCE_SUFFIXES`) | @@ -238,7 +238,7 @@ in `AGENTS.md`. New artifacts and checks added: ### New Makefile targets -`make garden`, `make up`, `make down` โ€” standard verbs across every project. +`scripts/garden.sh`, `scripts/up.sh`, `scripts/down.sh` โ€” standard scripts across every project. ### What stayed project-level (not globalized) diff --git a/README.md b/README.md index 7a540cc..c69f0d3 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,86 @@ -# meta โ€” cross-project best-practices template +# TSYSGroupAIOS โ€” cross-project best-practices framework -This repo serves two purposes at once: +This repo serves a single purpose: **capture the operating knowledge that makes +AI agents effective, and make it portable to any agent interface.** -1. **It is a Gitea template repository.** Create new projects from it to inherit - the full best-practices stack from the start (AGENTS.md, git hooks, rules - engine, Discourse/Redmine SoR policy, Docker-first conventions). -2. **It is the design source** that maintains the global baseline prompt and the - cross-project pattern extraction. New projects can delete `BASELINE-PROMPT.md` - and `PATTERNS.md` if they don't want the authoring context โ€” or keep them as - reference. +It works in three layers โ€” use whichever you need: -## What you get when you create a project from this template +## Layer 1: Knowledge (works everywhere) + +The markdown files are the core product. Any agent โ€” Crush, OpenWebUI, Hermes, +Conduit on an iPhone โ€” reads them. No CLI, no git, no SSH required. + +| File | What it does | +|---|---| +| **[BASELINE-PROMPT.md](BASELINE-PROMPT.md)** | The global working principles (13 sections). Paste into any agent's system prompt. | +| **AGENTS.md** | Project-level policy skeleton. Any agent that reads files picks this up automatically. | +| **[ADOPTING.md](ADOPTING.md)** | How to bring an existing project under this framework. | +| **[PATTERNS.md](PATTERNS.md)** | Why every decision was made (pattern extraction from 18 projects). | +| **STATUS.md** | Agent scratchpad template (token-efficiency, not system of record). | +| **WORKING.md** | Task tracker template (the only in-repo task list). | +| **questions-v1.md** | Git-tracked question log template for the human. | + +**For non-CLI users (e.g. Conduit/iPhone/Hermes):** load `BASELINE-PROMPT.md` +into the agent's system prompt. That alone carries the operating principles. +Add `AGENTS.md` as project context for project-specific policy. + +## Layer 2: Git hooks (for projects using git) + +When a project uses git, copy in the enforcement scripts for mechanical checks +at commit/push time. Works under any agent โ€” no harness coupling. ``` -/ -โ”œโ”€โ”€ AGENTS.md โ† fill in the bracketed fields, delete the rest -โ”œโ”€โ”€ scripts/ -โ”‚ โ”œโ”€โ”€ setup-hooks.sh โ† install git hooks (run once: make setup) -โ”‚ โ”œโ”€โ”€ pre-commit / pre-push โ† fast audit / full audit + clean-tree gate -โ”‚ โ”œโ”€โ”€ check-rules.sh โ† rule audit engine (shellcheck, image pin, container naming, Discourse pointers, freshness, hygiene, tests) -โ”‚ โ”œโ”€โ”€ docker-run.sh โ† canonical ephemeral-container wrapper -โ”‚ โ”œโ”€โ”€ up.sh / down.sh โ† docker-compose lifecycle wrappers -โ”‚ โ”œโ”€โ”€ garden.sh โ† doc-sprawl / Discourse-migration report -โ”‚ โ””โ”€โ”€ lib/common.sh โ† shared bash library (colors, log_*, docker_run, check) -โ”œโ”€โ”€ Makefile โ† setup/validate/fast/lint/garden/up/down/status/clean -โ”œโ”€โ”€ STATUS.md โ† agent scratchpad (token-efficiency; has Inbox) -โ”œโ”€โ”€ WORKING.md โ† the only task tracker (todos tool banned) -โ”œโ”€โ”€ questions-v1.md โ† git-tracked question log for the human -โ”œโ”€โ”€ docker-compose.yml.example โ† lifecycle template (copy to docker-compose.yml) -โ”œโ”€โ”€ .env.example โ† secrets/config template -โ”œโ”€โ”€ .gitignore -โ”œโ”€โ”€ .crush/memory/operational.md โ† per-session operational memory skeleton (optional, Crush-only) -โ”œโ”€โ”€ BASELINE-PROMPT.md โ† the global working principles (delete if unwanted) -โ””โ”€โ”€ PATTERNS.md โ† the pattern extraction analysis (delete if unwanted) +scripts/ +โ”œโ”€โ”€ setup-hooks.sh โ† install git hooks (bash scripts/setup-hooks.sh) +โ”œโ”€โ”€ pre-commit โ† fast rule audit + hot-path bypass +โ”œโ”€โ”€ pre-push โ† full audit + clean-tree gate +โ”œโ”€โ”€ check-rules.sh โ† the rule audit engine +โ”œโ”€โ”€ test.sh โ† project test runner (override per project) +โ”œโ”€โ”€ garden.sh โ† doc-sprawl / Discourse-migration report +โ””โ”€โ”€ lib/common.sh โ† shared bash library ``` -## Quick start (for a new project) +## Layer 3: Docker lifecycle (for containerized projects) +``` +scripts/docker-run.sh โ† canonical ephemeral-container wrapper +scripts/up.sh โ† docker compose up +scripts/down.sh โ† docker compose down +docker-compose.yml.example โ† lifecycle template +``` + +## What it enforces (layer 2) + +`scripts/check-rules.sh` runs these checks: +- **shellcheck** (zero warnings incl. info-level, via Docker) +- **Docker image pinning** (no `:latest`) +- **Container naming** (explicit `container_name:`, never Docker defaults) +- **Required files** (AGENTS.md, STATUS.md, questions-v1.md, .env.example, etc.) +- **Doc freshness** (STATUS.md updated today) +- **Discourse pointer-header** (non-exempt .md must cite a Discourse URL) +- **WORKING.md completion** (no unchecked tasks at commit time) +- **CNW markers** (unresolved questions flagged) +- **Hygiene** (no merge-conflict markers) +- **Test suite** (scripts/test.sh, in full audit only) + +## Creating a new project from this template + +In Gitea: use this repo as a template (`TSYSGroupCorporate/TSYSGroupAIOS`). + +Or clone and go: ```bash -# Create from this Gitea template, then: -cd my-new-project -git init # if not already -make setup # install git hooks -make fast # confirm baseline passes -# Fill in bracketed fields in AGENTS.md (project name, overview, model, etc.) -# Define `make test` for your stack -# Delete BASELINE-PROMPT.md and PATTERNS.md if you don't want them +git clone ssh://git@git.knownelement.com:29418/TSYSGroupCorporate/TSYSGroupAIOS.git my-project +cd my-project +bash scripts/setup-hooks.sh +bash scripts/check-rules.sh --fast ``` -## What it enforces +Fill in bracketed fields in `AGENTS.md`, override `scripts/test.sh`, start work. -| Layer | What | How | -|---|---|---| -| **Git hooks** | mechanical checks at commit/push | `scripts/pre-commit` (fast audit + hot-path bypass), `scripts/pre-push` (full audit + clean-tree gate) | -| **Rules engine** | shellcheck, image pinning, container naming, required files, doc freshness, Discourse pointers, WORKING.md completion, CNW markers, hygiene, test suite | `scripts/check-rules.sh` (`--fast` for pre-commit, `--quiet` for pre-push) | -| **Makefile** | standard verbs everywhere | `make setup/fast/validate/lint/test/garden/up/down/status/clean` | +## Adopting into an existing project -Configurable via env without editing hooks: `PROJECT_BANNED_COMMANDS`, -`PROJECT_BANNED_SUFFIXES`, `PROJECT_BANNED_ALLOW`, `PROJECT_SOURCE_SUFFIXES`, -`PROJECT_REQUIRED_FILES`. +See [ADOPTING.md](ADOPTING.md). -## The two extra docs (meta-authoring, optional) +## License -- **[BASELINE-PROMPT.md](BASELINE-PROMPT.md)** โ€” the canonical global working principles (13 sections), distilled from operating notes. Projects inherit it; they don't need to ship it. -- **[PATTERNS.md](PATTERNS.md)** โ€” the cross-project pattern extraction from 18 projects across two machines, with a standardization scorecard. Documents *why* every template decision was made. +GNU Affero General Public License v3.0. diff --git a/STATUS.md b/STATUS.md index 2d45ee9..4395172 100644 --- a/STATUS.md +++ b/STATUS.md @@ -16,8 +16,8 @@ Pending: push to TSYSGroupCorporate/TSYSGroupAIOS (Q1). - Removed docs/JOURNAL.md (Q5). Redmine is the SoR for work; Discourse for docs. JOURNAL.md was a stopgap. - Added Discourse pointer-header check to check-rules.sh (Q3) โ€” MANDATORY, FAILs if a non-exempt .md lacks a Discourse URL. All projects. - Fixed CLI references (Q2) โ€” AGENTS.md now documents the real container invocation paths (KNEL-AIMiddleware/{redmine,discourse}-cli/), not the missing bin/ shortcuts. -- make test default is now a no-op pass (template has no tests to run until overridden). -- make validate now fully passes on the template itself. +- scripts/test.sh default is now a no-op pass (template has no tests to run until overridden). +- scripts/check-rules.sh now fully passes on the template itself. ## In Progress diff --git a/scripts/check-rules.sh b/scripts/check-rules.sh index 8407e06..82d117f 100755 --- a/scripts/check-rules.sh +++ b/scripts/check-rules.sh @@ -107,7 +107,7 @@ fi # 3. Required-files manifest โ€” the files every project using this template owns. # ---------------------------------------------------------------------------- $RULE_VERBOSE && log_step "Required files" -REQUIRED_FILES="AGENTS.md STATUS.md questions-v1.md .env.example Makefile scripts/check-rules.sh scripts/setup-hooks.sh" +REQUIRED_FILES="AGENTS.md STATUS.md questions-v1.md .env.example scripts/check-rules.sh scripts/setup-hooks.sh" REQUIRED_FILES="$REQUIRED_FILES ${PROJECT_REQUIRED_FILES:-}" for f in $REQUIRED_FILES; do if [ -f "$f" ]; then check "$f exists" "pass"; else check "$f MISSING" "fail"; fi @@ -231,14 +231,14 @@ if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then fi # ---------------------------------------------------------------------------- -# 10. (slow, skipped in --fast) Project test suite via `make test` if present. +# 10. (slow, skipped in --fast) Project test suite via scripts/test.sh. # ---------------------------------------------------------------------------- -if [ "$RULE_FAST" = false ] && [ -f Makefile ] && grep -qE '^test:' Makefile; then - $RULE_VERBOSE && log_step "Test suite (make test)" - if make test >/dev/null 2>&1; then - check "make test passes" "pass" +if [ "$RULE_FAST" = false ] && [ -x scripts/test.sh ]; then + $RULE_VERBOSE && log_step "Test suite (scripts/test.sh)" + if bash scripts/test.sh >/dev/null 2>&1; then + check "scripts/test.sh passes" "pass" else - check "make test FAILS" "fail" + check "scripts/test.sh FAILS" "fail" fi fi diff --git a/scripts/garden.sh b/scripts/garden.sh index 672d60b..67b0592 100755 --- a/scripts/garden.sh +++ b/scripts/garden.sh @@ -3,7 +3,7 @@ # # Reports doc sprawl and files that violate the "Discourse is the system of # record for documentation; gitea .md files are stubs" policy. Run via -# `make garden`. Findings are WARNINGS (advisory); fix them at a natural break. +# `bash scripts/garden.sh`. Findings are WARNINGS (advisory); fix them at a natural break. # # What it checks: # 1. Markdown sprawl: count of .md files per directory (top-10 by count). diff --git a/scripts/setup-hooks.sh b/scripts/setup-hooks.sh index e0de950..57219ac 100755 --- a/scripts/setup-hooks.sh +++ b/scripts/setup-hooks.sh @@ -37,7 +37,7 @@ Git hooks installed. The following now run automatically: required files, doc freshness, Discourse pointers, WORKING.md completion, hygiene). Hot-path bypass for STATUS.md / WORKING.md. - pre-push full rule audit (includes make test) + clean-working-tree gate. + pre-push full rule audit (includes scripts/test.sh) + clean-working-tree gate. Bypass either with \`git commit --no-verify\` / \`git push --no-verify\` (emergencies only). diff --git a/scripts/test.sh b/scripts/test.sh new file mode 100755 index 0000000..87efd2f --- /dev/null +++ b/scripts/test.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +# test.sh โ€” project test runner. +# Override this per project. Default: no-op pass. +# Invoked by check-rules.sh (full audit) and pre-push. +set -euo pipefail +echo "test.sh: no tests defined โ€” override this in your project."