its-magic 0.1.2-9 → 0.1.2

package/template/decisions/DEC-0001.md

@@ -0,0 +1,11 @@
+# Decision DEC-0001
+
+Status: Pending
+
+## Context
+
+## Options
+
+## Recommendation
+
+## Impact

package/template/decisions/DEC-0002.md

@@ -0,0 +1,11 @@
+# Decision DEC-0002
+
+Status: Pending
+
+## Context
+
+## Options
+
+## Recommendation
+
+## Impact

package/template/docs/developer/README.md

@@ -0,0 +1,44 @@
+# Developer documentation
+
+This shard holds contributor-facing material for the **its-magic** framework. End-user
+setup stays in the root `README.md` (user channel).
+
+## Prerequisites
+
+- **Cursor** (or compatible editor) with the workflow files installed.
+- **Python 3** on PATH for scratchpad merge validation and several repo scripts.
+- **Node.js** if you use npm-packaged `its-magic` or npm-driven `TEST_COMMAND` defaults.
+
+## Workflow
+
+- Follow phased commands under `.cursor/commands/` (`intake`, `discovery`, `architecture`,
+  `sprint-plan`, `execute`, `qa`, `release`, etc.).
+- Keep handoffs and `docs/engineering/state.md` updated at phase boundaries.
+- Use `.cursor/scratchpad.local.md` for personal overrides; never commit secrets.
+
+## Quality gates
+
+- Run `TEST_COMMAND` from `docs/engineering/runbook.md` before push; CI should mirror the same.
+- Run `python scripts/validate_doc_profile.py` when changing documentation profile flags or
+  README surfaces.
+- Observe `US-0071` hygiene for user-visible script output (see runbook).
+
+## Architecture notes
+
+- High-level contracts live in `docs/engineering/architecture.md` (search for story ids).
+- Installer ownership is driven by `docs/engineering/context/installer-owned-paths.manifest`.
+- Template parity: changes in repo root often require the same edit under `template/`.
+
+## Contracts and interfaces
+
+- Scratchpad merge precedence: local → materialized `.cursor/scratchpad.md` →
+  `.cursor/scratchpad.local.example.md` (Model B / **DEC-0055**).
+- Documentation profile keys: `DOC_AUDIENCE_PROFILE`, `DOC_DETAIL_LEVEL` (**DEC-0059**).
+- Optional modes: `SPEC_PACK_MODE`, `USER_GUIDE_MODE` remain orthogonal; when `0`, validators
+  must not require those artifacts.
+
+## Engineering decisions
+
+- Decision records: `decisions/DEC-xxxx.md` and the compact index in
+  `docs/engineering/decisions.md`.
+- Profile semantics for this shard: **DEC-0059** and `# US-0077` in `architecture.md`.

package/template/docs/engineering/architecture.md

@@ -0,0 +1,9 @@
+# Architecture
+
+## Overview
+
+## Components
+
+## Risks
+
+## Decisions

package/template/docs/engineering/artifact-ordering-policy.md

@@ -0,0 +1,48 @@
+# Artifact Ordering Policy (US-0058 / DEC-0040)
+
+This policy defines deterministic write order for mutable workflow artifacts.
+Commands that mutate these artifacts must use this matrix and fail safe when
+anchors are missing or ambiguous.
+
+## Canonical matrix
+
+| Artifact | Policy | Deterministic rule |
+|---|---|---|
+| `docs/engineering/state.md` | `append-bottom` | Add new checkpoints only at end of file, in chronological order; enforce hot-surface rollover when configured thresholds are exceeded. |
+| `docs/engineering/architecture.md` | `append-bottom` | Add new `US-xxxx` architecture sections at end of file; non-target section rewrites/deletions are forbidden. |
+| `docs/product/backlog.md` | `sorted-canonical` | Keep stories sorted by numeric `US-xxxx` ID; mutate only target story block. |
+| `docs/product/acceptance.md` | `sorted-canonical` | Keep `US-xxxx` rows ordered by numeric ID aligned to backlog order. |
+| `handoffs/release_queue.md` | `append-bottom` | Append only one row per new sprint in release order. |
+| `handoffs/release_notes.md` | `prepend-top` | Update latest pointer section first; preserve historical references list. |
+| `handoffs/resume_brief.md` | `prepend-top` | Update current status/next-actions sections without rewriting unrelated history. |
+
+## Idempotence contract
+
+- Re-running a command without semantic changes must not reorder rows/blocks.
+- No oscillation between top and bottom insertion paths.
+- No broad rewrites of unrelated story/sprint entries.
+- For `docs/engineering/state.md`, each newly appended checkpoint timestamp must
+  be monotonic (`new_timestamp >= last_checkpoint_timestamp`) in UTC.
+- For rollover reruns, archive partition boundaries and pack naming must be
+  deterministic (no duplicate or oscillating pack generation).
+
+## Fail-safe behavior
+
+If required placement anchors are missing or ambiguous:
+- stop with reason code `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS`,
+- emit remediation guidance with expected anchor and file path,
+- perform no partial mutation.
+
+If a new `state.md` checkpoint timestamp is older than the current last
+checkpoint timestamp:
+- stop with reason code `STATE_TIMESTAMP_NON_MONOTONIC`,
+- emit remediation guidance with the expected minimum timestamp,
+- perform no partial mutation.
+
+If configured state hot-surface rollover cannot determine a safe archive
+boundary or cannot persist archive pack writes:
+- stop with reason code `STATE_ARCHIVE_BOUNDARY_AMBIGUOUS` or
+  `STATE_ARCHIVE_WRITE_FAILED` (or verification mismatch
+  `STATE_ARCHIVE_VERIFICATION_FAILED`),
+- emit remediation guidance with threshold/boundary details and target path,
+- perform no partial mutation.

