diff --git a/.coderabbit 2.yaml b/.coderabbit 2.yaml deleted file mode 100644 index 323e688..0000000 --- a/.coderabbit 2.yaml +++ /dev/null @@ -1,6 +0,0 @@ -reviews: - auto_review: - enabled: false - -chat: - auto_reply: false diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 58eb1f0..adf452f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,6 +12,16 @@ jobs: contents: read steps: - uses: actions/checkout@v6.0.2 + - name: Reject iCloud sync-conflict files + # iCloud Drive appends " 2", " 3", … to filenames on a sync conflict. + # These must never be committed; fail the build if any are tracked. + run: | + matches="$(git ls-files | grep -E ' [0-9]+(\.[^/]+)?$' || true)" + if [ -n "$matches" ]; then + echo "::error::iCloud sync-conflict files are tracked in git:" + echo "$matches" + exit 1 + fi - uses: actions/setup-python@v6.2.0 with: python-version: "3.11" diff --git a/.gitignore b/.gitignore index 5c9f92d..e2f7a3d 100644 --- a/.gitignore +++ b/.gitignore @@ -215,4 +215,11 @@ Icon? .Spotlight-V100 .Trashes .VolumeIcon.icns -Thumbs.db \ No newline at end of file +Thumbs.db + +# iCloud Drive sync-conflict copies (e.g. "CONTEXT 2.md", ".coderabbit 2.yaml"). +# iCloud appends " 2", " 3", … to a filename on a sync conflict; never commit them. +# Patterns cover names with and without an extension. CI also rejects them. +*.icloud +* [0-9].* +* [0-9] \ No newline at end of file diff --git a/CONTEXT 2.md b/CONTEXT 2.md deleted file mode 100644 index a3fa2f9..0000000 --- a/CONTEXT 2.md +++ /dev/null @@ -1,71 +0,0 @@ -# codeforerunner Context - -codeforerunner is a prompt-first documentation tool for keeping repository knowledge aligned with code. Its language separates prompt-pack tasks from thin runtime wrappers. - -## Language - -**Architecture Review**: -A documentation task that surfaces repo-grounded opportunities to deepen modules and improve maintainability. The command/path name is `arch-review`; the human-facing title is Architecture Review. -_Avoid_: Architecture audit, refactor report - -**Deepening Opportunity**: -A candidate architecture improvement that hides more behavior behind a smaller interface, increasing leverage for callers and locality for maintainers. Architecture Reviews rank Deepening Opportunities but do not implement them. -_Avoid_: Refactor idea, cleanup item - -**Task Registry**: -A catalog of codeforerunner task identity and policy: task name, output role, refresh inclusion, scan exemption, and installable skill surface. It is the source agents and wrappers consult instead of rediscovering task facts from scattered files. -_Avoid_: Task list, command list - -**Prompt Session**: -A run-scoped interaction with codeforerunner prompt tasks that owns task lookup, scan-first enforcement, scan state, and bundle resolution. CLI and MCP code act as adapters to a Prompt Session rather than each reimplementing task ordering rules. -_Avoid_: Prompt runner, execution context - -**Distribution Inventory**: -A catalog of codeforerunner distribution artifacts and install policy: canonical skill, skill copies, per-task skills, marketplace manifest, managed markers, and default install destinations. Installer, doctor, and validators consult the Distribution Inventory instead of repeating packaging paths. -_Avoid_: Package list, artifact list - -**npm Publishing**: -The release path that makes the Node installer package available through npm-compatible registries. codeforerunner treats npmjs publishing, GitHub Packages publishing, and pinned installer shims as related but separately fixable release surfaces. -_Avoid_: JavaScript release, package upload - -**Release Surface Manifest**: -A catalog of release surfaces, versions, registry targets, authentication modes, and validation expectations for codeforerunner releases. npm Publishing uses it to keep npmjs, GitHub Packages, installer shims, and release PR checks aligned. -_Avoid_: Release checklist, publish config - -**Package Contents Inspector**: -A release validation module that checks the packed npm artifact before publish, including required files, executable entrypoints, skill payloads, lock metadata, and shim pins. It treats the package artifact as the test surface. -_Avoid_: npm pack script, file list check - -**Agent Onboarding**: -A task that creates or refreshes the instructions and domain vocabulary a coding agent needs before working in a repo. Agent Onboarding may create or update `CONTEXT.md` with conservative glossary terms inferred from stable repo evidence. -_Avoid_: Init docs, setup docs - -## Example Dialogue - -Dev: "Run arch-review on this repo." - -Domain expert: "That means produce an Architecture Review: ranked Deepening Opportunities, grounded in scan evidence, without changing code or proposing final interfaces yet." - -Dev: "Run init for this repo." - -Domain expert: "That means perform Agent Onboarding: update agent instructions and, when stable terms are evident, maintain the repo glossary in `CONTEXT.md`." - -Dev: "Add a new prompt task." - -Domain expert: "Register it in the Task Registry so wrappers, skills, docs, and refresh policy read the same task identity." - -Dev: "Why does scan-first logic exist in both CLI and MCP?" - -Domain expert: "That rule belongs to a Prompt Session: adapters should ask the session whether a task can run." - -Dev: "Where should canonical skill paths and marketplace paths live?" - -Domain expert: "In the Distribution Inventory, so installer, doctor, and validators share distribution facts." - -Dev: "Fix npm publishing." - -Domain expert: "Treat npm Publishing as three release surfaces: npmjs trusted publish, GitHub Packages publish, and installer shim pins." - -Dev: "How do we keep release workflows aligned?" - -Domain expert: "Use a Release Surface Manifest, then validate packed npm artifacts with a Package Contents Inspector before publish." diff --git a/plugins/codeforerunner/skills/forerunner-arch-review/SKILL 2.md b/plugins/codeforerunner/skills/forerunner-arch-review/SKILL 2.md deleted file mode 100644 index 46cd986..0000000 --- a/plugins/codeforerunner/skills/forerunner-arch-review/SKILL 2.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -name: forerunner-arch-review -description: Rank architecture improvement candidates. Use when the user wants architecture friction reviewed before planning refactors. ---- - -# forerunner-arch-review - -Produces an Architecture Review: ranked Deepening Opportunities that identify shallow modules, leaky seams, testability friction, and high-leverage refactor candidates. - -Inspired by Matt Pocock's `/improve-codebase-architecture` skill: -https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture - -## Activate when - -User asks to: review architecture, find deepening opportunities, identify shallow modules, assess refactor candidates, or improve codebase architecture. - -## Collect this context - -- Scan result (run `/forerunner-scan` first) -- Key module/package files from the scan result -- Existing tests for the modules under review -- `CONTEXT.md` or `CONTEXT-MAP.md` if present -- Relevant `docs/adr/*.md` files if present -- Existing architecture docs only when they clarify current design - -## Execute - -Run `forerunner generate --prompt-only arch-review` — outputs the assembled prompt bundle to stdout. Read this output and execute the architecture review task it describes. - -Without CLI, get the prompt from: -- `src/codeforerunner/prompts/tasks/arch-review.md` -- `src/codeforerunner/prompts/system/base.md` -- `src/codeforerunner/prompts/partials/output-rules.md` - -## Output - -`.forerunner/arch-review.md` with a top recommendation and 3-7 ranked Deepening Opportunities. Each candidate includes files/modules, problem, evidence, proposed direction, locality/leverage benefits, testing impact, risk/blast radius, and recommendation strength. Do not implement changes or propose final interfaces. diff --git a/skills/forerunner-arch-review/SKILL 2.md b/skills/forerunner-arch-review/SKILL 2.md deleted file mode 100644 index 46cd986..0000000 --- a/skills/forerunner-arch-review/SKILL 2.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -name: forerunner-arch-review -description: Rank architecture improvement candidates. Use when the user wants architecture friction reviewed before planning refactors. ---- - -# forerunner-arch-review - -Produces an Architecture Review: ranked Deepening Opportunities that identify shallow modules, leaky seams, testability friction, and high-leverage refactor candidates. - -Inspired by Matt Pocock's `/improve-codebase-architecture` skill: -https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture - -## Activate when - -User asks to: review architecture, find deepening opportunities, identify shallow modules, assess refactor candidates, or improve codebase architecture. - -## Collect this context - -- Scan result (run `/forerunner-scan` first) -- Key module/package files from the scan result -- Existing tests for the modules under review -- `CONTEXT.md` or `CONTEXT-MAP.md` if present -- Relevant `docs/adr/*.md` files if present -- Existing architecture docs only when they clarify current design - -## Execute - -Run `forerunner generate --prompt-only arch-review` — outputs the assembled prompt bundle to stdout. Read this output and execute the architecture review task it describes. - -Without CLI, get the prompt from: -- `src/codeforerunner/prompts/tasks/arch-review.md` -- `src/codeforerunner/prompts/system/base.md` -- `src/codeforerunner/prompts/partials/output-rules.md` - -## Output - -`.forerunner/arch-review.md` with a top recommendation and 3-7 ranked Deepening Opportunities. Each candidate includes files/modules, problem, evidence, proposed direction, locality/leverage benefits, testing impact, risk/blast radius, and recommendation strength. Do not implement changes or propose final interfaces. diff --git a/src/codeforerunner/prompts/tasks/arch-review 2.md b/src/codeforerunner/prompts/tasks/arch-review 2.md deleted file mode 100644 index c48595e..0000000 --- a/src/codeforerunner/prompts/tasks/arch-review 2.md +++ /dev/null @@ -1,121 +0,0 @@ -# Task: Architecture Review - -Inspired by Matt Pocock's `/improve-codebase-architecture` skill: -https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture - -Ranks repo-grounded Deepening Opportunities: architecture improvements that hide more behavior behind smaller interfaces, increasing leverage for callers and locality for maintainers. -Requires scan result as input. - -## Input - -- Scan result from `prompts/tasks/scan.md` -- File tree -- Key module/package files relevant to the scan result -- Existing tests for the modules under review -- `CONTEXT.md` or `CONTEXT-MAP.md` if present -- Relevant `docs/adr/*.md` files if present -- Existing architecture docs only when they clarify current design - -## Review Focus - -Look for architecture friction, not documentation drift: - -1. Modules that are shallow: interface complexity nearly matches implementation complexity -2. Concepts that require bouncing across many files to understand -3. Seams that leak implementation details into callers -4. Pure helpers extracted for testability while real behavior remains hard to test -5. Adapter seams with more abstraction than real variation -6. Missing or weak tests caused by poor locality - -Apply the deletion test to suspected shallow modules: if deleting the module makes complexity disappear, it was probably a pass-through; if complexity reappears across many callers, it was earning its keep. - -## Vocabulary - -Use these architecture terms consistently: - -- Module -- Interface -- Implementation -- Deep -- Shallow -- Seam -- Adapter -- Leverage -- Locality -- Deepening Opportunity -- Deletion test - -Use repo vocabulary from `CONTEXT.md` when present. If the repo lacks `CONTEXT.md` or the vocabulary is incomplete, infer temporary terms from evidence and list them under `## Suggested Glossary Additions`; do not write or rewrite `CONTEXT.md`. - -## Candidate Format - -For each Deepening Opportunity, include: - -- **Files/modules**: concrete files or modules involved -- **Problem**: architecture friction observed -- **Evidence**: repo evidence supporting the finding -- **Proposed direction**: plain-English direction only -- **Benefits**: locality and leverage improvements -- **Testing impact**: what becomes easier to verify, without final test code -- **Risk / blast radius**: likely scope and migration risk -- **Recommendation strength**: `Strong`, `Worth exploring`, or `Speculative` - -## Rules - -- Claims must derive from provided files. If evidence is absent, omit or document in `## Gaps`. -- Do not report stale README/API/diagram/doc drift; use `check`, `review`, `diagrams`, or `flows` for that. -- Do not propose final function signatures, dataclass fields, schema shapes, or file-by-file implementation plans. -- Do not mutate `CONTEXT.md` or create ADRs. -- Do not imply Matt Pocock endorses codeforerunner. -- Keep the highest-signal 3-7 candidates. Fewer is acceptable when evidence is thin. - -## Output Format - - - -# Architecture Review - -> Inspired by Matt Pocock's `/improve-codebase-architecture` skill: -> https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture - -## Summary - -One paragraph describing the main architecture pressure observed. - -## Top Recommendation - -Name the highest-value Deepening Opportunity and why it should be first. - -## Deepening Opportunities - -### 1. [Candidate Name] - -**Recommendation strength:** Strong | Worth exploring | Speculative - -**Files/modules:** ... - -**Problem:** ... - -**Evidence:** ... - -**Proposed direction:** ... - -**Benefits:** ... - -**Testing impact:** ... - -**Risk / blast radius:** ... - -## Suggested Glossary Additions - -Only include if `CONTEXT.md` is missing or incomplete. Suggest terms; do not write them. - -## Not Yet Decided - -- Final interface shapes -- Migration sequence -- Exact tests - -## Gaps - -List missing evidence that could materially change the review.