its-magic 0.1.2-9 → 0.1.3-0

package/{docs → template/docs}/engineering/codebase-map.md

@@ -1,14 +1,9 @@
 # Codebase Map
 
 ## Stack
-- ...
 
 ## Entry Points
-- ...
 
 ## Key Modules
-- ...
 
 ## Conventions
-- ...
-

package/template/docs/engineering/compatibility-report.md

@@ -0,0 +1,20 @@
+# Compatibility Report
+
+- Mode: optional (`CROSS_REPO_OBSERVABILITY`)
+- Scope: workflow-level compatibility visibility and risk reporting
+- Status: advisory unless critical-gate policy is enabled
+
+## Findings
+
+| Finding ID | Story | Producer | Consumer | Severity | Evidence | Recommended action | Gate recommendation |
+|---|---|---|---|---|---|---|---|
+| (none yet) | - | - | - | - | - | - | - |
+
+## Summary
+
+- Critical: 0
+- High: 0
+- Medium: 0
+- Low: 0
+- Info: 0
+- Overall: PASS

package/template/docs/engineering/compatibility-signals.md

@@ -0,0 +1,7 @@
+# Compatibility Signals
+
+Structured contract-change signals for optional cross-repo observability mode.
+
+## Entries
+
+(No compatibility signals recorded yet.)

package/template/docs/engineering/component-scope-report.md

@@ -0,0 +1,16 @@
+# Component Scope Report
+
+- Story: US-xxxx
+- Scope mode: optional (`COMPONENT_SCOPE_MODE`)
+- Overall: N/A (no checks run yet)
+
+## Protection checks
+
+| Check ID | Target components | Non-target components | Result | Evidence |
+|---|---|---|---|---|
+| (none yet) | - | - | - | - |
+
+## Findings
+
+- Blocking: none
+- Non-blocking: none

package/template/docs/engineering/component-scope.md

@@ -0,0 +1,19 @@
+# Component Scope
+
+- Mode: optional (`COMPONENT_SCOPE_MODE`)
+- Story: US-xxxx
+
+## Scope declaration
+
+- scope_mode: off
+- target_components:
+  - (set when enabled)
+- non_target_components:
+  - (set when enabled)
+- allowed_interface_touch:
+  - (set when enabled)
+- out_of_scope_constraints:
+  - no intentional edits in non-target components without explicit approval
+- approval_policy:
+  - required: false
+  - source: decision/handoff artifact

package/template/docs/engineering/context/installer-owned-paths.manifest