package/template/docs/engineering/artifact-ownership-policy.md

@@ -0,0 +1,57 @@
+# Artifact Ownership Policy (US-0061 / DEC-0043)
+
+This policy defines phase-level mutation ownership for mutable workflow
+artifacts. Ordering policy and ownership policy are complementary:
+
+- ordering determines where mutations may be placed,
+- ownership determines who may mutate specific scopes.
+
+## Ownership matrix
+
+| Artifact | Owned scope | Allowed phases | Override-authorized phases |
+|---|---|---|---|
+| `docs/product/vision.md` | Intake/discovery notes for current story | `intake`, `discovery` | none |
+| `docs/product/backlog.md` | target story block only | `intake`, `release`, `status-reconcile` | none |
+| `docs/product/acceptance.md` | target story row only | `intake`, `release`, `status-reconcile` | none |
+| `handoffs/po_to_tl.md` | newest handoff/addendum section | `intake`, `discovery` | none |
+| `docs/engineering/research.md` | new `R-xxxx` entries | `intake`, `research`, `architecture` | none |
+| `docs/engineering/architecture.md` | append new `US-xxxx` architecture section or target section update | `architecture` | none |
+| `docs/engineering/decisions.md` | compact index/context pack section | `architecture`, `refresh-context` | none |
+| `decisions/DEC-xxxx.md` | decision file for current story | `architecture` | none |
+| `sprints/Sxxxx/*` | current sprint artifacts only | `sprint-plan`, `plan-verify`, `execute`, `qa`, `verify-work`, `release` | none |
+| `handoffs/tl_to_dev.md` | newest handoff section | `sprint-plan` | none |
+| `handoffs/release_queue.md` | target sprint row only | `release` | none |
+| `handoffs/release_notes.md` | latest pointer section | `release`, `refresh-context` | none |
+| `docs/engineering/state.md` | append-bottom checkpoints only | all delivery phases | none |
+| `handoffs/resume_brief.md` | current status/next-actions sections; latest-pointer upsert on **`/intake bug`** completion (**DEC-0069**) | `intake` (bug persistence path only), `pause`, `resume`, `refresh-context`, `release` | none |
+
+## Non-destructive mutation rules
+
+- Non-authorized phases must not delete or rewrite sections owned by other
+  phases.
+- Mutations must be target-scoped; broad file rewrites are forbidden.
+- `docs/engineering/architecture.md` history preservation is mandatory:
+  unrelated `US-xxxx` sections must remain intact.
+
+## Override contract
+
+- Override-authorized mutation is allowed only when the matrix explicitly lists
+  an override-authorized phase for that artifact.
+- Required evidence fields:
+  - `override_phase_id`
+  - `override_reason`
+  - `override_scope`
+  - `evidence_ref`
+- Missing/invalid override evidence is fail-closed.
+
+## Fail-safe reason codes
+
+- `PHASE_OWNERSHIP_VIOLATION`
+- `PHASE_OVERRIDE_EVIDENCE_MISSING`
+- `ARCH_HISTORY_DELETION_DETECTED`
+
+When any reason code is emitted:
+
+- perform no partial write,
+- preserve current file contents,
+- emit remediation guidance with expected owner phase and target scope.