ExecuteSpec setup: contract index and codemap for navneetprabhakar/executor

.executespec/README.md

@@ -0,0 +1,93 @@
+# `.executespec/` — for `navneetprabhakar/executor`
+
+> Generated by ExecuteSpec on `2026-05-20T02:21:16.854859Z`.
+> Generator version `1` — regenerate at any time and
+> your edits below the auto-section will be preserved.
+
+## What is this folder?
+
+`.executespec/` is the persistent contract surface between your
+repository and ExecuteSpec. Everything ExecuteSpec generates that is
+intended to be customer-visible and git-tracked lives here. The folder
+is **git-authoritative**: ExecuteSpec's database caches the contents
+but the folder itself is the source of truth, so your manual edits are
+preserved across regeneration runs.
+
+Every change ExecuteSpec wants to make to this folder ships as a pull
+request against your default branch. Your normal review process is the
+gate; nothing lands without your approval.
+
+## Folder structure
+
+```
+.executespec/
+├── README.md                 # this file (regenerable; manual edits preserved)
+├── arch/
+│   ├── codemap.md            # per-repo code map (regenerable on merge)
+│   ├── notes.md              # arch notes scoped to this repo (manual)
+│   ├── invariants.yaml       # architectural invariants (manual)
+│   └── adrs/
+│       ├── .template.md      # ADR template
+│       └── NNNN-<slug>.md    # individual ADRs
+├── contracts/
+│   ├── produced/             # auto-detected contracts produced by this repo
+│   ├── consumed/             # contracts this repo consumes from elsewhere
+│   └── breaking-changes.log  # append-only history
+├── tests/
+│   └── contract/
+│       └── generated/        # generated contract tests (deferred to a later release)
+└── config/
+    └── executor/
+        ├── scopes.yaml             # monorepo scope declarations (when applicable)
+        ├── standards.yaml          # engineering standards
+        └── detection-overrides.yaml # auto-detection overrides
+```
+
+## What's regenerable vs review-worthy
+
+| Path | Regenerable? | Notes |
+|---|---|---|
+| `README.md` | yes (this file) | Manual edits below the auto-section are preserved across regenerations |
+| `arch/codemap.md` | yes | Regenerated on every merge to default branch via PR |
+| `arch/notes.md` | no | Customer-authored only |
+| `arch/invariants.yaml` | no | Customer-authored only |
+| `arch/adrs/*.md` | no | Customer-authored; status transitions audited via PR |
+| `contracts/produced/*` | yes | Auto-detected from your code; refresh via "Check drift" in the dashboard |
+| `contracts/consumed/*` | no | Declared explicitly through the dashboard; ExecuteSpec opens the PR |
+| `config/executor/*.yaml` | no | Customer-authored config; ExecuteSpec only proposes additions |
+
+If you mark anything as regenerable that you'd rather hand-edit, set it
+to `merge=ours` in your own `.gitattributes` — ExecuteSpec does not ship
+gitattributes opinions.
+
+## Multi-project repos
+
+When this repo is linked to more than one ExecuteSpec project, the
+`config/` sub-folder is project-namespaced (e.g.
+`config/executor/standards.yaml`,
+`config/<other-project-slug>/standards.yaml`). Each project's config is
+independent. Anything outside `config/` is shared across all linked
+projects.
+
+## Pull request title prefixes
+
+ExecuteSpec uses these PR title prefixes so your bots and humans can
+filter:
+
+| Prefix | What | Reviewable risk |
+|---|---|---|
+| `ExecuteSpec setup:` | Initial bootstrap — README + codemap | low |
+| `ExecuteSpec: codemap regeneration after PR #N` | Post-merge codemap refresh | low |
+| `ExecuteSpec: contract refresh — <name>` | Drift detected against producer source | medium (review for unintended changes) |
+| `ExecuteSpec: standards update — <id>` | Org-level standards change flowing in | medium |
+| `ExecuteSpec: ADR proposed — NNNN-<slug>` | New ADR (status: proposed) | high (architectural decision) |
+
+## Conflict resolution
+
+If your manual edit conflicts with an ExecuteSpec PR, GitHub will
+report the conflict in the PR UI. Resolve it by editing on your branch
+or in the PR; ExecuteSpec does not auto-rebase or auto-merge. The
+dashboard's drift-detection view will surface the conflicted state so
+you can find it without scanning every open PR.
+
+<!-- ExecuteSpec auto-section ends here; manual edits below are preserved. -->