diff --git a/README.md b/README.md index 2c77933..a3c22c9 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,12 @@ Give every repository the same predictable anchor points: | `-- project.md |-- .gitea/ | `-- workflows/ -| `-- build.yml +| |-- security-scan.yml +| |-- repo-cleanup.yml +| |-- dependency-check.yml +| |-- release-dry-run.yml +| |-- build.yml +| `-- template-compliance.yml |-- docs/ | |-- release-checklist.md | `-- security-review.md @@ -49,7 +54,7 @@ Give every repository the same predictable anchor points: `-- .gitignore ``` -Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `README.md`, `SECURITY.md`, and `CHANGELOG.md` may be enough. For an app or releasable tool, add the runner, release checklist, and README blueprint workflow. +Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `README.md`, `SECURITY.md`, and `CHANGELOG.md` may be enough. For an app or releasable tool, add the runner, release checklist, useful scheduled checks, and README blueprint workflow.

-----------------------------------------------------

@@ -62,6 +67,9 @@ Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `R | `files/build-gitea.yml` | `.gitea/workflows/build.yml` | | `files/security-scan-gitea.yml` | `.gitea/workflows/security-scan.yml` | | `files/repo-cleanup-gitea.yml` | `.gitea/workflows/repo-cleanup.yml` | +| `files/dependency-check-gitea.yml` | `.gitea/workflows/dependency-check.yml` | +| `files/release-dry-run-gitea.yml` | `.gitea/workflows/release-dry-run.yml` | +| `files/template-compliance-gitea.yml` | `.gitea/workflows/template-compliance.yml` | | `files/release-checklist.md` | `docs/release-checklist.md` | | `files/security-review.md` | `docs/security-review.md` | | `files/blueprint.md` | `blueprint.md` | @@ -127,6 +135,7 @@ When applying this kit, an agent should: - update security and release docs when release behavior changes, - add or preserve scheduled security automation for releasable projects, - add or preserve scheduled repository cleanup checks for active projects, +- add dependency, release dry-run, and template compliance checks when they fit the project, - update `docs/agent-handoff.md` when work is interrupted, risky, or multi-session, - run `git diff --check` before finishing, - run the cheapest reliable verification command, @@ -164,6 +173,36 @@ The workflow is intentionally non-destructive. It must not delete files, branche

-----------------------------------------------------

+## Dependency Automation + +`files/dependency-check-gitea.yml` provides a weekly dependency health report. + +It detects common stacks and reports: + +- security audit results, +- outdated Node, Python, Rust, and Go dependencies, +- Docker base image references that should be reviewed manually. + +The workflow does not update lockfiles, create pull requests, or publish packages. Agents should use the report as a starting point for focused dependency update branches. + +

-----------------------------------------------------

+ +## Release Dry Run + +`files/release-dry-run-gitea.yml` checks whether a project looks ready to release without creating a release. + +It checks release documents, unresolved placeholders, stack-specific build/test commands where they can be detected, and likely artifact directories. It must not create tags, releases, packages, or uploaded artifacts. + +

-----------------------------------------------------

+ +## Template Compliance + +`files/template-compliance-gitea.yml` checks whether a repository still follows the Codex kit baseline. + +It verifies required agent context files, unresolved placeholders, README divider usage for generated READMEs, and recommended workflow presence. Treat failures as maintenance guidance, not as a reason to overwrite project-specific documentation blindly. + +

-----------------------------------------------------

