V0.4.1/tweakking git story teller

AGENTS.md

@@ -47,35 +47,38 @@ Never modify skills maintained by others (e.g. `skill-creator` by Anthropic). If
 
 ## Local Install Sync
 
-Repo-managed skills live in three places that must stay in sync:
+Repo-managed skills live in four places that must stay in sync:
 
-- `skills/<name>/` — source control
+- `skills/<name>/` — source control (and source of truth for edits)
 - `~/.claude/skills/<name>/` — local Claude install
 - `~/.agents/skills/<name>/` — local global agent install
+- `~/.gemini/antigravity/skills/<name>/` — local Gemini Antigravity install
 
-Changes often start in `~/.claude/skills/<name>/`, then get mirrored to the repo and the global install:
+Changes often start in `~/.claude/skills/<name>/`, then get mirrored to the repo and the other local installs:
 
 - **Claude local → repo** (persist changes to source control):
   ```powershell
   Copy-Item "$HOME/.claude/skills/<name>/<file>" "skills/<name>/<file>" -Force
   ```
-- **Claude local → global agent install** (keep `~/.agents` current):
-  ```powershell
-  Copy-Item "$HOME/.claude/skills/<name>/<file>" "$HOME/.agents/skills/<name>/<file>" -Force
-  ```
-- **Repo → both local installs** (after pulling changes or cloning fresh):
+- **Claude local → agent installs** (keep `~/.agents` and Gemini current):
+  ```powershell
+  Copy-Item "$HOME/.claude/skills/<name>/<file>" "$HOME/.agents/skills/<name>/<file>" -Force
+  Copy-Item "$HOME/.claude/skills/<name>/<file>" "$HOME/.gemini/antigravity/skills/<name>/<file>" -Force
+  ```
+- **Repo → local installs** (after pulling changes or cloning fresh):
   ```powershell
   Copy-Item "skills/<name>/<file>" "$HOME/.claude/skills/<name>/<file>" -Force
   Copy-Item "skills/<name>/<file>" "$HOME/.agents/skills/<name>/<file>" -Force
+  Copy-Item "skills/<name>/<file>" "$HOME/.gemini/antigravity/skills/<name>/<file>" -Force
   ```
 
-If you edit the `~/.agents/skills/<name>/` copy first, mirror it back to the repo and to `~/.claude/skills/<name>/` using the same pattern.
+If you edit the `~/.agents/skills/<name>/` copy first, mirror it back to the repo and to `~/.claude/skills/<name>/` and `~/.gemini/antigravity/skills/<name>/` using the same pattern.
 
-When renaming a skill, update **all three** locations — the repo folder, the local Claude install folder, and the local global agent install folder. The folder name and the `name:` field in the SKILL.md frontmatter must match. A mismatch causes the skill to disappear from tooling or show stale instructions.
+When renaming a skill, update **all four** locations — the repo folder, the local Claude install folder, the local global agent install folder, and the local Gemini Antigravity install folder. The folder name and the `name:` field in the SKILL.md frontmatter must match. A mismatch causes the skill to disappear from tooling or show stale instructions.
 
 A sync mismatch means one side runs a stale version, which leads to confusing eval results and wasted iterations.
 
-After changing any repo-managed skill, sync the touched files across the repo copy, `~/.claude/skills/<name>/`, and `~/.agents/skills/<name>/` before considering the task done.
+After changing any repo-managed skill, sync the touched files across the repo copy, `~/.claude/skills/<name>/`, `~/.agents/skills/<name>/`, and `~/.gemini/antigravity/skills/<name>/` before considering the task done.
 
 ## Skill Directory Structure
 

CHANGELOG.md