@@ -0,0 +1,96 @@
+# its-magic installer ownership manifest
+# Sections are line-based path lists.
+#
+# Model B baseline: materialized scratchpad (under .cursor/) is not manifest-copied;
+# installers copy it from packaged template during post-install only. Framework-owned
+# scratchpad.local.example (under .cursor/) refreshes from template before baseline
+# handling in installer.py --scratchpad-postinstall (example-first ordering).
+
+[install_include_paths]
+.cursor/commands
+.cursor/rules
+.cursor/skills
+.cursor/agents
+.cursor/hooks
+.cursor/hooks.json
+.cursor/scratchpad.local.example.md
+docs
+sprints
+handoffs
+decisions
+scripts/validate-and-push.ps1
+scripts/validate-and-push.sh
+scripts/sync_push_gates.py
+scripts/doc_profile_lib.py
+scripts/validate_doc_profile.py
+scripts/intake_evidence_validate.py
+scripts/intake_evidence_lib.py
+scripts/intake_bug_routing_guard.py
+scripts/check_intake_template_parity.py
+scripts/materialize_codebase_map.py
+scripts/remote_config_summary.py
+scripts/guard_installer_publish.py
+scripts/enforce-triad-hot-surface.py
+scripts/caveman_compress_input.py
+scripts/readme_feature_coverage_lib.py
+scripts/validate_readme_feature_coverage.py
+scripts/check_downstream_ci_guard.py
+scripts/downstream_ci_guard_lib.py
+scripts/auto_outer_driver.py
+scripts/uat_probe_lib.py
+scripts/project_readme_coverage_lib.py
+scripts/validate_project_readme_coverage.py
+.github/workflows
+its_magic
+
+[clean_paths]
+.cursor
+docs/product
+docs/engineering
+docs/developer
+docs/user-guides
+sprints
+handoffs
+decisions
+scripts/validate-and-push.ps1
+scripts/validate-and-push.sh
+scripts/sync_push_gates.py
+scripts/doc_profile_lib.py
+scripts/validate_doc_profile.py
+scripts/intake_evidence_validate.py
+scripts/intake_evidence_lib.py
+scripts/intake_bug_routing_guard.py
+scripts/check_intake_template_parity.py
+scripts/materialize_codebase_map.py
+scripts/remote_config_summary.py
+scripts/guard_installer_publish.py
+scripts/enforce-triad-hot-surface.py
+scripts/caveman_compress_input.py
+scripts/readme_feature_coverage_lib.py
+scripts/validate_readme_feature_coverage.py
+scripts/check_downstream_ci_guard.py
+scripts/downstream_ci_guard_lib.py
+scripts/auto_outer_driver.py
+scripts/uat_probe_lib.py
+scripts/project_readme_coverage_lib.py
+scripts/validate_project_readme_coverage.py
+.github/workflows/ci.yml
+.github/workflows/deploy.yml
+its_magic
+.its-magic-version
+
+[required_install_script_paths]
+scripts/validate-and-push.ps1
+scripts/validate-and-push.sh
+scripts/sync_push_gates.py
+scripts/doc_profile_lib.py
+scripts/validate_doc_profile.py
+scripts/intake_evidence_validate.py
+scripts/intake_evidence_lib.py
+scripts/intake_bug_routing_guard.py
+scripts/check_intake_template_parity.py
+scripts/materialize_codebase_map.py
+scripts/remote_config_summary.py
+scripts/guard_installer_publish.py
+scripts/enforce-triad-hot-surface.py
+scripts/caveman_compress_input.py

package/template/docs/engineering/context/readme-section-affinity.json

@@ -0,0 +1,30 @@
+{
+  "affinity_version": 1,
+  "rules": [
+    {
+      "dev_h2": "Workflow",
+      "root_h2": "Commands and workflow",
+      "tag": "slash_command"
+    },
+    {
+      "dev_h2": "Quality gates",
+      "root_h2": "Other useful capabilities",
+      "tag": "scratchpad_mode"
+    },
+    {
+      "dev_h2": "Architecture notes",
+      "root_h2": "Features",
+      "tag": "distribution"
+    },
+    {
+      "dev_h2": "Quality gates",
+      "root_h2": "Commands and workflow",
+      "tag": "release_gate"
+    },
+    {
+      "dev_h2": "Engineering decisions",
+      "root_h2": "Other useful capabilities",
+      "tag": "governance"
+    }
+  ]
+}

package/template/docs/engineering/decisions.md

@@ -0,0 +1,16 @@
+# Decisions
+
+## Current context pack
+
+- Latest completed/released stories: none yet (clean template baseline).
+- Active in-flight story: none yet.
+- No decision gate is currently open at workflow boundary.
+
+## Compact decision index (bounded summaries)
+
+- (none yet) Add bounded decision summaries here as `DEC-xxxx` records are
+  accepted.
+
+## Canonical full records
+
+- Full records live in decisions/DEC-xxxx.md.

package/template/docs/engineering/legacy-drift-audit.md

@@ -0,0 +1,21 @@
+# Legacy drift audit (US-0049)
+
+Append-only audit log for legacy DONE-story acceptance/traceability drift
+detection and repair. Per DEC-0031; canonical path for one-time backfill and
+ongoing guard outputs.
+
+## Schema (required fields per entry)
+
+| Field | Description |
+|-------|-------------|
+| story_id | Backlog story ID (e.g. US-xxxx) |
+| prior_acceptance_state | Acceptance checklist state before repair (e.g. unchecked) |
+| prior_traceability_state | Traceability/state entry presence before repair |
+| resolved_state | State(s) after repair or guard action |
+| reason_code | One of: BACKLOG_DONE_ACCEPTANCE_UNCHECKED, BACKLOG_DONE_TRACEABILITY_MISSING, BACKLOG_DONE_RELEASE_ARTIFACT_MISSING |
+| evidence_ref | Reference to evidence used (e.g. release notes path, state.md row) |
+| timestamp | ISO UTC when entry was appended |
+
+## Entries
+
+(No drift detected yet; idempotent backfill runs leave this section empty or add "no drift" note.)

