Skip to content

Commit bccf0b1

Browse files
martincjarvismartincjarvis
committed
chore: remediate repo standards gaps
1 parent 4990735 commit bccf0b1

104 files changed

Lines changed: 5475 additions & 420 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/nx-release.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Nx Release
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
branches:
7+
- main
8+
paths:
9+
- "skills/**"
10+
- "nx.json"
11+
- "package.json"
12+
- "package-lock.json"
13+
14+
permissions:
15+
contents: write
16+
17+
jobs:
18+
release:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v4
23+
with:
24+
fetch-depth: 0
25+
26+
- name: Setup Node
27+
uses: actions/setup-node@v4
28+
with:
29+
node-version-file: .nvmrc
30+
cache: npm
31+
32+
- name: Install dependencies
33+
run: npm ci
34+
35+
- name: Configure git user
36+
run: |
37+
git config user.name "github-actions[bot]"
38+
git config user.email "github-actions[bot]@users.noreply.github.com"
39+
40+
- name: Run Nx release (tags only)
41+
run: npx nx release --yes --skip-publish
42+
43+
- name: Push tags
44+
run: git push --follow-tags

‎.github/workflows/secretlint.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Secretlint
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
- main
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
secretlint:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout
17+
uses: actions/checkout@v4
18+
19+
- name: Setup Node
20+
uses: actions/setup-node@v4
21+
with:
22+
node-version-file: .nvmrc
23+
cache: npm
24+
25+
- name: Install dependencies
26+
run: npm ci
27+
28+
- name: Run secretlint
29+
run: npm run secretlint

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ node_modules/
66
.vs/
77
.idea/
88
.tmp/
9+
.nx/
910
.worktrees/
1011
.DS_Store

‎.husky/pre-commit‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,10 @@
1+
#!/bin/sh
2+
. "$(dirname "$0")/_/husky.sh"
3+
4+
branch="$(git symbolic-ref --quiet --short HEAD 2>/dev/null)"
5+
if [ "$branch" = "main" ]; then
6+
echo "Commit blocked: default branch is protected. Create a feature branch."
7+
exit 1
8+
fi
9+
110
npx lint-staged

‎AGENTS.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ with the goal of portability across multiple projects and adoption by teams.
2020
- Deployable components are versioned independently (semantic versioning + conventional commits)
2121
- During build and deployment, **only modified/impacted components** should be built/tested/deployed
2222
- Tags should be used in deployment records to track which component versions are deployed to environments
23+
- Default branch is protected: no direct commits to `main`; required checks include Docs Quality, Commit Lint, and Secretlint
24+
- Per-skill semantic version tags are created on `main` via Nx release using `skill/<name>/vX.Y.Z`
25+
- Release/deploy pipelines are out of scope for this repository
2326
- Reuse strategy:
2427
- Reusable functionality is developed in an application repo until stable, then extracted into standalone repos and versioned independently.
2528
- Co-location is required at the **narrowest meaningful scope** (not just “same repo”).

‎README.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,8 +74,14 @@ consistent with **DRY** and **YAGNI**.
7474
- Local verification: `npm run verify` (markdownlint + cspell).
7575
- Pre-commit: Husky runs `lint-staged` (prettier, markdownlint, cspell, secretlint) on staged files.
7676
- Commit messages: Husky enforces Conventional Commits via commitlint.
77-
- CI: GitHub Actions runs the same `npm run verify` gate on PRs and pushes to `main` when documentation or lint/spell config files change.
78-
- Branch protection: require the `Docs Quality` status check on `main` before merge.
77+
- CI: GitHub Actions runs `npm run verify` and `npm run secretlint` on PRs and pushes to `main`.
78+
- Branch protection: no direct pushes to `main`; require `Docs Quality`, `Commit Lint`, and `Secretlint` checks before merge.
79+
- CI/CD scope: this repo does not run release/deploy workflows; tag-based deployment is out of scope for now.
80+
81+
## Versioning
82+
83+
- Per-skill tags are created on `main` via Nx release using the format `skill/<name>/vX.Y.Z`.
84+
- Use `npx nx release --yes --skip-publish` in CI to create tags without publishing.
7985

8086
## Contributing
8187