@@ -6,6 +6,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-05-04
+
+This is a minor release focused on strengthening `git-story-teller` with complete-read grounding rules, optional subagent delegation, evidence-based language validation, and enhanced deterministic output artifacts. The skill now enforces that agents read full context and target stories as primary sources, supports delegation of independent target contexts to subagents, and provides tooling to detect and prevent unmeasured frequency or behavior claims without source evidence.
+
+### Added
+
+- Complete-read grounding rules in `git-story-teller` requiring agents to fully inspect target contexts and overview sources, with explicit guidance on using chunk indices and range reads to handle truncated output,
+- Optional subagent strategy in `git-story-teller` for delegating independent target contexts to isolated subagents, reducing prompt budget contention while maintaining strict grounding requirements,
+- Evidence-based language validation patterns and regex detection in `git-story-teller` to distinguish structural facts from unmeasured behavior claims, with explicit guidance on conditional language like "if you only need X, aggregate adds Y" instead of "most common" or "developers often" without evidence,
+- Public API summary generation in `story.cs` to help agents orient around consumer-facing types, inheritance chains, and key members before reading raw source,
+- Engineering signal map in `story.cs` highlighting source-backed validation guards, lifecycle callbacks, factories, hosting styles, and test evidence for narrative-driven explanations instead of mechanical API lists,
+- Conservative test ownership mapping in `story.cs` preferring dedicated test projects with matching names over downstream package tests, only using direct references as fallback, and leaving Test path undiscovered when no unambiguous match exists,
+- Chunked context navigation in `story.cs` with `*.context.index.md` and ordered `*.context.chunks/*.md` files alongside full contexts for robust reading even when tools cap single-file output.
+
+### Changed
+
+- Refined `git-story-teller` SKILL.md with explicit complete-read contract, mandatory target-story sourcing for overview phase, subagent orchestration patterns, and conservative test mapping rules,
+- Enhanced `story.cs` to emit complete context files, public API summaries, engineering signal maps, conservative test ownership logic, context indexes, and ordered chunk files for improved agent navigation and grounding,
+- Updated README description and "Why git-story-teller?" section to document full output artifacts, public-API-first orientation, engineering signals, conservative test mapping, chunked navigation, and complete-read grounding,
+- Expanded AGENTS.md with four-way skill sync guidance including Gemini Antigravity install location and folder-name requirements,
+- Refined eval contracts for complete-read patterns, subagent coordination, evidence-based prose, target-story-sourced overview synthesis, and conservative test ownership mapping.
+
+### Fixed
+
+- Clarified validator and documentation alignment to enforce complete-read requirements, evidence-based language rules, and target-story sourcing for overview workflows,
+- Refined conservative test project matching to use exact suffix matching instead of stripping, preventing false positives when project names contain partial test-suffix overlap,
+- Updated eval 11 expectations to clarify handling of dedicated test projects with explicit "Tests" suffix patterns.
+
 ## [0.4.0] - 2026-05-03
 
 This is a minor release focused on deterministic repository story generation and foundational agent guidelines. It introduces a new `git-story-teller` skill with a bundled .NET context extractor, enhanced bot workspace management, and Karpathy programming principles for LLM agents.
@@ -157,7 +185,8 @@ This is a minor release that introduces two complementary git workflow skills, e
 
 - Improved scaffold fidelity with hidden `.bot` asset preservation, explicit UTF-8 and BOM handling, and checks aimed at preventing mojibake or incomplete generated output.
 
-[Unreleased]: https://github.com/codebeltnet/agentic/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/codebeltnet/agentic/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/codebeltnet/agentic/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/codebeltnet/agentic/compare/v0.3.4...v0.4.0
 [0.3.4]: https://github.com/codebeltnet/agentic/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/codebeltnet/agentic/compare/v0.3.2...v0.3.3

README.md

@@ -42,7 +42,7 @@ Use the skill tool to invoke the "<skill-name>" skill.
 
 ## Always-on skills
 
-Depending on the agent runtime, skills installed via `npx skills add` may live in `~/.claude/skills/` and/or `~/.agents/skills/`. Treat both as personal global skill folders: if you use both toolchains, keep repo-authored skills mirrored between them so each agent sees the same version. Either way, installed skills are **automatically loaded in every session** — no manual invocation needed. The agent reads the skill's description and activates it when relevant (e.g. you say "commit this" and the `git-visual-commits` skill kicks in).
+Depending on the agent runtime, skills installed via `npx skills add` may live in `~/.claude/skills/`, `~/.agents/skills/`, and/or `~/.gemini/antigravity/skills/`. Treat these as personal global skill folders: if you use multiple toolchains, keep repo-authored skills mirrored between them so each agent sees the same version. Either way, installed skills are **automatically loaded in every session** — no manual invocation needed. The agent reads the skill's description and activates it when relevant (e.g. you say "commit this" and the `git-visual-commits` skill kicks in).
 
 If you want a bundle of skills always available, just install them all:
 