package/template/docs/engineering/manifests/components/api-gateway.manifest.yaml

@@ -0,0 +1,12 @@
+component_id: api-gateway
+repo_id: example-producer
+owner: team-example
+status: active
+exposed_contracts:
+  - contract_id: public-api
+    api_spec_ref: contracts/public-api.yaml
+    version: 1.0.1
+consumed_contracts: []
+protected_interfaces:
+  - interface_id: public-api-v1
+    description: Public API contract expected to remain stable for non-target work.

package/template/docs/engineering/manifests/registry.manifest.yaml

@@ -0,0 +1,20 @@
+schema_version: 1
+generated_at: "2026-03-01T00:00:00Z"
+repos:
+  - repo_id: example-producer
+    repo_url_or_path: ./example-producer
+    owner: team-example
+    status: active
+    manifest_ref: docs/engineering/manifests/repo.manifest.yaml
+contracts:
+  - contract_id: public-api
+    producer_repo: example-producer
+    producer_component: api-gateway
+    contract_ref: contracts/public-api.yaml
+    version: 1.0.1
+compatibility_links:
+  - contract_id: public-api
+    consumer_repo: example-consumer
+    consumer_component: web-app
+    expected_version_range: ^1.0.0
+    criticality: medium

package/template/docs/engineering/manifests/repo.manifest.yaml

@@ -0,0 +1,11 @@
+schema_version: 1
+repo_id: example-producer
+owner: team-example
+version: 1.0.1
+components:
+  - docs/engineering/manifests/components/api-gateway.manifest.yaml
+exports:
+  - contract_id: public-api
+    version: 1.0.1
+    contract_ref: contracts/public-api.yaml
+imports: []

package/template/docs/engineering/phase-context.md

@@ -0,0 +1,16 @@
+# Phase context pointers
+
+Use this file as the **first** narrow read for workflow orientation. Expand to
+linked hot or archive paths only when a question stays unresolved after the
+default set (see minimal-read table in `docs/engineering/runbook.md`).
+
+| Kind | Path | Notes |
+|------|------|-------|
+| Engineering state (hot) | `docs/engineering/state.md` | Recent checkpoints; archive under `docs/engineering/state-archive/` |
+| Decisions index | `docs/engineering/decisions.md` | Compact index; full records under `decisions/` |
+| PO → TL handoff (hot) | `handoffs/po_to_tl.md` | Narrative handoff; archive under `handoffs/archive/` |
+| Architecture (hot) | `docs/engineering/architecture.md` | Story-shaped sections; archive under `docs/engineering/architecture-archive/` |
+| Triad enforcement | `scripts/enforce-triad-hot-surface.py` | `--check` before phase completion when mutating triad surfaces |
+
+Escalation: open the **named archive pack** cited in the latest rollover
+verification tuple for the surface you need, not the entire archive tree.

package/template/docs/engineering/release-targets.json

