@nlaprell/shipit 1.0.0

package/_system/behaviors/WORK_ROOT_PLATFORM_ISSUES.md

@@ -0,0 +1,140 @@
+# Root Platform Issue Workflow
+
+**Purpose:** Define a consistent, high-quality workflow for resolving root platform issues.
+
+**When to use:** Any time you are working a platform issue from GitHub Issues.
+
+## Agent Execution Rule
+
+**You must execute the entire workflow yourself.** Do not stop early to "give the user directions" or "let them do the next step." For each step:
+
+- **Do it:** Run the commands, create the PR, post the resolution comment, close the issue, add the review comment. Use `gh`, `git`, and your tools.
+- **Only hand off** when the workflow explicitly requires a human (e.g. "Wait for merge approval" or "stop and request approval").
+
+If you cannot complete a step (e.g. no `gh` auth, no merge permission), say so and do everything up to that point—do not hand off steps you _can_ do (push, PR create, issue close, PR comment) by telling the user to do them.
+
+**Anti-pattern:** Ending with "Next: push the branch and open a PR" or "You can now merge" when you have not yet pushed, created the PR, or posted the resolution comment. That is drift; complete the steps instead.
+
+## Scope and Safety
+
+- This behavior applies to the root platform repo (not downstream project repos).
+- **All issues are tracked on GitHub** (not in local files).
+- Read issues from GitHub using MCP tools or GitHub API.
+- After resolving an issue, add a resolution comment and close it on GitHub.
+- If the issue cannot be resolved without changing scope or requirements, stop and report.
+- Update `README.md` if the fix adds or changes user-facing behavior, commands, or workflows.
+
+**Note:** As of 2026-01-28, all issues are tracked on GitHub. The previous file-based tracking in `tests/ISSUES.md` is deprecated. See `behaviors/WORK_TEST_PLAN_ISSUES.md` for issue creation rules.
+
+---
+
+## Workflow
+
+### Step 1: Validate the Implementation
+
+**Objective:** Confirm the current implementation and issue description still match reality.
+
+**Actions:**
+
+1. Ensure the current workspace is clean before starting work.
+2. Switch to main branch and ensure it's up to date: `git checkout main && git pull origin main`
+3. Create a new branch for the issue from main: `git checkout -b issue-XXX-description` (where XXX is the GitHub issue number)
+4. Push the branch: `git push -u origin issue-XXX-description`
+5. Read the GitHub issue using MCP tools (e.g., `mcp_github-mcp_get_issue`) or GitHub API.
+6. Verify the described behavior is still reproducible or still missing.
+7. If the issue description is outdated or incorrect:
+   - Add a comment to the GitHub issue with corrected findings before proceeding.
+   - If the issue is no longer valid, add a resolution comment explaining why and close the issue.
+
+**Stop gate:** If the issue is invalid or not reproducible, do not implement changes.
+
+---
+
+### Step 2: Work the Issue
+
+**Objective:** Implement the fix or missing functionality.
+
+**Actions:**
+
+1. Identify the smallest set of files required to change.
+2. Implement the fix.
+3. Avoid bloat: no unrelated refactors or feature additions.
+4. Run the narrowest verification that proves the fix.
+5. Commit any new changes made during validation.
+
+**Stop gate:** If the fix requires new scope, stop and request approval.
+
+---
+
+### Step 3: Quality Review
+
+**Objective:** Ensure the solution is correct, minimal, and safe.
+
+**Actions:**
+
+1. Re-read the changed files for logic errors or regressions.
+2. Check for unnecessary complexity or duplication.
+3. Confirm the fix aligns with existing patterns and scripts.
+4. Verify no unrelated files were modified.
+
+---
+
+### Step 4: Update Issue Records
+
+**Objective:** Record resolution and close the GitHub issue.
+
+**Actions:**
+
+1. Add a resolution comment to the GitHub issue using `tests/ISSUE_RESOLUTION_COMMENT_TEMPLATE.md`:
+   - **Resolution:** How the issue was resolved, what was changed
+   - **Validation:** How the fix was validated, tests run, verification steps
+   - **Date Resolved:** YYYY-MM-DD
+2. Close the GitHub issue using MCP tools (e.g., `mcp_github-mcp_update_issue` with `state: "closed"`).
+3. Update `README.md` if the change affects user-facing docs.
+4. Commit the final changes when the work is finished.
+
+---
+
+### Step 5: Submit PR and Review Cycle
+
+**Objective:** Submit PR and iterate until it's ready to merge.
+
+**Actions (you perform these; do not hand off to the user):**
+
+1. Summarize changes and validation performed.
+2. Report the final status (resolved/blocked/invalid).
+3. Reference the GitHub issue number in the PR description (e.g., "Resolves #123").
+4. **Submit the PR yourself:** `git push -u origin <branch>` then `gh pr create` (or equivalent). Do not tell the user to "open a PR" or "push and create a PR."
+5. **Review the PR yourself** and add comments with findings:
+   - Check for bloat, rabbit holes, or unnecessary complexity
+   - Verify all requirements are met
+   - Check for unrelated changes
+   - Verify code quality and consistency
+6. **If PR is not ready to merge:**
+   - Resolve all identified issues
+   - Commit the fixes: `git commit -m "Fix: [description of fixes]"`
+   - Push the changes: `git push`
+   - Add a comment to the PR summarizing the fixes
+   - **Review the PR again** and add comments with findings
+   - **Repeat** the review/fix cycle until the PR is ready to merge
+7. **If PR is ready to merge:**
+   - Confirm in a PR comment that it's ready.
+   - If you can merge (e.g. `gh pr merge` works), merge the PR. Otherwise, the only handoff is: the user merges when ready.
+8. **After the PR is merged** (by you or the user): Switch back to `main` and pull so the workspace is clean for the next task: `git checkout main && git pull origin main`.
+
+**Review Criteria:**
+
+- No bloat or unnecessary complexity
+- No rabbit holes (scope creep)
+- All requirements met
+- No unrelated changes
+- Code quality and consistency verified
+- Issue tracking updated correctly
+
+---
+
+## Validation Guidance
+
+- Prefer targeted checks over full suites when safe.
+- If there is any uncertainty, run full checks: `pnpm test`, `pnpm lint`, `pnpm typecheck`.
+- Capture the commands run and their outcomes in the issue resolution notes.