@@ -68,10 +68,11 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-new-lib-sln
 |----------|-------|-------------|
 | `~/.agents/skills/` | All sessions, all projects | Global skills for agents that read the shared `~/.agents` install |
 | `~/.claude/skills/` | All sessions, all projects | Your personal defaults — always on everywhere |
+| `~/.gemini/antigravity/skills/` | All sessions, all projects | Gemini Antigravity skills kept in sync with repo-authored skill copies |
 | `.claude/skills/` (in a repo) | Project-scoped | Shared team conventions for a specific codebase |
 | `.github/skills/` (in a repo) | GitHub Copilot / VS Code | When your team uses Copilot agent mode in the IDE |
 
-> **Tip:** You can mix scopes. Install your personal favorites globally, and add project-specific skills to the repo so your whole team gets them. If you use both `~/.claude/skills/` and `~/.agents/skills/`, mirror repo-authored skills to both so sessions stay consistent.
+> **Tip:** You can mix scopes. Install your personal favorites globally, and add project-specific skills to the repo so your whole team gets them. If you use multiple personal skill folders, mirror repo-authored skills to each one so sessions stay consistent.
 
 ## Available Skills
 
@@ -84,7 +85,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-new-lib-sln
 | [git-visual-squash-summary](skills/git-visual-squash-summary/SKILL.md) | Non-mutating grouped-summary companion to `git-visual-commits`. Turns the full current feature branch into a curated set of compact summary lines for PR or squash-and-merge contexts by default, preserving technical identifiers, merging overlap, dropping low-signal noise, highlighting distinct meaningful efforts, and avoiding changelog-style wording, unsupported claims, needless commit-range questions, or commit-selection UI for ordinary branch-level squash requests. |
 | [skill-creator-agnostic](skills/skill-creator-agnostic/SKILL.md) | Runner-agnostic overlay for Anthropic `skill-creator`. Adds repo and environment guardrails for skill authoring and benchmarking: temp-workspace isolation, `iteration-N/eval-name/{config}/run-N/` benchmark layout, valid `grading.json` summaries, generated `benchmark.json`, honest `MEASURED` vs `SIMULATED` labeling, and sync/README discipline for repo-managed skills. |
 | [markdown-illustrator](skills/markdown-illustrator/SKILL.md) | Reads a markdown file and answers directly in chat with one document-wide Visual Brief plus one compiled prompt. Infers a compact visual strategy by default, keeps follow-up questions near zero, and only branches when the user explicitly asks for added specificity. |
