From 9ec5776a6c323a5c217e86ffd34bf168a5cd4965 Mon Sep 17 00:00:00 2001 From: Aurelio <19254254+Aureliolo@users.noreply.github.com> Date: Sat, 14 Mar 2026 19:10:03 +0100 Subject: [PATCH 1/2] fix: store CLA signatures on unprotected branch and declutter repo root - Change CLA signature storage from protected main branch to dedicated cla-signatures orphan branch (fixes contributor-assistant action failing due to branch protection rules) - Move CLA.md to .github/CLA.md (GitHub community files convention) - Move DESIGN_SPEC.md to docs/DESIGN_SPEC.md (it's a docs pointer) - Move .zizmor.yml to .github/.zizmor.yml (CI config belongs in .github) - Update all references across workflows, CLAUDE.md, README, skills, CONTRIBUTING, licensing docs, and getting_started --- .claude/skills/aurelio-review-pr/SKILL.md | 2 +- .claude/skills/pre-pr-review/SKILL.md | 2 +- .claude/skills/research-link/SKILL.md | 2 +- .claude/skills/worktree/SKILL.md | 2 +- .zizmor.yml => .github/.zizmor.yml | 0 CLA.md => .github/CLA.md | 2 +- .github/CONTRIBUTING.md | 2 +- .github/workflows/cla.yml | 6 +++--- .github/workflows/zizmor.yml | 6 +++--- CLAUDE.md | 6 +++--- README.md | 2 +- DESIGN_SPEC.md => docs/DESIGN_SPEC.md | 0 docs/getting_started.md | 2 +- docs/licensing.md | 4 ++-- 14 files changed, 19 insertions(+), 19 deletions(-) rename .zizmor.yml => .github/.zizmor.yml (100%) rename CLA.md => .github/CLA.md (98%) rename DESIGN_SPEC.md => docs/DESIGN_SPEC.md (100%) diff --git a/.claude/skills/aurelio-review-pr/SKILL.md b/.claude/skills/aurelio-review-pr/SKILL.md index d2190db652..629e283922 100644 --- a/.claude/skills/aurelio-review-pr/SKILL.md +++ b/.claude/skills/aurelio-review-pr/SKILL.md @@ -204,7 +204,7 @@ The **docs-consistency** agent ensures project documentation never drifts from t **What to check:** -Read the current `DESIGN_SPEC.md`, `CLAUDE.md`, and `README.md` in full. Then compare them against the PR diff and the actual current state of the codebase. Flag anything that is now inaccurate, incomplete, or missing. +Read the current `docs/DESIGN_SPEC.md`, `CLAUDE.md`, and `README.md` in full. Then compare them against the PR diff and the actual current state of the codebase. Flag anything that is now inaccurate, incomplete, or missing. **DESIGN_SPEC.md (CRITICAL — this is the project's source of truth):** 1. §15.3 Project Structure — does it match the actual files/directories under `src/ai_company/`? Any new modules missing? Any listed files that no longer exist? (CRITICAL) diff --git a/.claude/skills/pre-pr-review/SKILL.md b/.claude/skills/pre-pr-review/SKILL.md index 3d905f43b6..69530b2d9e 100644 --- a/.claude/skills/pre-pr-review/SKILL.md +++ b/.claude/skills/pre-pr-review/SKILL.md @@ -306,7 +306,7 @@ The docs-consistency agent ensures project documentation never drifts from the c **What to check:** -Read the current `DESIGN_SPEC.md`, `CLAUDE.md`, and `README.md` in full. Then compare them against the PR diff and the actual current state of the codebase. Flag anything that is now inaccurate, incomplete, or missing. +Read the current `docs/DESIGN_SPEC.md`, `CLAUDE.md`, and `README.md` in full. Then compare them against the PR diff and the actual current state of the codebase. Flag anything that is now inaccurate, incomplete, or missing. **DESIGN_SPEC.md (CRITICAL — this is the project's source of truth):** 1. §15.3 Project Structure — does it match the actual files/directories under `src/ai_company/`? Any new modules missing? Any listed files that no longer exist? (CRITICAL) diff --git a/.claude/skills/research-link/SKILL.md b/.claude/skills/research-link/SKILL.md index b0bd7977ae..9273b9ec77 100644 --- a/.claude/skills/research-link/SKILL.md +++ b/.claude/skills/research-link/SKILL.md @@ -24,7 +24,7 @@ Research any external content — URL, tool, concept, pasted article, code snipp ## Phase 0: Load Project Context -**Before doing anything else**, read `DESIGN_SPEC.md` in the project root. This is the authoritative source for the project's architecture, module design, technology choices, and risk register. You need this context loaded to produce accurate project mappings and verdicts in later phases. Read it in parallel with the Phase 1 content acquisition. +**Before doing anything else**, read `docs/DESIGN_SPEC.md` in the project root. This is the authoritative source for the project's architecture, module design, technology choices, and risk register. You need this context loaded to produce accurate project mappings and verdicts in later phases. Read it in parallel with the Phase 1 content acquisition. ## Phase 1: Identify Input Type and Acquire Content diff --git a/.claude/skills/worktree/SKILL.md b/.claude/skills/worktree/SKILL.md index b1d4f5de4d..750bbc814d 100644 --- a/.claude/skills/worktree/SKILL.md +++ b/.claude/skills/worktree/SKILL.md @@ -184,7 +184,7 @@ Directory suffix is auto-derived from the branch name: - #: ## Instructions - 1. Read `DESIGN_SPEC.md` sections: <list relevant §sections from issue bodies> + 1. Read `docs/DESIGN_SPEC.md` sections: <list relevant §sections from issue bodies> 2. Read the GitHub issues: <gh issue view commands> 3. Read the relevant source modules: <list directories/files matched from spec labels + dependency parsing> diff --git a/.zizmor.yml b/.github/.zizmor.yml similarity index 100% rename from .zizmor.yml rename to .github/.zizmor.yml diff --git a/CLA.md b/.github/CLA.md similarity index 98% rename from CLA.md rename to .github/CLA.md index a8288d2f2c..555dedc0d5 100644 --- a/CLA.md +++ b/.github/CLA.md @@ -100,7 +100,7 @@ or include Your Contributions in the Project. When you open your first pull request to SynthOrg, a bot will comment asking you to sign this CLA. To sign, reply to the bot's comment with the exact text it specifies. Your signature is stored in this repository at -`.github/cla-signatures.json`. +`.github/cla-signatures.json` on the `cla-signatures` branch. You only need to sign once — the agreement covers all future contributions. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 200c3a89e7..7fc599fdab 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -146,7 +146,7 @@ This project is licensed under [BUSL-1.1](../LICENSE) (Business Source License 1 ### Contributor License Agreement -Before your first contribution can be merged, you must sign the [Contributor License Agreement (CLA)](../CLA.md). This is required to enable dual-licensing (BSL + commercial licenses for enterprise customers). +Before your first contribution can be merged, you must sign the [Contributor License Agreement (CLA)](CLA.md). This is required to enable dual-licensing (BSL + commercial licenses for enterprise customers). **How to sign:** When you open your first pull request, a bot will post a comment asking you to sign. Simply reply with the text specified in the comment — no forms, no external services. Your signature is recorded as a JSON entry in this repository. diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml index e082b8e57c..c462212620 100644 --- a/.github/workflows/cla.yml +++ b/.github/workflows/cla.yml @@ -29,10 +29,10 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: path-to-signatures: .github/cla-signatures.json - path-to-document: CLA.md - branch: main + path-to-document: .github/CLA.md + branch: cla-signatures custom-notsigned-prcomment: | - Thank you for your contribution! Before we can merge this PR, you need to sign the [Contributor License Agreement](https://github.com/${{ github.repository }}/blob/main/CLA.md). + Thank you for your contribution! Before we can merge this PR, you need to sign the [Contributor License Agreement](https://github.com/${{ github.repository }}/blob/main/.github/CLA.md). **To sign**, please reply to this comment with the following exact text: diff --git a/.github/workflows/zizmor.yml b/.github/workflows/zizmor.yml index 90c1534ff2..e38ed66d82 100644 --- a/.github/workflows/zizmor.yml +++ b/.github/workflows/zizmor.yml @@ -6,13 +6,13 @@ on: paths: - ".github/workflows/**" - ".github/dependabot.yml" - - ".zizmor.yml" + - ".github/.zizmor.yml" pull_request: branches: [main] paths: - ".github/workflows/**" - ".github/dependabot.yml" - - ".zizmor.yml" + - ".github/.zizmor.yml" workflow_dispatch: permissions: {} @@ -33,5 +33,5 @@ jobs: - name: Run zizmor uses: zizmorcore/zizmor-action@71321a20a9ded102f6e9ce5718a2fcec2c4f70d8 # v0.5.2 with: - config: .zizmor.yml + config: .github/.zizmor.yml advanced-security: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }} diff --git a/CLAUDE.md b/CLAUDE.md index 7920e6225c..75a2e1591d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,11 +6,11 @@ - **Python**: 3.14+ (PEP 649 native lazy annotations) - **License**: BUSL-1.1 with narrowed Additional Use Grant (free production use for non-competing small orgs; converts to Apache 2.0 three years after release) - **Layout**: `src/ai_company/` (src layout), `tests/` (unit/integration/e2e), `web/` (Vue 3 dashboard), `cli/` (Go CLI binary) -- **Design**: [DESIGN_SPEC.md](DESIGN_SPEC.md) (pointer to `docs/design/` pages) +- **Design**: [DESIGN_SPEC.md](docs/DESIGN_SPEC.md) (pointer to `docs/design/` pages) ## Design Spec (MANDATORY) -- **ALWAYS read the relevant `docs/design/` page** before implementing any feature or planning any issue. [DESIGN_SPEC.md](DESIGN_SPEC.md) is a pointer file linking to the 7 design pages. +- **ALWAYS read the relevant `docs/design/` page** before implementing any feature or planning any issue. [DESIGN_SPEC.md](docs/DESIGN_SPEC.md) is a pointer file linking to the 7 design pages. - The design spec is the **starting point** for architecture, data models, and behavior - If implementation deviates from the spec (better approach found, scope evolved, etc.), **alert the user and explain why** — user decides whether to proceed or update the spec - Do NOT silently diverge — every deviation needs explicit user approval @@ -262,7 +262,7 @@ cli/ # Go CLI binary (cross-platform, manages Docker lifecycle) - **OSSF Scorecard**: `.github/workflows/scorecard.yml` — supply chain maturity scoring on push to main + weekly schedule. SARIF upload to Security tab. Contributes to OpenSSF ecosystem data via `publish_results: true`. - **DAST**: `.github/workflows/dast.yml` — ZAP API scan against the backend OpenAPI spec on push to main + weekly schedule. Builds backend image locally, starts container, runs ZAP. Results available as workflow artifacts (no SARIF — action v0.10.0 lacks native SARIF output). Not on PRs (too slow). - **Socket.dev**: GitHub App — supply chain attack detection on PRs (typosquatting, malware, suspicious ownership changes, obfuscated code). No config file needed, auto-comments on PRs. -- **CLA**: `.github/workflows/cla.yml` — Contributor License Agreement signature check on PRs via `contributor-assistant/github-action`. Triggers on `pull_request_target` and `issue_comment`. Skips Dependabot. Signatures stored in `.github/cla-signatures.json`. +- **CLA**: `.github/workflows/cla.yml` — Contributor License Agreement signature check on PRs via `contributor-assistant/github-action`. Triggers on `pull_request_target` and `issue_comment`. Skips Dependabot. Signatures stored in `.github/cla-signatures.json` on the `cla-signatures` branch (unprotected, so the action can commit directly). - **Release**: `.github/workflows/release.yml` — Release Please (Google) auto-creates a release PR on every push to main. Merging the release PR creates a git tag (`vX.Y.Z`) + GitHub Release with changelog. Tag push triggers the Docker workflow to build version-tagged images. Uses `RELEASE_PLEASE_TOKEN` secret (PAT/GitHub App token) so tag creation triggers downstream workflows (GITHUB_TOKEN cannot). Config in `.github/release-please-config.json` and `.github/.release-please-manifest.json`. After creating/updating a release PR, auto-updates the BSL Change Date in LICENSE to 3 years ahead. ## Dependencies diff --git a/README.md b/README.md index b642a2aa59..5e9e97d162 100644 --- a/README.md +++ b/README.md @@ -147,7 +147,7 @@ graph TB | [Developer Setup](docs/getting_started.md) | Clone, test, lint, contribute | | [User Guide](docs/user_guide.md) | Install, configure, run via Docker | -> **Contributors:** Start with the [Design Overview](docs/design/index.md) before implementing any feature — it is the mandatory starting point for architecture, data models, and behavior. [`DESIGN_SPEC.md`](DESIGN_SPEC.md) serves as a pointer to the full design set. +> **Contributors:** Start with the [Design Overview](docs/design/index.md) before implementing any feature — it is the mandatory starting point for architecture, data models, and behavior. [`DESIGN_SPEC.md`](docs/DESIGN_SPEC.md) serves as a pointer to the full design set. ## Status diff --git a/DESIGN_SPEC.md b/docs/DESIGN_SPEC.md similarity index 100% rename from DESIGN_SPEC.md rename to docs/DESIGN_SPEC.md diff --git a/docs/getting_started.md b/docs/getting_started.md index 09513fbc61..a7b3a6ddd1 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -124,7 +124,7 @@ synthorg/ web/ # Vue 3 web dashboard (PrimeVue + Tailwind CSS) .github/ # CI workflows, dependabot, actions pyproject.toml # Project config (deps, tools, linters) - DESIGN_SPEC.md # Pointer to design specification pages + docs/DESIGN_SPEC.md # Pointer to design specification pages CLAUDE.md # AI assistant quick reference ``` diff --git a/docs/licensing.md b/docs/licensing.md index 38a7d9426f..d3295569d1 100644 --- a/docs/licensing.md +++ b/docs/licensing.md @@ -11,7 +11,7 @@ | Production use by large org (500+ employees and contractors) | Conditional | Commercial license | | Offering SynthOrg as a hosted/managed service | Conditional | Commercial license | | Reselling or embedding SynthOrg as your core product | Conditional | Commercial license | -| Contributing to SynthOrg | Yes | Sign the [CLA](https://github.com/Aureliolo/synthorg/blob/main/CLA.md) | +| Contributing to SynthOrg | Yes | Sign the [CLA](https://github.com/Aureliolo/synthorg/blob/main/.github/CLA.md) | *"Conditional" uses require a commercial license — please [contact us](https://github.com/Aureliolo/synthorg/discussions) to discuss terms.* @@ -111,7 +111,7 @@ This means: ## Contributor License Agreement (CLA) -We require a [Contributor License Agreement](https://github.com/Aureliolo/synthorg/blob/main/CLA.md) before merging external contributions. The CLA: +We require a [Contributor License Agreement](https://github.com/Aureliolo/synthorg/blob/main/.github/CLA.md) before merging external contributions. The CLA: - Grants SynthOrg a non-exclusive license to your contributions - **Does not transfer ownership** — you retain full rights to your work From a571e5bae1e29fcbafa4d77983a3b89907436242 Mon Sep 17 00:00:00 2001 From: Aurelio <19254254+Aureliolo@users.noreply.github.com> Date: Sat, 14 Mar 2026 19:24:13 +0100 Subject: [PATCH 2/2] fix: point skills to docs/design/ pages instead of DESIGN_SPEC.md DESIGN_SPEC.md is just a pointer/index file. The actual design spec lives in docs/design/*.md pages. Update all 4 skill files to direct readers to the relevant design pages as the authoritative source. --- .claude/skills/aurelio-review-pr/SKILL.md | 4 ++-- .claude/skills/pre-pr-review/SKILL.md | 4 ++-- .claude/skills/research-link/SKILL.md | 2 +- .claude/skills/worktree/SKILL.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.claude/skills/aurelio-review-pr/SKILL.md b/.claude/skills/aurelio-review-pr/SKILL.md index 629e283922..58d5e9dba1 100644 --- a/.claude/skills/aurelio-review-pr/SKILL.md +++ b/.claude/skills/aurelio-review-pr/SKILL.md @@ -204,9 +204,9 @@ The **docs-consistency** agent ensures project documentation never drifts from t **What to check:** -Read the current `docs/DESIGN_SPEC.md`, `CLAUDE.md`, and `README.md` in full. Then compare them against the PR diff and the actual current state of the codebase. Flag anything that is now inaccurate, incomplete, or missing. +Read the current `CLAUDE.md` and `README.md` in full, plus the relevant `docs/design/` pages (see `docs/DESIGN_SPEC.md` for the index). Then compare them against the PR diff and the actual current state of the codebase. Flag anything that is now inaccurate, incomplete, or missing. -**DESIGN_SPEC.md (CRITICAL — this is the project's source of truth):** +**Design pages in `docs/design/` (CRITICAL — these are the project's source of truth):** 1. §15.3 Project Structure — does it match the actual files/directories under `src/ai_company/`? Any new modules missing? Any listed files that no longer exist? (CRITICAL) 2. §3.1 Agent Identity Card — does the config/runtime split documentation match the actual model code? (MAJOR) 3. §15.4 Key Design Decisions — are technology choices and rationale still accurate? (MAJOR) diff --git a/.claude/skills/pre-pr-review/SKILL.md b/.claude/skills/pre-pr-review/SKILL.md index 69530b2d9e..28bfe5566f 100644 --- a/.claude/skills/pre-pr-review/SKILL.md +++ b/.claude/skills/pre-pr-review/SKILL.md @@ -306,9 +306,9 @@ The docs-consistency agent ensures project documentation never drifts from the c **What to check:** -Read the current `docs/DESIGN_SPEC.md`, `CLAUDE.md`, and `README.md` in full. Then compare them against the PR diff and the actual current state of the codebase. Flag anything that is now inaccurate, incomplete, or missing. +Read the current `CLAUDE.md` and `README.md` in full, plus the relevant `docs/design/` pages (see `docs/DESIGN_SPEC.md` for the index). Then compare them against the PR diff and the actual current state of the codebase. Flag anything that is now inaccurate, incomplete, or missing. -**DESIGN_SPEC.md (CRITICAL — this is the project's source of truth):** +**Design pages in `docs/design/` (CRITICAL — these are the project's source of truth):** 1. §15.3 Project Structure — does it match the actual files/directories under `src/ai_company/`? Any new modules missing? Any listed files that no longer exist? (CRITICAL) 2. §3.1 Agent Identity Card — does the config/runtime split documentation match the actual model code? (MAJOR) 3. §15.4 Key Design Decisions — are technology choices and rationale still accurate? (MAJOR) diff --git a/.claude/skills/research-link/SKILL.md b/.claude/skills/research-link/SKILL.md index 9273b9ec77..edcc432baa 100644 --- a/.claude/skills/research-link/SKILL.md +++ b/.claude/skills/research-link/SKILL.md @@ -24,7 +24,7 @@ Research any external content — URL, tool, concept, pasted article, code snipp ## Phase 0: Load Project Context -**Before doing anything else**, read `docs/DESIGN_SPEC.md` in the project root. This is the authoritative source for the project's architecture, module design, technology choices, and risk register. You need this context loaded to produce accurate project mappings and verdicts in later phases. Read it in parallel with the Phase 1 content acquisition. +**Before doing anything else**, read the relevant `docs/design/` page(s) for the topic being researched (see `docs/DESIGN_SPEC.md` for the index of all design pages). These are the authoritative source for the project's architecture, module design, technology choices, and risk register. You need this context loaded to produce accurate project mappings and verdicts in later phases. Read in parallel with the Phase 1 content acquisition. ## Phase 1: Identify Input Type and Acquire Content diff --git a/.claude/skills/worktree/SKILL.md b/.claude/skills/worktree/SKILL.md index 750bbc814d..8b8f814c4f 100644 --- a/.claude/skills/worktree/SKILL.md +++ b/.claude/skills/worktree/SKILL.md @@ -184,7 +184,7 @@ Directory suffix is auto-derived from the branch name: - #<N>: <title> ## Instructions - 1. Read `docs/DESIGN_SPEC.md` sections: <list relevant §sections from issue bodies> + 1. Read the relevant `docs/design/` pages: <list pages matched from issue spec labels and §section references> 2. Read the GitHub issues: <gh issue view commands> 3. Read the relevant source modules: <list directories/files matched from spec labels + dependency parsing>