‎docs/plans/2026-02-01-repo-standards-gap-remediation.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Repo Standards Gap Remediation
2+
3+
> Status: Delivered
4+
> Owner: Codex
5+
> Date: 2026-02-01
6+
7+
## Goal
8+
9+
Close the repo‑vs‑standards gaps identified in the gap analysis: enforce default‑branch guardrails, add CI secret scanning, document CI/CD scope (no release/deploy workflows), and define per‑skill tag conventions on `main`.
10+
11+
## Architecture
12+
13+
Documentation, CI/hook changes, and Nx monorepo tooling to support per‑skill versioning and tags. No runtime or behavioural code changes.
14+
15+
## Tech Stack
16+
17+
- PowerShell
18+
- Husky (git hooks)
19+
- GitHub Actions
20+
- Secretlint
21+
- Nx (monorepo orchestration + release)
22+
23+
## Assumptions
24+
25+
- Branch protection is configured in the hosting platform, but repo evidence must document expected settings.
26+
- Per‑skill versioning will be represented by Nx release tags on `main`.
27+
28+
## Alternatives Considered
29+
30+
1. Implement minimal guardrails and documentation (selected) to close current gaps.
31+
2. Build full release/deploy pipelines with tag‑based deployments (more complete, higher effort).
32+
3. Add per‑skill changelogs and manifests (more traceability, not required now).
33+
4. Custom per‑skill semver scripts (lighter, but not portable).
34+
35+
## Task Checklist
36+
37+
|ID|Task|Status|Verification|Evidence|
38+
|---|---|---|---|---|
39+
|1|Impact analysis (RED/GREEN/REFACTOR): list impacted files (hooks, workflows, README/AGENTS/skills docs, Nx config) and unimpacted areas; record in plan and update report if needed.|Done|Impacted/unimpacted list recorded|Plan notes|
40+
|2|Nx bootstrap (RED/GREEN/REFACTOR): add Nx to the repo, define each `skills/<name>` as a project, and configure Nx release for independent versioning and tags (`skill/<name>/vX.Y.Z`).|Done|`npx nx graph` runs; `npx nx release --dry-run` shows per-skill tags|`npx nx graph --file=.tmp/nx-graph.json`; dry-run verified for `architecture-testing` (full repo dry-run timed out).|
41+
|3|Default-branch guardrail (RED/GREEN/REFACTOR): add a Husky `pre-commit` check that blocks commits on `main` (or default branch) and document expected branch protection settings in README/AGENTS.|Done|Docs updated|`.husky/pre-commit`, `README.md`, `AGENTS.md`|
42+
|4|CI secret scanning (RED/GREEN/REFACTOR): add a GitHub Actions job to run `npm run secretlint` on PRs and `main` pushes (path filtered).|Done|Workflow file added|`.github/workflows/secretlint.yml`|
43+
|5|CI/CD scope documentation (RED/GREEN/REFACTOR): document that this repo has no release/deploy workflows and that tag-based deployment is out of scope for now; add explicit note in README and/or AGENTS.|Done|Docs updated|`README.md`, `AGENTS.md`|
44+
|6|Nx release tagging workflow (RED/GREEN/REFACTOR): add a CI workflow that runs Nx release on `main` merges and pushes tags.|Done|Workflow file added|`.github/workflows/nx-release.yml`|
45+
|7|Per-skill tag policy (RED/GREEN/REFACTOR): document Nx release usage, tag format, and when tags should be created; update relevant skill/docs.|Done|Docs updated and verified|`README.md`|
46+
|8|Verification + commit (RED/GREEN/REFACTOR): run `npm run verify`; run `npx nx release --dry-run` (sample project); fix lint/spell issues; commit on feature branch with conventional commit (no commits to `main`).|Done|`npm run verify` clean; dry-run clean|`npm run verify` passed; `npx nx release --dry-run --projects=architecture-testing` verified.|
47+
48+
Notes:
49+
50+
- Status values: Planned, In Progress, Done, Aborted.
51+
- When a task is Done, fill in Verification and Evidence (command output, link, or note).
52+
53+
## Impact Notes
54+
55+
Impacted: `package.json`, `package-lock.json`, `nx.json`, `skills/**/project.json`, `skills/**/package.json`, `.husky/pre-commit`, `.github/workflows/secretlint.yml`, `.github/workflows/nx-release.yml`, `README.md`, `AGENTS.md`, `.gitignore`, `cspell.json`, `docs/plans/2026-02-01-repo-standards-gap-remediation.md`.
56+
Unimpacted: runtime code, deployable components, application features.
57+
58+
## Progress Log
59+
60+
- 2026-02-01: Draft remediation plan created.
61+
- 2026-02-01: Nx bootstrap completed; graph generated and single-project release dry-run verified.
62+
- 2026-02-01: Guardrail, secretlint, CI/CD scope, and tag policy documentation updated.
63+
- 2026-02-01: Verification complete (`npm run verify`, `nx release --dry-run`).
64+
65+
## Finalisation
66+
67+
> Outcome: Delivered
68+
> Date: 2026-02-01
69+
70+
### Verification Summary
71+
72+
- `npm run verify`
73+
- `npx nx graph --file=.tmp/nx-graph.json --watch=false`
74+
- `npx nx release --dry-run --projects=architecture-testing --verbose`
75+
76+
### References
77+
78+
- `docs/reports/2026-02-01-repo-standards-gap-analysis.md`
79+
- `skills/branching-strategy-and-conventions/SKILL.md`
80+
- `skills/local-dev-experience/SKILL.md`
81+
- `skills/static-analysis-security/SKILL.md`
82+
- `skills/ci-cd-conformance/SKILL.md`
83+
- `skills/quality-gate-enforcement/SKILL.md`
84+
- `skills/monorepo-orchestration-setup/SKILL.md`