-| [git-story-teller](skills/git-story-teller/SKILL.md) | Turns any full repository URL into a deterministic story workspace using the bundled .NET file-based runner `scripts/story.cs`. Requires explicit `--repo-url` and `--output-root`, derives `{repo-id}`, fixes `result/`, packs context with local Repomix when available, the public Repomix web API for GitHub URLs when Node/npm is unavailable, or a lower-fidelity built-in .NET fallback as the last resort, writes target contexts plus manifest instructions, then guides the agent to write target stories before `result/Index.md` with a package-facing `## Package selection` overview section. |
+| [git-story-teller](skills/git-story-teller/SKILL.md) | Turns any full repository URL into a deterministic story workspace using the bundled .NET file-based runner `scripts/story.cs`. Requires explicit `--repo-url` and `--output-root`, derives `{repo-id}`, fixes `result/`, packs context with local Repomix when available, the public Repomix web API for GitHub URLs when Node/npm is unavailable, or a lower-fidelity built-in .NET fallback as the last resort, writes full contexts plus public API summaries, engineering signals, conservative package-owned test paths, context indexes, and ordered chunk files, then guides the agent to fully read the current phase's required context before writing target stories and `result/Index.md`, optionally using one subagent per independent target context and using completed package stories as the primary source for the package-facing `## Package selection` overview. |
 | [dotnet-new-lib-slnx](skills/dotnet-new-lib-slnx/SKILL.md) | Scaffold a new .NET NuGet library solution following codebeltnet engineering conventions. Dynamic defaults for TFM/repository metadata, latest-stable NuGet package resolution, tuning projects plus a tooling-based benchmark runner, TFM-aware test environments, strong-name signing, NuGet packaging, DocFX documentation, CI/CD pipeline, and code quality tooling. |
 | [dotnet-new-app-slnx](skills/dotnet-new-app-slnx/SKILL.md) | Scaffold a new .NET standalone application solution following codebeltnet engineering conventions. Supports Console, Web, and Worker host families with Startup or Minimal hosting patterns; Web expands into Empty Web, Web API, MVC, or Web App / Razor, plus functional tests and a simplified CI pipeline. |
 | [trunk-first-repo](skills/trunk-first-repo/SKILL.md) | Initialize a git repository following [scaled trunk-based development](https://trunkbaseddevelopment.com/#scaled-trunk-based-development). Seeds an empty `main` branch and creates a versioned feature branch (`v0.1.0/init`), enforcing a PR-first workflow where content only reaches main through peer-reviewed pull requests. |
@@ -283,7 +284,7 @@ Anthropic's `skill-creator` is an excellent base workflow, but the day-to-day fr
 
 ### Why git-story-teller?
 
-Repository story generation works best when deterministic context gathering is separated from AI-authored prose. **git-story-teller** owns that split: its bundled .NET file-based runner creates the manifest, instructions, and one context file per target; the agent writes the target stories and overview.
+Repository story generation works best when deterministic context gathering is separated from AI-authored prose. **git-story-teller** owns that split: its bundled .NET file-based runner creates the manifest, instructions, full context files, public API summaries, engineering signal maps, context indexes, and ordered chunk files; the agent writes the target stories and overview.
 
 - **Bundled C# runner** - ships `scripts/story.cs`, run with `dotnet run --file`, so the skill is self-contained without a full project file
 - **Repomix-first packing** - uses `npx repomix` for the canonical XML context, ignore handling, token metadata, and security checks when Node/npm access is available
@@ -293,10 +294,18 @@ Repository story generation works best when deterministic context gathering is s
 - **KISS contract** - only `--repo-url` and `--output-root` are inputs; `{repo-id}` is derived and `result/` is fixed
 - **Codebelt-flavored default** - recommends `.bot/stories` when the active workspace already contains a `.bot` folder
 - **Tool output is authoritative** - reads `manifest.json`, `instructions.md`, and one target context at a time instead of reconstructing scope from memory
+- **Public API first** - adds a generated public API summary so agents can orient around consumer-facing types, inheritance chains, and likely key members before reading the raw source
+- **Engineering signal map** - highlights source-backed places to inspect for validation guards, lifecycle callbacks, factories, hosting styles, and test evidence so stories can explain the engineering decisions instead of listing APIs mechanically
+- **Conservative test ownership** - maps a package to a dedicated test project with the same package name plus a test suffix, or to a single unambiguous direct reference, instead of assigning downstream package tests that merely share a base package prefix
+- **Low-signal filtering** - removes `GlobalSuppressions.cs` from packed context while keeping internals available when they explain public behavior
+- **Chunked context navigation** - emits `*.context.index.md` and ordered `*.context.chunks/*.md` files beside each full context so agents can read large evidence sets even when a tool caps single-file output
+- **Complete-read grounding** - treats capped or truncated context output as an unfinished read, requiring the agent to use the index and every ordered chunk, or range reads for older workspaces, until the current target context, overview context, and required target stories have been fully inspected
+- **Subagent-friendly targets** - when the runtime supports delegation, assigns at most one independent target context to each subagent so large contexts do not compete for the same prompt budget, while the main agent orchestrates, gathers caveats, and authors the final overview
 - **Target-first workflow** - writes `result/{TargetName}.md` files before synthesizing `result/Index.md`
+- **Story-sourced overview** - requires the overview phase to open the completed target story files as the primary source instead of relying on `overview.context.md` alone
 - **Package-facing overview** - requires `result/Index.md` to use `## Package selection` for the reader-facing selection section
-- **Context-budget aware** - processes target contexts separately and uses completed target stories for the overview
-- **Grounded prose** - forbids invented APIs, relationships, examples, and broad marketing claims unless the generated context supports them
+- **Phase-scoped reading** - processes target contexts separately and uses completed target stories for the overview without letting token limits justify skipped evidence
+- **Grounded prose** - forbids invented APIs, relationships, examples, broad marketing claims, and unmeasured frequency claims such as "most common mistake" unless the generated context supports them with concrete evidence
 - **Publication stays explicit** - leaves staged files in `{output-root}/{repo-id}/result` unless the user asks to sync them into a consuming site
 ### Why markdown-illustrator?