@@ -0,0 +1,123 @@
+{
+  "version": 1,
+  "selectionPolicy": "explicit_or_default",
+  "runtimeConnectivityDoc": "docs/engineering/runtime-connectivity.md",
+  "targets": [
+    {
+      "id": "npm-public",
+      "type": "npm",
+      "enabled": false,
+      "order": 10,
+      "command": "npm publish",
+      "workingDirectory": ".",
+      "runtime": {
+        "mode": "local",
+        "protocol": "https",
+        "domainEnv": "PUBLIC_DOMAIN",
+        "port": 443
+      }
+    },
+    {
+      "id": "choco",
+      "type": "choco",
+      "enabled": false,
+      "order": 20,
+      "command": "choco push packaging/chocolatey/its-magic.*.nupkg --source %CHOCO_SOURCE%",
+      "tokenEnv": "CHOCO_API_KEY",
+      "runtime": {
+        "mode": "local"
+      }
+    },
+    {
+      "id": "brew-tap",
+      "type": "brew",
+      "enabled": false,
+      "order": 30,
+      "command": "git push origin HEAD",
+      "tokenEnv": "GITHUB_TOKEN",
+      "runtime": {
+        "mode": "local"
+      }
+    },
+    {
+      "id": "dockerhub",
+      "type": "docker",
+      "enabled": false,
+      "order": 40,
+      "command": "docker push %DOCKER_IMAGE%",
+      "tokenEnv": "DOCKER_TOKEN",
+      "runtime": {
+        "mode": "remote",
+        "hostEnv": "DOCKER_RUNTIME_HOST",
+        "port": 443,
+        "protocol": "https"
+      }
+    },
+    {
+      "id": "aws-deploy",
+      "type": "cloud",
+      "enabled": false,
+      "order": 50,
+      "command": "aws deploy create-deployment --application-name %APP_NAME% --deployment-group-name %DEPLOY_GROUP% --s3-location bucket=%S3_BUCKET%,bundleType=zip,key=%BUNDLE_KEY%",
+      "credentialEnv": "AWS_PROFILE",
+      "runtime": {
+        "mode": "remote",
+        "domainEnv": "APP_DOMAIN",
+        "ipEnv": "APP_IP",
+        "port": 443,
+        "protocol": "https",
+        "traefik": {
+          "enabled": false,
+          "router": "app",
+          "entrypoint": "websecure",
+          "tls": true
+        }
+      }
+    },
+    {
+      "id": "custom-release-hook",
+      "type": "custom",
+      "enabled": false,
+      "order": 60,
+      "command": "powershell -ExecutionPolicy Bypass -File scripts/publish-custom.ps1",
+      "runtime": {
+        "mode": "remote",
+        "domainEnv": "CUSTOM_DOMAIN",
+        "ipEnv": "CUSTOM_IP",
+        "port": 443,
+        "protocol": "https"
+      }
+    },
+    {
+      "id": "ssh-server",
+      "type": "ssh",
+      "enabled": false,
+      "order": 70,
+      "hostEnv": "SSH_HOST",
+      "port": 22,
+      "userEnv": "SSH_USER",
+      "authEnv": "SSH_PRIVATE_KEY",
+      "remoteCommand": "cd /opt/its-magic && ./deploy.sh",
+      "runtime": {
+        "mode": "remote",
+        "domainEnv": "RUNTIME_DOMAIN",
+        "ipEnv": "RUNTIME_IP",
+        "port": 443,
+        "protocol": "https",
+        "traefik": {
+          "enabled": true,
+          "router": "its-magic",
+          "entrypoint": "websecure",
+          "tls": true
+        }
+      },
+      "dockerOverSsh": {
+        "enabled": false,
+        "dockerHostEnv": "DOCKER_HOST",
+        "dockerContextEnv": "DOCKER_CONTEXT",
+        "composeFile": "docker-compose.yml",
+        "service": "app"
+      }
+    }
+  ]
+}

package/template/docs/engineering/research.md

@@ -0,0 +1,29 @@
+# Research
+
+## Entry format
+
+Each research entry uses the R-xxxx ID format with semi-structured fields.
+
+**Required fields**: ID (R-xxxx), Date (YYYY-MM-DD), Topic (short description).
+**Optional fields**: Query, Sources, Findings, Linked (US-xxxx/DEC-xxxx refs),
+Confidence (high/medium/low, default: medium), Status (current/outdated/superseded,
+default: current).
+
+### Auto-increment convention
+
+Assign the next sequential R-xxxx ID by incrementing from the highest existing
+entry in this file. Before creating a new entry, read this file to determine the
+current highest ID.
+
+### Cross-referencing guidance
+
+Reference research entries by ID in other artifacts using the format "per R-xxxx".
+Examples:
+- In decisions: "per R-0001, prompt-level isolation is unreliable"
+- In architecture: "R-0003 confirms the library supports streaming"
+- In handoffs: "see R-0002 for competitor analysis"
+
+Agents, commands, and handoffs should cite entry IDs whenever research informed
+a decision or recommendation.
+
+---