‎nx.json‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
{
2+
"$schema": "./node_modules/nx/schemas/nx-schema.json",
3+
"defaultBase": "main",
4+
"workspaceLayout": {
5+
"libsDir": "skills",
6+
"appsDir": "apps"
7+
},
8+
"release": {
9+
"changelog": {
10+
"projectChangelogs": false,
11+
"workspaceChangelog": false
12+
},
13+
"version": {
14+
"updateDependents": "never",
15+
"specifierSource": "conventional-commits",
16+
"fallbackCurrentVersionResolver": "disk",
17+
"currentVersionResolver": "git-tag"
18+
},
19+
"git": {
20+
"push": false,
21+
"commit": false,
22+
"tag": true
23+
},
24+
"projects": [
25+
"architecture-testing",
26+
"aspire-integration-testing",
27+
"automated-standards-enforcement",
28+
"best-practice-introduction",
29+
"brainstorming",
30+
"branching-strategy-and-conventions",
31+
"change-risk-rollback",
32+
"ci-cd-conformance",
33+
"component-boundary-ownership",
34+
"contract-consistency-validation",
35+
"dispatching-parallel-agents",
36+
"documentation-as-code",
37+
"documentation-scaffold",
38+
"environment-traceability",
39+
"executing-plans",
40+
"finishing-a-development-branch",
41+
"greenfield-baseline",
42+
"incremental-change-impact",
43+
"incremental-deployment",
44+
"library-extraction-stabilisation",
45+
"local-dev-experience",
46+
"modern-csharp-coding-standards",
47+
"monorepo-orchestration-setup",
48+
"observability-logging-baseline",
49+
"quality-gate-enforcement",
50+
"receiving-code-review",
51+
"release-tagging-plan",
52+
"repository-foundation-bootstrap",
53+
"requesting-code-review",
54+
"runtime-tooling-validation",
55+
"safe-brownfield-refactor",
56+
"scoped-colocation",
57+
"selective-build-test",
58+
"semantic-version-impact",
59+
"static-analysis-security",
60+
"structured-review-workflow",
61+
"subagent-driven-development",
62+
"systematic-debugging",
63+
"technical-debt-prioritisation",
64+
"test-driven-development",
65+
"testcontainers-integration-tests",
66+
"using-git-worktrees",
67+
"using-skill-library",
68+
"verification-and-handover",
69+
"walking-skeleton-delivery",
70+
"writing-plans",
71+
"writing-skills"
72+
],
73+
"projectsRelationship": "independent",
74+
"releaseTag": {
75+
"pattern": "skill/{projectName}/v{version}",
76+
"requireSemver": true
77+
}
78+
}
79+
}

0 commit comments

Comments
 (0)