+ ## Gitea API Token When working with private repositories on `git.wilkensxl.de`, Codex agents may find a local `GITEA_TOKEN` environment variable on the machine. diff --git a/agent-quickstart.md b/agent-quickstart.md index 0d0440e..525302f 100644 --- a/agent-quickstart.md +++ b/agent-quickstart.md @@ -11,6 +11,7 @@ Use new-repository.md or existing-project.md as the task workflow. Use matching profiles/*.md guidance after detecting the stack. For releasable projects, add or preserve scheduled security automation. For active projects, add or preserve non-destructive scheduled repository cleanup checks. +For Codex-maintained projects, add or preserve dependency, release dry-run, and template compliance checks when useful. Check git status before editing. Preserve unrelated user changes. Replace all applicable placeholders and remove non-applicable placeholder sections. @@ -84,6 +85,18 @@ Is this an active repository with generated files, artifacts, or branches? yes -> add .gitea/workflows/repo-cleanup.yml or preserve equivalent cleanup checks no -> cleanup automation can be skipped +Is this an active project with dependencies? + yes -> add .gitea/workflows/dependency-check.yml or preserve equivalent dependency checks + no -> dependency automation can be skipped + +Is this project releasable? + yes -> add .gitea/workflows/release-dry-run.yml or preserve equivalent release dry-run checks + no -> release dry-run can be skipped + +Is this project intended to stay Codex-maintained? + yes -> add .gitea/workflows/template-compliance.yml or preserve equivalent template checks + no -> template compliance can be skipped + Are commands unknown? yes -> document PENDING in .codex/project.md no -> wire commands into AGENTS.md and CI @@ -135,6 +148,9 @@ docs/agent-handoff.md .gitea/workflows/build.yml .gitea/workflows/security-scan.yml .gitea/workflows/repo-cleanup.yml +.gitea/workflows/dependency-check.yml +.gitea/workflows/release-dry-run.yml +.gitea/workflows/template-compliance.yml ``` For README-generator projects: diff --git a/existing-project.md b/existing-project.md index 52ea211..9bdb156 100644 --- a/existing-project.md +++ b/existing-project.md @@ -124,6 +124,12 @@ For releasable projects, add `.gitea/workflows/security-scan.yml` unless the rep For active repositories, add `.gitea/workflows/repo-cleanup.yml` unless equivalent cleanup checks already exist. Keep cleanup automation non-destructive and document intentional exceptions. +For projects with dependencies, add `.gitea/workflows/dependency-check.yml` unless equivalent dependency update or dependency audit checks already exist. Keep it report-only. + +For releasable projects, add `.gitea/workflows/release-dry-run.yml` unless equivalent release readiness checks already exist. It must not tag, publish, or create releases. + +For Codex-maintained projects, add `.gitea/workflows/template-compliance.yml` unless equivalent agent-context checks already exist. Preserve documented project-specific exceptions. + ### 6. Security Review Fill `docs/security-review.md` with known facts. diff --git a/files/AGENTS.md b/files/AGENTS.md index 3972ee4..2f2d82d 100644 --- a/files/AGENTS.md +++ b/files/AGENTS.md @@ -22,7 +22,9 @@ PROJECT_NAME: PROJECT_DESCRIPTION - If README blueprint files are changed, regenerate or update `README.md` in the same change and verify the generated output renders reasonably. - For releasable projects, add or preserve `.gitea/workflows/security-scan.yml` using `files/security-scan-gitea.yml` unless the repository already has equivalent scheduled security automation. - For active projects, add or preserve `.gitea/workflows/repo-cleanup.yml` using `files/repo-cleanup-gitea.yml` unless the repository already has equivalent cleanup checks. +- Add or preserve `.gitea/workflows/dependency-check.yml`, `.gitea/workflows/release-dry-run.yml`, and `.gitea/workflows/template-compliance.yml` when the repository is active, releasable, or intended as a Codex-maintained project. - Repository cleanup automation must be non-destructive. Do not delete branches, packages, releases, or tracked files without explicit user approval. +- Dependency, compliance, and release dry-run automation must report findings only. Do not auto-update dependencies, auto-open PRs, create tags, publish packages, or create releases without explicit user approval. ## Commands @@ -59,6 +61,7 @@ ARTIFACT_NAME - Fill `docs/security-review.md` with actual checked commands and results when performing release-readiness work. - Review scheduled security workflow failures before changing code. Treat matches as leads: they may be true positives, documentation examples, or test fixtures. - Review repository cleanup workflow failures as maintenance leads. Document intentional exceptions instead of blindly deleting files. +- Review dependency and template compliance workflow failures as maintenance leads. Preserve project-specific conventions when they are documented. - Treat generated credentials and config files as sensitive. - Keep external network calls documented. - Prefer local processing for user data. diff --git a/files/dependency-check-gitea.yml b/files/dependency-check-gitea.yml new file mode 100644 index 0000000..f601304 --- /dev/null +++ b/files/dependency-check-gitea.yml @@ -0,0 +1,114 @@ +name: Scheduled Dependency Check + +on: + schedule: + - cron: "29 3 * * 2" + workflow_dispatch: + +jobs: + dependency-check: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Detect project stack + id: detect + shell: bash + run: | + stacks="" + + [ -f package.json ] && stacks="${stacks} node" + { [ -f pyproject.toml ] || [ -f requirements.txt ]; } && stacks="${stacks} python" + [ -f Cargo.toml ] && stacks="${stacks} rust" + [ -f go.mod ] && stacks="${stacks} go" + { [ -f Dockerfile ] || [ -f compose.yml ] || [ -f docker-compose.yml ]; } && stacks="${stacks} docker" + + echo "stacks=${stacks:-generic}" >> "$GITHUB_OUTPUT" + echo "Detected stacks:${stacks:- generic}" + + - name: Node dependency report + if: contains(steps.detect.outputs.stacks, 'node') + shell: bash + run: | + if [ -f package-lock.json ] || [ -f npm-shrinkwrap.json ]; then + npm ci + else + npm install --package-lock-only --ignore-scripts + fi + + echo "Security audit:" + npm audit --omit=dev --audit-level=high + + echo + echo "Outdated dependencies:" + npm outdated || true + + - name: Python dependency report + if: contains(steps.detect.outputs.stacks, 'python') + shell: bash + run: | + python -m pip install --upgrade pip pip-audit + + echo "Security audit:" + if [ -f requirements.txt ]; then + pip-audit -r requirements.txt + else + pip-audit + fi + + echo + echo "Outdated packages:" + python -m pip list --outdated || true + + - name: Rust dependency report + if: contains(steps.detect.outputs.stacks, 'rust') + shell: bash + run: | + cargo install cargo-audit cargo-outdated --locked + + echo "Security audit:" + cargo audit + + echo + echo "Outdated crates:" + cargo outdated || true + + - name: Go dependency report + if: contains(steps.detect.outputs.stacks, 'go') + shell: bash + run: | + go install golang.org/x/vuln/cmd/govulncheck@latest + + echo "Security audit:" + govulncheck ./... + + echo + echo "Available dependency updates:" + go list -u -m all || true + + - name: Docker base image report + if: contains(steps.detect.outputs.stacks, 'docker') + shell: bash + run: | + echo "Docker image references:" + grep -RInE --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=build '^\s*FROM\s+' Dockerfile* . 2>/dev/null || true + + echo + echo "Review Docker base images manually for pinned versions, official sources, and current security status." + + - name: Dependency guidance + shell: bash + run: | + cat <<'EOF' + Dependency check completed. + + This workflow reports vulnerabilities and available updates. It does + not modify dependency files, create pull requests, or publish packages. + + Recommended manual follow-up: + - update dependencies in a focused branch, + - run the project test/build commands, + - review lockfile diffs carefully, + - document intentionally held versions. + EOF diff --git a/files/release-dry-run-gitea.yml b/files/release-dry-run-gitea.yml new file mode 100644 index 0000000..25e61ab --- /dev/null +++ b/files/release-dry-run-gitea.yml @@ -0,0 +1,133 @@ +name: Release Dry Run + +on: + push: + branches: + - main + - master + workflow_dispatch: + +jobs: + release-dry-run: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Inspect release metadata + shell: bash + run: | + missing=0 + + required_docs=( + "README.md" + "CHANGELOG.md" + "SECURITY.md" + "docs/release-checklist.md" + ) + + for file in "${required_docs[@]}"; do + if [ ! -f "$file" ]; then + echo "Missing release document: $file" + missing=1 + fi + done + + placeholder_paths=(README.md AGENTS.md .codex docs) + placeholder_pattern='PROJECT_NAME|PROJECT_DESCRIPTION|REPOSITORY_OWNER|REPOSITORY_NAME|PACKAGE_NAME|ARTIFACT_NAME|ARTIFACT_OUTPUT_DIRECTORY|DOWNLOAD_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND' + + for path in "${placeholder_paths[@]}"; do + [ -e "$path" ] || continue + if grep -RInE --exclude-dir=.git "$placeholder_pattern" "$path"; then + echo "Unresolved template placeholders found." + missing=1 + fi + done + + if [ "$missing" -eq 1 ]; then + exit 1 + fi + + - name: Detect project stack + id: detect + shell: bash + run: | + stacks="" + + [ -f package.json ] && stacks="${stacks} node" + { [ -f pyproject.toml ] || [ -f requirements.txt ]; } && stacks="${stacks} python" + [ -f Cargo.toml ] && stacks="${stacks} rust" + [ -f go.mod ] && stacks="${stacks} go" + + echo "stacks=${stacks:-generic}" >> "$GITHUB_OUTPUT" + echo "Detected stacks:${stacks:- generic}" + + - name: Node release checks + if: contains(steps.detect.outputs.stacks, 'node') + shell: bash + run: | + if [ -f package-lock.json ] || [ -f npm-shrinkwrap.json ]; then + npm ci + else + npm install + fi + + node -e "const p=require('./package.json'); if(!p.name||!p.version){throw new Error('package.json needs name and version')}; console.log(p.name+'@'+p.version)" + + npm run lint --if-present + npm test --if-present + npm run build --if-present + npm run release:check --if-present + + - name: Python release checks + if: contains(steps.detect.outputs.stacks, 'python') + shell: bash + run: | + python -m pip install --upgrade pip + + if [ -f requirements.txt ]; then + python -m pip install -r requirements.txt + fi + + if [ -f pyproject.toml ]; then + python -m pip install build + python -m build + else + echo "No pyproject.toml found; skipped Python package build." + fi + + - name: Rust release checks + if: contains(steps.detect.outputs.stacks, 'rust') + shell: bash + run: | + cargo test + cargo build --release + + - name: Go release checks + if: contains(steps.detect.outputs.stacks, 'go') + shell: bash + run: | + go test ./... + go build ./... + + - name: Artifact report + shell: bash + run: | + echo "Potential release artifacts:" + find . \ + -path ./.git -prune -o \ + -path ./node_modules -prune -o \ + -path './dist/*' -type f -print -o \ + -path './build/*' -type f -print -o \ + -path './release/*' -type f -print -o \ + -path './target/release/*' -type f -print \ + | sed 's#^\./##' \ + | head -200 + + cat <<'EOF' + + Release dry run completed. + + This workflow verifies release readiness. It does not create tags, + releases, packages, or upload artifacts. + EOF diff --git a/files/template-compliance-gitea.yml b/files/template-compliance-gitea.yml new file mode 100644 index 0000000..9700a7a --- /dev/null +++ b/files/template-compliance-gitea.yml @@ -0,0 +1,109 @@ +name: Codex Template Compliance + +on: + push: + branches: + - main + - master + pull_request: + workflow_dispatch: + +jobs: + template-compliance: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Check required Codex files + shell: bash + run: | + missing=0 + + required_files=( + "AGENTS.md" + ".codex/project.md" + "README.md" + ) + + recommended_files=( + "SECURITY.md" + "CHANGELOG.md" + "docs/agent-handoff.md" + ) + + for file in "${required_files[@]}"; do + if [ ! -f "$file" ]; then + echo "Missing required Codex file: $file" + missing=1 + fi + done + + for file in "${recommended_files[@]}"; do + if [ ! -f "$file" ]; then + echo "Recommended Codex file not found: $file" + fi + done + + if [ "$missing" -eq 1 ]; then + exit 1 + fi + + - name: Check unresolved placeholders + shell: bash + run: | + found=0 + paths=(AGENTS.md README.md SECURITY.md CHANGELOG.md .codex docs blueprint.md blueprint.json) + pattern='PROJECT_NAME|PROJECT_DESCRIPTION|REPOSITORY_OWNER|REPOSITORY_NAME|PACKAGE_NAME|ARTIFACT_NAME|ARTIFACT_OUTPUT_DIRECTORY|AUTHOR_NAME|PROJECT_STACK|DOWNLOAD_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND|README_COMMAND|INSTALL_COMMAND|DEV_COMMAND|PACKAGE_MANAGER|PROJECT_VERSION' + + for path in "${paths[@]}"; do + [ -e "$path" ] || continue + if grep -RInE --exclude-dir=.git "$pattern" "$path"; then + found=1 + fi + done + + if [ "$found" -eq 1 ]; then + echo "Unresolved template placeholders found. Replace real values or mark genuinely unknown values as PENDING." + exit 1 + fi + + - name: Check README divider convention + shell: bash + run: | + if [ -f blueprint.md ] || [ -f blueprint.json ]; then + if ! grep -q 'template:section-line' blueprint.md 2>/dev/null; then + echo "README blueprint exists but does not use {{ template:section-line }}." + exit 1 + fi + fi + + - name: Check workflow baseline + shell: bash + run: | + echo "Detected Gitea workflows:" + find .gitea/workflows -maxdepth 1 -type f -name '*.yml' -print 2>/dev/null || true + + if [ ! -f ".gitea/workflows/security-scan.yml" ]; then + echo "Recommended workflow missing: .gitea/workflows/security-scan.yml" + fi + + if [ ! -f ".gitea/workflows/repo-cleanup.yml" ]; then + echo "Recommended workflow missing: .gitea/workflows/repo-cleanup.yml" + fi + + - name: Compliance guidance + shell: bash + run: | + cat <<'EOF' + Codex template compliance check completed. + + This workflow verifies agent context and template hygiene. It does + not change files automatically. + + Recommended manual follow-up: + - add missing required Codex context files, + - replace unresolved placeholders, + - keep README blueprint and README output aligned, + - document intentional exceptions in .codex/project.md. + EOF diff --git a/manifest.json b/manifest.json index 6a1eb39..af40a33 100644 --- a/manifest.json +++ b/manifest.json @@ -13,6 +13,7 @@ "Update docs/security-review.md during release-readiness work.", "Update docs/release-checklist.md when release behavior changes.", "Add or preserve non-destructive scheduled repository cleanup checks for active projects.", + "Add or preserve dependency, release dry-run, and template compliance checks when they fit the project.", "Run git diff --check before finishing.", "Run the cheapest reliable verification command or document why it could not run.", "After pushing workflow-triggering commits, poll Gitea workflow runs until success or a concrete blocker." @@ -40,6 +41,41 @@ ], "destructive": false }, + "dependencyAutomation": { + "workflow": "files/dependency-check-gitea.yml", + "target": ".gitea/workflows/dependency-check.yml", + "schedule": "weekly", + "checks": [ + "dependency vulnerability reports", + "outdated dependency reports", + "Docker base image references" + ], + "destructive": false + }, + "releaseDryRunAutomation": { + "workflow": "files/release-dry-run-gitea.yml", + "target": ".gitea/workflows/release-dry-run.yml", + "trigger": "push and manual", + "checks": [ + "release documentation presence", + "unresolved placeholder scan", + "stack-specific build/test checks", + "artifact discovery" + ], + "publishes": false + }, + "templateComplianceAutomation": { + "workflow": "files/template-compliance-gitea.yml", + "target": ".gitea/workflows/template-compliance.yml", + "trigger": "push, pull request, and manual", + "checks": [ + "required Codex files", + "unresolved placeholders", + "README divider convention", + "recommended workflow presence" + ], + "destructive": false + }, "readmeDivider": { "templateName": "section-line", "source": "https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png", @@ -126,6 +162,21 @@ "source": "files/repo-cleanup-gitea.yml", "target": ".gitea/workflows/repo-cleanup.yml", "required": false + }, + { + "source": "files/dependency-check-gitea.yml", + "target": ".gitea/workflows/dependency-check.yml", + "required": false + }, + { + "source": "files/release-dry-run-gitea.yml", + "target": ".gitea/workflows/release-dry-run.yml", + "required": false + }, + { + "source": "files/template-compliance-gitea.yml", + "target": ".gitea/workflows/template-compliance.yml", + "required": false } ], "placeholders": [ diff --git a/manifest.schema.json b/manifest.schema.json index 649d507..2af585a 100644 --- a/manifest.schema.json +++ b/manifest.schema.json @@ -79,6 +79,78 @@ } } }, + "dependencyAutomation": { + "type": "object", + "required": ["workflow", "target", "schedule", "checks", "destructive"], + "properties": { + "workflow": { + "type": "string" + }, + "target": { + "type": "string" + }, + "schedule": { + "type": "string" + }, + "checks": { + "type": "array", + "items": { + "type": "string" + } + }, + "destructive": { + "type": "boolean" + } + } + }, + "releaseDryRunAutomation": { + "type": "object", + "required": ["workflow", "target", "trigger", "checks", "publishes"], + "properties": { + "workflow": { + "type": "string" + }, + "target": { + "type": "string" + }, + "trigger": { + "type": "string" + }, + "checks": { + "type": "array", + "items": { + "type": "string" + } + }, + "publishes": { + "type": "boolean" + } + } + }, + "templateComplianceAutomation": { + "type": "object", + "required": ["workflow", "target", "trigger", "checks", "destructive"], + "properties": { + "workflow": { + "type": "string" + }, + "target": { + "type": "string" + }, + "trigger": { + "type": "string" + }, + "checks": { + "type": "array", + "items": { + "type": "string" + } + }, + "destructive": { + "type": "boolean" + } + } + }, "workflows": { "type": "object", "required": ["newRepository", "existingProject", "quickstart"], diff --git a/new-repository.md b/new-repository.md index bfe1ec6..497ac8f 100644 --- a/new-repository.md +++ b/new-repository.md @@ -52,6 +52,9 @@ files/blueprint.json -> blueprint.json files/build-gitea.yml -> .gitea/workflows/build.yml files/security-scan-gitea.yml -> .gitea/workflows/security-scan.yml files/repo-cleanup-gitea.yml -> .gitea/workflows/repo-cleanup.yml +files/dependency-check-gitea.yml -> .gitea/workflows/dependency-check.yml +files/release-dry-run-gitea.yml -> .gitea/workflows/release-dry-run.yml +files/template-compliance-gitea.yml -> .gitea/workflows/template-compliance.yml ``` Skip `build-gitea.yml` when the project has no CI target yet. Skip README blueprint files when the project should keep a very small manual README. @@ -162,6 +165,12 @@ For releasable projects, config tools, apps, or repositories that process user d For active repositories, also add `.gitea/workflows/repo-cleanup.yml`. It should report cleanup candidates only; it must not delete files, branches, packages, or releases automatically. +For projects with dependencies, add `.gitea/workflows/dependency-check.yml`. It should report dependency health only; it must not edit dependency manifests or lockfiles automatically. + +For releasable projects, add `.gitea/workflows/release-dry-run.yml`. It should verify release readiness only; it must not create tags, releases, packages, or artifacts automatically. + +For Codex-maintained projects, add `.gitea/workflows/template-compliance.yml`. It should verify agent context and template hygiene without overwriting project-specific conventions. + ### 7. Finish Before final response: