@deftai/directive-content 0.55.0

package/resilience/context-pruning.md

@@ -0,0 +1,67 @@
+# Context Pruning
+
+Fresh context windows for every task — eliminating context rot.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [context/context.md](../context/context.md) | [context/fractal-summaries.md](../context/fractal-summaries.md) | [core/glossary.md](../glossary.md)
+
+> Adapted from [GSD](https://github.com/gsd-build/get-shit-done) context pruning model.
+
+---
+
+## Core Principle
+
+Context rot is the silent killer of multi-task agent work. By task 3–4 in a sequence, the context window is saturated with stale tool output, dead-end debugging, and outdated file reads. The model doesn't know what's current — reasoning quality drops as signal-to-noise collapses.
+
+---
+
+## Task Anchoring
+
+- ~ Each task gets a **logical anchor point** in the conversation
+- ~ Before each task, prune prior tasks' tool calls, intermediate reads, and debugging traces
+- ! The only things in context for a new task: **current task plan** + **curated upstream summaries**
+- ⊗ Carrying forward stale file reads, old terminal output, or resolved debugging traces
+
+## Zero Discovery Calls
+
+- ~ Pre-assemble everything the agent needs **before** the task starts:
+  - Task plan (goal, steps, acceptance criteria)
+  - Compressed summaries from dependency features (see [fractal-summaries.md](../context/fractal-summaries.md))
+  - Locked decisions from interview phase (see [strategies/discuss.md](../strategies/discuss.md))
+  - Continue checkpoint data if resuming (see [resilience/continue-here.md](./continue-here.md))
+- ~ If the agent must `grep` for project structure or search for prior decisions, the context assembly is broken
+- ⊗ Spending tokens on "where am I, what exists, what was decided" — that's context assembly's job
+
+## Token Budget
+
+- ~ Cap injected summary context at **~2500 tokens**
+- ~ If dependency chain is too large, drop oldest/least relevant summaries first
+- ~ Priority: release summaries > feature summaries > task summaries
+- ! Never exceed the budget by loading "just one more" summary
+
+---
+
+## Self-Monitoring
+
+Behavioral guidelines for recognizing and acting on context degradation mid-sequence.
+
+- ~ After every 3 completed tasks in a sequence, pause and assess: is reasoning quality declining?
+- ~ Watch for these signals of context rot:
+  - Repeating tool calls that were already made earlier
+  - Conflating details from different tasks
+  - Hesitating on decisions that were already locked
+  - Growing urge to re-read files that haven't changed
+- ! When signals appear: write a continue checkpoint (see [continue-here.md](./continue-here.md)) and start a fresh context
+- ~ Proactively checkpoint **before** degradation — don't wait until reasoning visibly breaks
+- ≉ Pushing through "just one more task" when context is saturated
+- ? If task count is uncertain, err on the side of checkpointing early
+
+---
+
+## Anti-Patterns
+
+- ⊗ Task 5 seeing 40 tool calls from tasks 1–4
+- ⊗ Referencing variables/patterns from code that was since refactored
+- ⊗ Avoiding approaches that failed earlier for reasons that no longer apply
+- ⊗ Re-reading the entire project structure at the start of every task

package/resilience/continue-here.md

@@ -0,0 +1,62 @@
+# Continue-Here: Interruption Recovery
+
+Surviving context window exhaustion, session timeouts, and manual stops.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [context/long-horizon.md](../context/long-horizon.md) | [resilience/context-pruning.md](./context-pruning.md) | [core/glossary.md](../glossary.md)
+
+> Adapted from [GSD](https://github.com/gsd-build/get-shit-done) continue-here model.
+
+---
+
+## Core Principle
+
+Sessions end. Work must not be lost. A fresh session must resume from **exactly** where the prior one stopped — without the human re-explaining everything.
+
+---
+
+## When to Write a Continue Checkpoint
+
+- ! On session end (timeout, user stop, compaction event)
+- ! On context window exhaustion
+- ~ Proactively when task complexity suggests resumption is likely
+- ? Mid-task if a natural checkpoint is reached
+
+## Continue Checkpoint Contents
+
+Persist to `./vbrief/continue.vbrief.json` in vBRIEF format:
+
+- ! **Completed** — what's already done (vBRIEF items with `completed` status)
+- ! **Remaining** — what's left (vBRIEF items with `pending` status)
+- ! **Decisions** — choices made during this session (vBRIEF narratives)
+- ~ **Hazards** — what was tricky, what to watch out for (narrative)
+- ! **Resume point** — the exact first thing to do when resuming (narrative on the next `pending` item)
+- ! **Scope vBRIEF reference** — when scope vBRIEFs exist, MUST include `planRef` to the scope vBRIEF(s) the agent was working on (enables the resuming agent to load the durable scope record)
+
+## Resume Protocol
+
+- ! On resume, read the continue checkpoint — **don't replay conversation history**
+- ! Load the task plan + continue checkpoint into context
+- ! Pick up from the resume point, not from the beginning
+- ! After successful resume, mark the continue checkpoint consumed (status: `completed`)
+- ⊗ Re-debate decisions already recorded in the continue checkpoint
+- ⊗ Re-read prior conversation to reconstruct state
+
+## Continue Checkpoint Lifecycle
+
+- ! Continue checkpoints are **ephemeral** — consumed on resume, not permanent records
+- ~ Durable learnings from the session → persist to [meta/lessons.md](../../meta/lessons.md)
+- ~ Durable state → persist to the task's vBRIEF plan file or scope vBRIEF(s) in lifecycle folders
+- ! Scope vBRIEFs (`./vbrief/{proposed,pending,active,completed,cancelled}/`) are **durable** — they persist across sessions and are shared between agents; do not conflate them with ephemeral continue checkpoints
+- ⊗ Accumulate stale continue checkpoints — clean up after resume
+
+---
+
+## Anti-Patterns
+
+- ⊗ Resuming by asking the user "where were we?"
+- ⊗ Re-reading full conversation history instead of the continue checkpoint
+- ⊗ Losing in-flight decisions because they weren't persisted
+- ⊗ Starting over from scratch after an interruption
+- ⊗ Creating `continue-{ULID}.json` — the file is singular: `continue.vbrief.json`

package/scm/changelog.md

@@ -0,0 +1,276 @@
+# Changelog Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [git.md](./git.md) | [github.md](./github.md) | [versioning.md](../meta/versioning.md)
+
+**Specification**: [Keep a Changelog 1.0.0](https://keepachangelog.com/en/1.0.0/)
+
+## Scope
+
+! CHANGELOG.md is maintained **on every PR** under `[Unreleased]` and published as a versioned entry at release time.
+
+## Purpose
+
+The changelog documents notable changes for **users and consumers** of the software between releases. Individual commits are tracked in git history for developers.
+
+## Format
+
+! Use Keep a Changelog format in `CHANGELOG.md`:
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- New features in development
+
+### Changed
+- Changes in existing functionality
+
+### Deprecated
+- Soon-to-be removed features
+
+### Removed
+- Removed features
+
+### Fixed
+- Bug fixes
+
+### Security
+- Security vulnerability fixes
+
+## [1.0.0] - 2024-01-18
+
+### Added
+- Initial release
+
+[Unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/user/repo/releases/tag/v1.0.0
+```
+
+## Sections
+
+! Use exactly these section headings:
+
+- **Added** - New features
+- **Changed** - Changes in existing functionality
+- **Deprecated** - Soon-to-be removed features
+- **Removed** - Removed features
+- **Fixed** - Bug fixes
+- **Security** - Security vulnerability fixes
+
+~ Include only sections with changes for each release.
+
+## When to Update
+
+! Update CHANGELOG.md **on every PR**, not just at release time:
+
+1. Add your entry under `[Unreleased]` in the appropriate section (Added/Changed/Fixed/Removed)
+2. Reference the issue number: `- **Feature Name**: description (#42)`
+3. The PR template checklist enforces this — reviewers should verify
+
+? Skip the changelog entry only for test-only, CI-only, or purely internal changes.
+
+At release time, `[Unreleased]` is renamed to the new version (see Release Process below).
+
+## What to Include
+
+! Include changes that affect **users, integrations, or framework-level tooling/structure**:
+
+**Include:**
+- New features users can access
+- Breaking changes requiring user action
+- Deprecated features users should stop using
+- Bug fixes users will notice
+- Security fixes
+- Important performance improvements
+
+**Exclude:**
+- Internal refactoring invisible to users
+- Documentation typos
+- Test-only changes
+- CI-only pipeline tweaks
+
+## Version Format
+
+! Each release section takes the form:
+
+```markdown
+## [MAJOR.MINOR.PATCH] - YYYY-MM-DD
+```
+
+! Versions listed in reverse chronological order (newest first).
+
+! Use semantic versioning for version numbers (see [versioning.md](../meta/versioning.md)).
+
+## Optional Release Summary Blockquote
+
+? An optional one-line Markdown blockquote may appear directly after the `## [MAJOR.MINOR.PATCH] - YYYY-MM-DD` heading, sandwiched by blank lines:
+
+```markdown
+## [1.1.0] - 2024-02-01
+
+> Adds dark mode and CSV export, replacing the legacy theme picker.
+
+### Added
+- Dark mode support
+- Export data to CSV format
+```
+
+The blockquote captures the operator's one-sentence release narrative (recommended 80-160 chars). It is authored once during the release flow (`task release -- <version> --summary "<text>"`; see `skills/deft-directive-release/SKILL.md` Phase 1) and propagates verbatim into the GitHub release body (auto-pickup via `scripts/release.py::_section_for_version`) AND the Phase 8 Slack `*Summary*:` slot. The blockquote is inline Markdown -- `**bold**`, `[link](url)`, etc. are preserved verbatim. Omit the blockquote (no `--summary` flag) to keep the pre-existing Keep-a-Changelog shape.
+
+⊗ Hand-write a different one-line narrative for each downstream surface (CHANGELOG / GitHub release / Slack) -- author once via `--summary` and let the pipeline propagate.
+
+## Entry Format
+
+~ Each change is a concise bullet point:
+
+```markdown
+### Added
+- Dark mode support for web UI
+- Export to CSV functionality in reports
+```
+
+~ Start each entry with a verb (Added, Fixed, Changed, etc. implied by section).
+
+! Keep entries user-focused, not implementation-focused.
+
+**Good examples:**
+- "Added dark mode toggle in settings"
+- "Fixed crash when opening large files"
+- "Removed deprecated `--legacy` flag"
+- "Bumped `black` to 26.3.1 (framework tooling update)"
+
+**Bad examples:**
+- "Refactored authentication module" (internal, not user-visible)
+- "Fixed typo in README" (documentation, minor)
+- "Updated ESLint to v8" (dev CI tooling, no impact on framework users)
+
+## Unreleased Section
+
+! Maintain an `[Unreleased]` section at the top.
+
+~ Add notable changes to `[Unreleased]` as they're developed.
+
+! Move items from `[Unreleased]` to versioned section during release.
+
+## Breaking Changes
+
+! Clearly mark breaking changes:
+
+```markdown
+## [2.0.0] - 2024-02-15
+
+### Changed
+- **BREAKING**: Renamed `--output` flag to `--file`
+- **BREAKING**: Removed support for Python 3.8
+```
+
+~ Provide migration guidance for breaking changes:
+
+```markdown
+### Changed
+- **BREAKING**: API endpoint `/api/v1/users` moved to `/api/v2/users`
+  - Migration: Update all API calls to use `/api/v2/users`
+  - Old endpoint will be removed in v3.0.0
+```
+
+## Links
+
+~ Include comparison links at bottom:
+
+```markdown
+[Unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/user/repo/releases/tag/v1.0.0
+```
+
+! Update links when adding new versions.
+
+## Examples
+
+### Minimal Release
+
+```markdown
+## [1.0.1] - 2024-01-20
+
+### Fixed
+- Crash when opening files larger than 10MB
+- Incorrect timezone display in logs
+```
+
+### Feature Release
+
+```markdown
+## [1.1.0] - 2024-02-01
+
+### Added
+- Dark mode support
+- Export data to CSV format
+- Keyboard shortcuts for common actions
+
+### Fixed
+- Memory leak in background sync
+- Incorrect sorting in dashboard
+```
+
+### Breaking Changes Release
+
+```markdown
+## [2.0.0] - 2024-03-01
+
+### Changed
+- **BREAKING**: Removed `--legacy` flag (use `--format=legacy` instead)
+- **BREAKING**: Minimum Node.js version now 18.x
+  - Migration: Upgrade Node.js to 18.x or later
+
+### Added
+- New plugin system for extensibility
+- Built-in support for PostgreSQL 15
+
+### Removed
+- Support for deprecated config file format (`.oldrc`)
+```
+
+## Release Process
+
+! Follow these steps in order when cutting a release:
+
+1. ! Rename `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD` (add today's release date)
+2. ! Add a fresh `## [Unreleased]` section above the new version
+3. ! Add link reference at bottom: `[X.Y.Z]: https://github.com/deftai/directive/releases/tag/vX.Y.Z`
+4. ! Update comparison link: `[Unreleased]: https://github.com/deftai/directive/compare/vX.Y.Z...HEAD`
+5. ! Commit: `chore: release vX.Y.Z`
+6. ! Open a PR for the release commit and merge to `master`
+7. ! After merge, tag locally: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`
+8. ! Push the tag: `git push origin vX.Y.Z` (triggers release workflow)
+9. ~ Verify GitHub Actions builds and publishes release artifacts
+
+⊗ Tag without a corresponding changelog entry.
+⊗ Write a versioned changelog entry without tagging.
+
+## Compliance
+
+- ! Maintain `CHANGELOG.md` in project root
+- ! Update `[Unreleased]` on every PR; rename to versioned entry only at release
+- ! Use Keep a Changelog format with exact section names
+- ! Include user-facing changes and framework-level changes (repo structure, tooling, docs) that affect developers who use the framework directly
+- ! Use semantic versioning for release numbers
+- ! Mark breaking changes clearly
+- ! Write entries from user perspective, not developer perspective
+- ~ Provide migration guidance for breaking changes
+- ~ Keep entries concise (1-2 lines per change)
+
+---
+
+**See also**:
+- [Keep a Changelog 1.0.0](https://keepachangelog.com/en/1.0.0/) - Full specification
+- [versioning.md](../meta/versioning.md) - Semantic versioning standards
+- [git.md](./git.md) - Git workflow and tagging
+- [github.md](./github.md) - GitHub releases

package/scm/git.md

@@ -0,0 +1,139 @@
+# Git Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [github.md](../scm/github.md)
+
+**Stack**: git 2.30+, Conventional Commits, `git --no-pager`, task-based workflows
+
+## Standards
+
+**Commits**: ! use Conventional Commits format: `type(scope): description`
+**Changelog**: ! follow [Keep a Changelog](./changelog.md) format
+**Versioning**: ~ follow [Semantic Versioning](../meta/versioning.md)
+**Safety**: ⊗ use `git reset --hard` or force-push without explicit permission
+**Workflow**: ! make small, reversible changes; ⊗ introduce silent breaking behavior
+**History**: ~ maintain linear history; ~ rebase over merge for feature branches (with permission)
+**Branches**: ~ use descriptive names: `feat/feature-name`, `fix/bug-name`, `refactor/scope`
+
+## Commit Types
+
+**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `ci`, `build`, `revert`
+
+```bash
+feat(auth): add JWT token refresh mechanism
+fix(api): handle null response in user endpoint
+docs(readme): update installation instructions
+refactor(db): extract connection pool logic
+test(parser): add edge cases for malformed input
+chore(deps): upgrade golang.org/x/crypto to v0.17
+```
+
+**Format**:
+
+- **type(scope)**: ! include type; ~ include scope
+- **description**: ! be lowercase, no period, imperative mood ("add" not "added")
+- **body**: ? be included; ~ wrap at 72 chars if present
+- **footer**: ? include `BREAKING CHANGE:` or `Closes #123`
+
+## Workflow Best Practices
+
+**Before committing**:
+1. ! Review changes with `git diff` and `git diff --cached`
+2. ! Run `task check` (MUST run pre-commit checks)
+3. ! Use interactive staging (`git add -p`) for complex changes
+4. ! Write descriptive commit messages following Conventional Commits
+
+**Branching**:
+- ~ Use descriptive branch names: `feat/feature-name`, `fix/bug-name`
+- ~ Create feature branches from latest `main`
+- ~ Delete branches after merge
+
+**Syncing**:
+- ~ Use `git pull --rebase` to maintain linear history
+- ! Always use `git --no-pager` for scripted/programmatic operations
+- ~ Keep feature branches up to date with `main`
+
+## .gitignore Patterns
+
+```gitignore
+# Dependencies
+node_modules/
+vendor/
+.venv/
+__pycache__/
+
+# Build outputs
+dist/
+build/
+*.o
+*.so
+*.dylib
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Secrets (CRITICAL)
+secrets/
+*.env
+*.pem
+*.key
+.envrc
+
+# Generated
+coverage/
+htmlcov/
+*.log
+.task/
+
+# OS
+Thumbs.db
+```
+
+## Safety Rules
+
+**MUST NOT do without explicit permission**:
+
+- `git reset --hard` - destroys uncommitted work
+- `git push --force` - rewrites published history
+- `git rebase` on published branches
+- `git clean -fd` - deletes untracked files
+
+**Always safe (MAY use freely)**:
+
+- `git revert` - creates new commit undoing changes
+- `git restore` - discards unstaged changes (affects working tree only)
+- `git restore --staged` - unstages files
+- `git stash` - temporarily saves work
+
+**SHOULD prefer**:
+
+- Small commits over large ones
+- Descriptive commit messages over terse ones
+- `--force-with-lease` over `--force` (if force push needed)
+- New commits over history rewriting
+- Temp branches for experiments
+
+
+## Changelog & Versioning
+
+! Maintain CHANGELOG.md following [Keep a Changelog](./changelog.md) format
+! Use [Semantic Versioning](../meta/versioning.md) for releases:
+- **MAJOR** (X.0.0): Breaking changes
+- **MINOR** (0.X.0): New features (backward compatible)
+- **PATCH** (0.0.X): Bug fixes (backward compatible)
+
+## Compliance
+
+- ! Use Conventional Commits for all commits: `type(scope): description`
+- ! Maintain CHANGELOG.md following Keep a Changelog format
+- ! Use Semantic Versioning for releases
+- ⊗ Force-push or `reset --hard` without explicit permission
+- ! Run `task check` before committing
+- ! Use `git --no-pager` for programmatic/scripted operations
+- ! Keep secrets in `secrets/` dir; ⊗ commit them
+- ~ Prefer safe alternatives (`revert`, temp branches) over history rewriting