package/_system/behaviors/WORK_TEST_PLAN_ISSUES.md

@@ -0,0 +1,380 @@
+# Test Plan Issue Management
+
+**Purpose:** Define consistent rules for creating, tracking, and archiving issues discovered during test plan execution using GitHub Issues.
+
+**When to use:** Any time you are executing test plan steps from `tests/TEST_PLAN.md` and encounter failures, missing functionality, or unexpected behavior.
+
+## Quick Reference: Templates
+
+- **Issue body:** Use `tests/ISSUE_TEMPLATE.md` (GitHub issue body)
+- **Research Notes:** Use `tests/ISSUE_RESEARCH_TEMPLATE.md` (GitHub issue body)
+- **Resolution Comments:** Use `tests/ISSUE_RESOLUTION_COMMENT_TEMPLATE.md` (GitHub issue comment)
+- **Issue Title:** Brief descriptive title (e.g., "Missing golden-data directory")
+
+Always create issues on GitHub using the templates. Issues are tracked on GitHub, not in local files.
+
+## Scope and Safety
+
+- This behavior applies to issues discovered during test plan execution.
+- **All issues are created on GitHub** in the repository where the test is running.
+- Root platform issues: Create in root platform repository (e.g., `NJLaPrell/ShipIt`).
+- Test project issues: Create in test project repository (if it has its own repo) or root platform repository.
+- After resolving an issue, close it on GitHub with a resolution comment.
+
+**Note:** This workflow replaces the previous file-based issue tracking in `tests/ISSUES.md`. `tests/ISSUES.md` is for **test run logs only**; issues live on GitHub.
+
+---
+
+## Preflight (Must Pass Before Creating Issues)
+
+Before creating any issues, verify `gh` is available and authenticated:
+
+```bash
+gh --version
+gh auth status
+```
+
+If authentication is missing/expired, **STOP** and treat it as a **blocking** test-plan failure (you cannot correctly record issues).
+
+## Repo Resolution (Where to File the Issue)
+
+### Determine the current repo
+
+From the workspace where the failure occurred:
+
+```bash
+gh repo view --json nameWithOwner -q .nameWithOwner
+```
+
+If this fails (e.g., not a git repo, no remote), fall back to the **root platform repo** (usually `NJLaPrell/ShipIt`) and note the limitation in the issue body.
+
+### Decision rule
+
+- **Root platform issue → file in root platform repo**
+  - Missing/broken framework scripts or commands
+  - Incorrect framework behaviors/docs/templates
+  - CI/lint/test configuration in the framework
+  - Anything that would affect _any_ initialized project
+
+- **Test project issue → file in test project repo (only if it exists as a real repo), otherwise root platform repo**
+  - Failures caused by test-project-specific content or changes _after_ initialization
+  - If the test project is just a folder created under `./projects/` (no separate remote), file in the root platform repo and label it as test-project surfaced
+
+Rule of thumb: if fixing it requires changing the framework repo → file in the framework repo.
+
+---
+
+## When to Create an Issue
+
+Create a GitHub issue when:
+
+1. **Test step fails** (expected behavior doesn't match actual)
+2. **Missing functionality** (expected feature/script/file doesn't exist)
+3. **Unexpected behavior** (system behaves differently than documented)
+4. **Tooling missing** (required scripts, configs, or dependencies are absent)
+5. **Configuration errors** (invalid or missing configuration causes failures)
+
+**Do NOT create issues for:**
+
+- Expected failures (tests that are supposed to fail initially)
+- User errors (incorrect input, wrong commands)
+- Transient failures (network issues, temporary outages)
+
+---
+
+## Creating GitHub Issues
+
+### Issue Creation Process
+
+1. **Prepare the issue:**
+   - Read the appropriate template (`tests/ISSUE_TEMPLATE.md` or `tests/ISSUE_RESEARCH_TEMPLATE.md`)
+   - Fill in all fields with specific, actionable information
+   - Remove placeholder text and brackets
+
+2. **Create the issue on GitHub:**
+   - Use the GitHub CLI (`gh`) to create the issue
+   - **Title:** Brief descriptive title (e.g., "Missing golden-data directory")
+   - **Body:** Use the filled-out template content
+   - **Labels:** Add appropriate labels (labels must exist before use):
+     - Severity: `severity:low`, `severity:medium`, `severity:high`
+     - Type: `test-plan-issue`, `research-note` (if applicable)
+     - Step: `step:12-1`, `step:UX`, etc. (if applicable)
+   - **Repository:** Create in the appropriate repository (root platform or test project)
+   - **Label Creation:** Labels must be created via GitHub UI before they can be used. GitHub MCP tools and API cannot create labels—they can only add existing labels to issues. If a label doesn't exist:
+     1. Go to the repository on GitHub
+     2. Navigate to Issues → Labels
+     3. Create the label with the exact name (e.g., `severity:low`, `test-plan-issue`)
+     4. Then use the label when creating the issue
+
+3. **Reference the issue:**
+   - Use GitHub issue number (e.g., `#123`) in test run summaries
+   - Link to the issue in documentation
+
+### Issue Format
+
+**Use the template:** `tests/ISSUE_TEMPLATE.md`
+
+The template provides the GitHub issue body format. Fill in:
+
+- **Severity:** low | medium | high
+- **Step:** Test step number or phase name
+- **First Seen:** Date when issue was discovered
+- **Expected:** What should happen
+- **Actual:** What actually happened
+- **Error:** Error message or description
+- **Implementation:** Action items
+
+### Severity Levels
+
+- **high:** Blocks test execution or core functionality
+- **medium:** Affects functionality but workarounds exist
+- **low:** Minor issues, missing nice-to-haves, UX improvements
+
+### Issue Numbering
+
+- GitHub automatically assigns sequential issue numbers (#1, #2, #3, etc.)
+- Reference issues by their GitHub number (e.g., `#123`)
+- No manual numbering required
+
+---
+
+## Issue Categorization
+
+### Active Issues
+
+Create regular GitHub issues when:
+
+- They need to be resolved
+- They block or affect test execution
+- They represent missing functionality
+
+Use `tests/ISSUE_TEMPLATE.md` for the body.
+
+### Research Notes
+
+Create GitHub issues with `research-note` label when:
+
+- They require research before implementation
+- They are deferred for future work
+- They need architectural decisions
+- They are low priority but worth documenting
+
+Use `tests/ISSUE_RESEARCH_TEMPLATE.md` for the body and add `research-note` label.
+
+---
+
+## Test Run Recording
+
+### Test Runs (run logs only)
+
+`tests/ISSUES.md` must contain **only the latest run**. Prior runs are archived in `tests/ISSUES_HISTORIC.md`.
+
+**When recording a new run:**
+
+1. Append all existing run blocks from `tests/ISSUES.md` to `tests/ISSUES_HISTORIC.md` (under `## Historic Test Runs`).
+2. Write `tests/ISSUES.md` with header, Counting Conventions, and only the new run block.
+
+Format for each run block:
+
+```markdown
+## Test Runs
+
+### Run: YYYY-MM-DDTHH:MM:SSZ (root-project | test-project)
+
+**Steps Total:** [number]
+**Steps Executed:** [number]
+**Steps Skipped:** [number]
+**Steps Passed:** [number]
+**Steps Failed:** [number]
+**Blocking Issues:** [number]
+**Result:** ✅ PASS | ❌ FAIL
+
+#### Summary
+
+| Step | Name      | Status            | Severity | Notes |
+| ---- | --------- | ----------------- | -------- | ----- |
+| X-Y  | Step name | ✅ PASS / ❌ FAIL | severity | Notes |
+
+#### Issues Found This Run
+
+- **#123:** [Title] ([severity]) - **RESOLVED** / **ACTIVE**
+- **#124:** [Title] ([severity]) - **RESOLVED** / **ACTIVE**
+```
+
+**Note:** Issues are tracked on GitHub. Only reference GitHub issue numbers here.
+
+Definitions:
+
+- **Steps Total**: Total steps in the test plan section being run (including those that may be skipped due to blocking failures).
+- **Steps Executed**: Count of steps with status **✅ PASS** or **❌ FAIL** (exclude **⏭️ SKIP**).
+- **Steps Skipped**: Count of steps with status **⏭️ SKIP**.
+
+---
+
+## Archiving Issues
+
+### When to Close an Issue
+
+Close a GitHub issue when:
+
+- It has been resolved
+- It is no longer valid (e.g., requirements changed)
+- It was a false positive
+
+### Closing Process
+
+1. **Verify the fix:**
+   - Confirm the issue is resolved
+   - Run verification steps
+   - Document validation results
+
+2. **Add resolution comment:**
+   - Add a comment to the GitHub issue with:
+     - **Resolution:** How the issue was resolved, what was changed
+     - **Validation:** How the fix was validated, tests run, verification steps
+     - **Date Resolved:** YYYY-MM-DD
+
+3. **Close the issue:**
+   - Close the GitHub issue
+   - Add appropriate labels if needed (e.g., `resolved`, `fixed`)
+
+4. **Update test run summary:**
+   - Mark issue as **RESOLVED** in "Issues Found This Run" section
+   - Update with GitHub issue number and link
+
+### Resolution Comment Format
+
+**Use the template:** `tests/ISSUE_RESOLUTION_COMMENT_TEMPLATE.md`
+
+Copy the template and fill in:
+
+- Fill in "Resolution" with specific details about what was changed
+- Fill in "Validation" with specific verification steps and test results
+- Add the date resolved
+- Remove any placeholder text or brackets
+
+See `tests/ISSUE_RESOLUTION_COMMENT_TEMPLATE.md` for the complete template.
+
+---
+
+## Location Rules
+
+### Root Platform vs Test Project
+
+- **Root platform issues:** Create in root platform repository
+  - Missing framework scripts
+  - Framework bugs
+  - Missing framework files/configs
+  - CI/CD issues
+  - Documentation issues
+
+- **Test project issues:** Create in test project repository (if it has its own repo) or root platform repository
+  - Project-specific test failures
+  - Project configuration issues
+  - Project-specific missing functionality
+
+**Rule of thumb:** If the issue affects the framework itself → root platform repo. If it affects only the test project → test project repo (or root if no separate repo).
+
+---
+
+## Workflow
+
+### During Test Execution
+
+1. **When a step fails:**
+   - Record the failure in the test run summary table (in `tests/ISSUES.md`)
+   - Create a GitHub issue if it's a new issue (use `tests/ISSUE_TEMPLATE.md`)
+   - Reference the GitHub issue number in "Issues Found This Run" section
+
+2. **When discovering missing functionality:**
+   - Create a GitHub issue immediately (use `tests/ISSUE_TEMPLATE.md` or `tests/ISSUE_RESEARCH_TEMPLATE.md`)
+   - Add appropriate labels (severity, type, step)
+   - Reference the issue number in test run summary
+
+3. **At end of test run:**
+   - Update "Latest Test Run" section in `tests/ISSUES.md` with summary
+   - List all GitHub issues found in "Issues Found This Run" (with issue numbers)
+   - Update overall validation status if applicable
+
+### After Issue Resolution
+
+1. Add resolution comment to the GitHub issue
+2. Close the GitHub issue
+3. Update test run summary in `tests/ISSUES.md` to mark issue as **RESOLVED**
+4. Update with link to closed issue
+
+---
+
+## Examples
+
+The following examples show filled-out templates. Always start from the templates:
+
+- Active issues: Use `tests/ISSUE_TEMPLATE.md`
+- Research notes: Use `tests/ISSUE_RESEARCH_TEMPLATE.md`
+
+### Example: Active Issue (GitHub Issue #123)
+
+**Title:** Missing golden-data directory
+
+**Body (from ISSUE_TEMPLATE.md):**
+
+```markdown
+**Severity:** low
+**Step:** UX
+**First Seen:** 2026-01-27
+
+## Expected
+
+`golden-data/` directory exists per plan
+
+## Actual
+
+Directory does not exist
+
+## Error
+
+Replay validation test data cannot be stored
+
+## Implementation
+
+- Add `golden-data/.gitkeep` to track directory
+- Create `golden-data/README.md` with format documentation
+- Update `scripts/init-project.sh` to create directory
+```
+
+**Labels:** `severity:low`, `test-plan-issue`, `step:UX`
+
+### Example: Research Note (GitHub Issue #124)
+
+**Title:** Intent subfolders missing
+
+**Body (from ISSUE_RESEARCH_TEMPLATE.md):**
+
+```markdown
+**Type:** Research Note
+**Priority:** low
+
+## Best Approach
+
+- Create `intent/features/`, `intent/bugs/`, `intent/tech-debt/` subdirectories
+- Update all scripts to read intents recursively
+
+## Integration Points
+
+- `scripts/new-intent.sh` - write to subfolders
+- `scripts/generate-release-plan.sh` - read recursively
+- `scripts/generate-roadmap.sh` - read recursively
+- `scripts/init-project.sh` - create subfolders
+```
+
+**Labels:** `research-note`, `severity:low`, `test-plan-issue`
+
+---
+
+## Validation
+
+- All issues must be created on GitHub (not in local files)
+- All issues must have clear "Expected" vs "Actual" descriptions
+- Severity must be assigned (low/medium/high) and added as label
+- Issues must be referenced by GitHub issue number in test run summaries
+- Closed issues must have resolution comments with validation details

package/_system/do-not-repeat/abandoned-designs.md

@@ -0,0 +1,18 @@
+# Abandoned Designs
+
+This ledger records design approaches that were considered but rejected. **Do not rediscover these.**
+
+## Format
+
+Each entry should include:
+
+- **Design:** Brief description
+- **Why abandoned:** Reason for rejection
+- **Date:** When it was abandoned
+- **Intent ID:** Related intent (if any)
+
+---
+
+## Entries
+
+(No entries yet. Add entries as designs are abandoned.)

package/_system/do-not-repeat/bad-patterns.md

@@ -0,0 +1,19 @@
+# Bad Patterns
+
+This ledger records code patterns, architectural approaches, or practices that have been identified as problematic. **Do not repeat these patterns.**
+
+## Format
+
+Each entry should include:
+
+- **Pattern:** Brief description of the pattern
+- **Why it's bad:** Problems it causes
+- **Date:** When it was identified
+- **Intent ID:** Related intent (if any)
+- **Alternative:** Better approach (if known)
+
+---
+
+## Entries
+
+(No entries yet. Add entries as bad patterns are identified.)

package/_system/do-not-repeat/failed-experiments.md

@@ -0,0 +1,18 @@
+# Failed Experiments
+
+This ledger records experiments that were tried but failed. **Do not repeat these.**
+
+## Format
+
+Each entry should include:
+
+- **Experiment:** What was tried
+- **Why it failed:** Root cause
+- **Date:** When it failed
+- **Intent ID:** Related intent (if any)
+
+---
+
+## Entries
+
+(No entries yet. Add entries as experiments fail.)

package/_system/do-not-repeat/rejected-libraries.md

@@ -0,0 +1,19 @@
+# Rejected Libraries
+
+This ledger records libraries, frameworks, or tools that were evaluated but rejected. **Do not reconsider these without new information.**
+
+## Format
+
+Each entry should include:
+
+- **Library:** Name and version (if applicable)
+- **Why rejected:** Reason for rejection (performance, licensing, maintenance, etc.)
+- **Date:** When it was rejected
+- **Intent ID:** Related intent (if any)
+- **Alternatives:** Better options (if known)
+
+---
+
+## Entries
+
+(No entries yet. Add entries as libraries are rejected.)

package/_system/drift/baselines.md

@@ -0,0 +1,49 @@
+# Drift Baselines
+
+Initial thresholds for drift detection. Update these as the system matures.
+
+## Baseline Metrics (Initial)
+
+| Metric                    | Baseline   | Threshold  | Action if Exceeded |
+| ------------------------- | ---------- | ---------- | ------------------ |
+| **Avg PR size**           | < 10 files | > 15 files | Flag for review    |
+| **Test-to-code ratio**    | > 0.5      | < 0.3      | Block merge        |
+| **Dependency count**      | < 50 deps  | > 100 deps | Review for bloat   |
+| **New files w/o intents** | 0          | > 5        | Flag for review    |
+| **CI time-to-green**      | < 5 min    | > 15 min   | Investigate        |
+
+## Drift Indicators
+
+### Vocabulary Drift
+
+- New terms introduced without documentation
+- Terms used inconsistently across codebase
+- **Detection:** Grep for new domain terms, check consistency
+
+### Dependency Graph Entropy
+
+- Circular dependencies introduced
+- Import depth increases
+- **Detection:** ESLint `import/no-cycle`, custom depth checker
+
+### Test Coverage Drift
+
+- New code without tests
+- Test-to-code ratio decreases
+- **Detection:** Coverage reports, ratio calculation
+
+### Architecture Drift
+
+- Violations of CANON.md
+- New patterns without ADRs
+- **Detection:** ESLint rules, manual review
+
+## Review Schedule
+
+- **Weekly:** Automated drift check (CI)
+- **Monthly:** Human review of drift metrics
+- **Quarterly:** Baseline recalibration
+
+---
+
+_Last updated: 2026-01-12_

package/_system/drift/metrics.md

@@ -0,0 +1,33 @@
+# Drift Metrics Report
+
+Generated: 2026-02-04T22:05:43Z
+
+## PR Size Trend
+
+Avg files changed: 8.625
+
+## Test-to-Code Ratio
+
+Test lines: 177
+Code lines: 38
+Ratio: 4.65
+
+## Dependency Growth
+
+Dependencies: 0
+DevDependencies: 14
+
+## Untracked New Concepts
+
+\_system/architecture/CANON.md
+\_system/drift/metrics.md
+docs/DIRECTORY_STRUCTURE.md
+experimental/README.md
+projects/README.md
+scripts/README.md
+tests/README.md
+work/workflow-state/README.md
+
+## CI Performance
+
+(Manually update from CI dashboard)