Point MPG users to canonical Gecode skills repository

README.md

@@ -15,6 +15,32 @@ Document inputs now live under `docs/src/`:
 
 During migration, tooling still supports legacy root paths with runtime warnings.
 
+## Gecode Skills
+
+Canonical Gecode skills are now maintained in:
+
+- `Gecode/gecode-skills`
+
+Install from the canonical repository:
+
+```bash
+npx skills add Gecode/gecode-skills
+```
+
+List available skills:
+
+```bash
+npx skills add Gecode/gecode-skills --list
+```
+
+Install a single skill:
+
+```bash
+npx skills add Gecode/gecode-skills --skill gecode-modeling
+```
+
+The `skills/` directory in this repository is retained as a reference snapshot for MPG work and is not the release source for published skills.
+
 ## Modern Tooling
 
 The project now uses a Python CLI as the primary interface:

skills/README.md

@@ -0,0 +1,13 @@
+# MPG Skills Snapshot
+
+Canonical published Gecode skills are maintained in:
+
+- `Gecode/gecode-skills`
+
+Install from the canonical source:
+
+```bash
+npx skills add Gecode/gecode-skills
+```
+
+This `skills/` directory is kept as a reference snapshot for MPG and local iteration, and is not the release source for skills published via `npx skills add`.

skills/case-study-skill-audit.md

@@ -0,0 +1,43 @@
+# MPG Case-Study Skill Audit
+
+Scope: `/Users/zayenz/gecode/MPG/docs/src/chapters/case-studies/*.tex.in`
+
+## Per-Case Findings
+
+| Case study | Important issues / patterns | Category | Skill mapping | Coverage before | Action |
+|---|---|---|---|---|---|
+| `c-photo.tex.in` | Objective via `cost()`, propagation-level alignment (`distinct` BND), reversal symmetry break | Optimization + symmetry | `gecode-modeling` | Partial | Added symmetry + propagation-level guidance |
+| `c-golomb.tex.in` | Tight bounds to avoid overflow risk, implied constraints, symmetry break, cost-driven branching | Modeling strength | `gecode-modeling` | Partial | Added implied-constraint and symmetry bullets |
+| `c-golf.tex.in` | Set-model symmetry reduction + extra symmetry breaking (`precede`, ordering) | Symmetry design | `gecode-modeling` | Weak | Added structural symmetry guidance |
+| `c-magic-sequence.tex.in` | Individual `count` vs global counting, implied linear constraints, value-order heuristic | Global-vs-decomposition | `gecode-modeling` | Partial | Added global-constraint replacement rule |
+| `c-nonogram.tex.in` | Regex/extensional modeling, AFC branching, propagation-only vs custom branching need | Search/branching fit | `gecode-modeling`, `gecode-brancher-implementation` | Partial | Added brancher heuristic emphasis |
+| `c-knights.tex.in` | `circuit(..., IPL_DOM)`, symmetry via fixed move, custom Warnsdorff brancher | Problem-specific brancher | `gecode-brancher-implementation`, `gecode-modeling` | Partial | Added heuristic-brancher pattern |
+| `c-kakuro.tex.in` | Naive `distinct+linear` decomposition weak, `IPL_DOM` linear cost tradeoff, extensional tuple-set surrogate, tuple-set cache opportunity | Propagation strength + modeling perf | `gecode-modeling`, `gecode-propagator-implementation` | Gap | Added decomposition-warning + cache guidance |
+| `c-warehouses.tex.in` | `count` + `element` + `linear` composition, mixed int/bool cost expression, two-stage branching | Optimization modeling | `gecode-modeling` | Partial | Added cost-driven branching guidance |
+| `c-bin-packing.tex.in` | Naive vs `binpacking` global, CDBF custom brancher, symmetry in branching, heap choice payload + `AP_DISPOSE`, region scratch, shared arrays | High-impact full-stack pattern | `gecode-modeling`, `gecode-brancher-implementation`, `gecode-memory-handling`, `gecode-general-knowledge` | Gap/partial | Added all four skills |
+| `c-crossword.tex.in` | Memory reductions (variable elimination/shared arrays), branch print hooks, restart+no-goods+AFC robustness | Search robustness + memory | `gecode-modeling`, `gecode-memory-handling`, `gecode-general-knowledge` | Partial | Added memory + iterative tuning guidance |
+
+## Priority Synthesis
+
+### P0 (applied)
+- Symmetry as mandatory design axis in modeling and branching.
+- Global-constraint substitution for weak decompositions.
+- Propagation-level cost awareness (`IPL_DOM` selectively).
+- Problem-specific branchers for structure-heavy problems.
+
+### P1 (applied)
+- Memory patterns from case studies: shared arrays, region scratch, `AP_DISPOSE` lifecycle discipline.
+- Iterative optimization loop: baseline -> propagation -> branching -> restart/no-good tuning.
+
+### P2 (applied lightly)
+- Propagator skill now explicitly calls out decomposition weakness and cacheable support data.
+
+## Skill Updates Applied
+
+- Updated `/Users/zayenz/gecode/MPG/skills/gecode-general-knowledge/SKILL.md`
+- Updated `/Users/zayenz/gecode/MPG/skills/gecode-modeling/SKILL.md`
+- Updated `/Users/zayenz/gecode/MPG/skills/gecode-propagator-implementation/SKILL.md`
+- Updated `/Users/zayenz/gecode/MPG/skills/gecode-brancher-implementation/SKILL.md`
+- Updated `/Users/zayenz/gecode/MPG/skills/gecode-memory-handling/SKILL.md`
+
+No new skill created: existing five skills cover all extracted case-study learnings after update.

skills/gecode-brancher-implementation/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: gecode-brancher-implementation
+description: "Implement custom Gecode branchers and choice mechanics: status/choice/commit, archiving, recomputation compatibility, no-good literal support, and brancher view reuse. Use when predefined `branch(...)` is insufficient."
+---
+
+# Gecode Brancher Implementation
+
+## Core
+- Brancher is actor implementing branching behavior.
+- Implement `status`, `choice(Space&)`, `choice(const Space&,Archive&)`, `commit`, `print`, `copy`, `dispose`.
+- Choice stores only space-independent commit data.
+- `commit` must work with recomputed/cloned spaces using only choice payload.
+- Choices must be archive-compatible and deterministic.
+- Branchers execute in queue order of posting.
+- Optional `ngl()` adds no-good support.
+- Brancher `status()==false` does not imply immediate disposal; commits for earlier choices must remain valid.
+
+## Key Patterns
+- Track first candidate index (`start`) to avoid rescanning.
+- Keep choice payload minimal (`pos`, `val`, alt count), archive/unarchive deterministically.
+- Use binary alternatives (`eq` vs `nq`) unless assignment brancher (single alt).
+- Implement NGL class with `status`, `prune`, `subscribe`, `cancel`, `reschedule`.
+- For complementary last alternatives, `ngl()` can return `NULL` when semantically valid.
+- Reuse branchers through views (notably minus view for max-style variants).
+- Encode problem heuristic explicitly (for example Warnsdorff, best-fit slack).
+- Mix assignment-style one-alt choices with pruning alternatives when justified.
+- Design second alternatives to embed symmetry breaking when safe.
+- Pair brancher with branch print callbacks for explainability/debugging.
+
+## Pitfalls
+- Storing views/pointers to space state inside choice objects.
+- Disposing brancher too early when `status()` becomes false.
+- Depending on mutable brancher state not encoded in choice for `commit()`.
+- Using choices after invalidation by a later `choice()` call on the same space.
+- Not skipping assigned views, causing repeated same choice/infinite tree.
+- Violating recomputation invariants and commit order assumptions.
+- Using generic variable-value branching when structure-aware heuristic is required.
+- Forgetting that brancher disposal is not automatic when external resources exist.

skills/gecode-brancher-implementation/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Gecode Brancher Implementation"
+  short_description: "Implement custom Gecode branchers and NGLs"
+  default_prompt: "Provide concise implementation guidance for Gecode branchers, choices, commits, and NGL support."

skills/gecode-general-knowledge/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: gecode-general-knowledge
+description: "Core Gecode architecture and runtime model: spaces, propagators, branchers, status/choice/clone/commit lifecycle, cloning/recomputation semantics, groups/tracing. Use when explaining solver behavior, search flow, or high-level debugging/design decisions."
+---
+
+# Gecode General Knowledge
+
+## Core
+- Space is home for variables, propagators, branchers, optimization order.
+- Propagation is explicit: call `status()`.
+- Search primitives: `status()`, `choice()`, `clone()`, `commit()`, `constrain()`.
+- Space status: `SS_FAILED`, `SS_SOLVED`, `SS_BRANCH`.
+- Choice is space-independent descriptor; alternatives indexed `0..n-1`.
+- Choice compatibility is clone-based: a choice is compatible with its source space and clones.
+- `choice()` invalidates previous choices for later `commit()` on that space.
+- Clone only stable, non-failed spaces.
+- Branchers run in posting order.
+- Recomputation can be nondeterministic with weakly monotonic propagation, while remaining sound/complete.
+
+## Key Patterns
+- Model as `class M : public Space`.
+- Implement copy constructor + virtual `copy()`.
+- In space cloning, clone variable arrays via `x.update(home, s.x)`; do not use a variable-array copy constructor.
+- After `status()==SS_BRANCH`, compute `choice()` immediately.
+- Seed search engine with model, then delete seed model.
+- Treat solution as space closure over member variables.
+- Use groups/tracing for observability, selective control.
+- Iterate model quality in loops: baseline -> improve propagation -> improve branching -> tune search.
+- Measure with nodes/time/restarts, not runtime only.
+- Treat symmetry handling as first-class design work, not post-processing.
+
+## Pitfalls
+- Assuming posting runs full propagation.
+- Calling `Space` copy constructor directly instead of `clone()`.
+- Using stale choices after invalidating via later `choice()` usage.
+- Forgetting ownership/deletion of choices and returned solution spaces.
+- Cloning unstable/failed spaces.
+- Assuming parallel search preserves sequential solution order or runtime profile.
+- Assuming one modeling pass is enough; most case studies need staged refinement.

skills/gecode-general-knowledge/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Gecode General Knowledge"
+  short_description: "Core Gecode architecture and workflow guide"
+  default_prompt: "Explain core Gecode concepts, spaces, propagation, and search operations concisely."

skills/gecode-memory-handling/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gecode-memory-handling
+description: "Manage Gecode memory areas and actor state: space/region/heap/freelists, lazy vs eager state allocation, shared/local handles, and disposal obligations (`AP_DISPOSE`). Use when implementing memory-sensitive propagators/branchers."
+---
+
+# Gecode Memory Handling
+
+## Core
+- Memory areas: space, region, heap, space freelists.
+- `alloc/realloc/free` follow C++ object lifecycle semantics.
+- Space memory auto-reclaimed on space deletion; good for stable-size actor data.
+- Region is temporary arena; implicit free on region destruction.
+- Heap is for frequently resized/dynamic structures.
+- Search memory profile favors pristine clones; allocation timing matters.
+- Shared handles: cross-space/thread shared heap object with refcount.
+- Local handles: per-space shared object, copied on cloning.
+
+## Key Patterns
+- Allocate fixed actor members in home space.
+- Allocate resize-heavy buffers on heap; free in `dispose()`.
+- Build heavy internal state lazily on first propagation when possible.
+- Choose eager vs lazy vs hybrid allocation based on clone-footprint and hit rate.
+- Use regions for short-lived temporary iterators/buffers.
+- Explicitly `Region::free()` at clear control-flow boundaries to maximize reuse.
+- Use `SharedHandle` for immutable/global lookup data.
+- Use `LocalHandle` for shared per-space mutable state.
+- Use `IntSharedArray`/shared arrays for read-only large data reused across clones.
+- For brancher choices using heap buffers, pair allocation/free and register `AP_DISPOSE`.
+- Use `Region` for per-choice scratch arrays to avoid heap churn.
+
+## Pitfalls
+- Frequent resize in space memory causing fragmentation.
+- Forgetting `home.notice(..., AP_DISPOSE)` for external/heap resources.
+- Forgetting matching `home.ignore(..., AP_DISPOSE)` in dispose path.
+- Assuming same alignment guarantees across space vs heap/region.
+- Leaking ownership assumptions across cloning boundaries.
+- Allocating per-choice temporary arrays on heap in hot paths.

skills/gecode-memory-handling/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Gecode Memory Handling"
+  short_description: "Manage Gecode memory and shared/local state"
+  default_prompt: "Summarize concise best practices for Gecode memory areas, lifecycle, and handle-based sharing."

skills/gecode-modeling/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: gecode-modeling
+description: "Model CP problems in Gecode with Int/Bool/Set/Float variables, constraints, MiniModel expressions, branchings, and search configuration. Use when building or refining Gecode models and solver setup."
+---
+
+# Gecode Modeling
+
+## Core
+- Define model as `Space` subclass.
+- Create typed variable arrays with tight domains early.
+- Post constraints via post functions (`rel`, `linear`, `distinct`, set/float variants).
+- Post branching via `branch(...)`; variable strategy + value strategy define tree shape.
+- Use search engines (`DFS`, `BAB`, restart/portfolio variants) per objective.
+- MiniModel adds expression syntax via `expr(...)`, `rel(...)`, matrix/channel helpers.
+- Reified modeling supports full and half reification; decomposition semantics matter.
+
+## Key Patterns
+- Prefer global constraints over manual decompositions when available.
+- Keep branchings explicit and problem-specific for scale.
+- Use multiple branchers intentionally; creation order matters.
+- Tune search options: recomputation distance, restarts, no-goods, stop objects.
+- Use tracing/Gist/CPProfiler for model diagnostics.
+- Add implied constraints aggressively when semantics unchanged but propagation improves.
+- Break symmetry structurally: order constraints, fixed anchors, `precede`, monotone bins.
+- Use LDSB only with supported branching/value configurations; validate symmetry assumptions.
+- Match propagation level to complexity (`IPL_DOM` only where payoff > cost).
+- Replace weak decompositions with stronger globals (`count` GCC, `binpacking`, `circuit`, `extensional`).
+- Cache reusable heavy artifacts (tuple sets, shared arrays) keyed by shape/parameters.
+- For arrays requiring non-shared vars, call `unshare(...)` once and reuse the result.
+- Use branch filters/print functions for targeted branching and observability.
+- When executing code between branchers, remember propagation is still explicit on recomputation paths.
+- For optimization models, branch on cost-driving vars first, tie with objective structure.
+
+## Pitfalls
+- Weak domains at model start causing huge trees.
+- Forgetting to update all variable members in cloning constructor.
+- Assuming MiniModel nonlinear expressions stay monolithic; many decompose.
+- Assuming reified non-functional decompositions imply `b=false`; they can fail instead.
+- Treating Boolean vars as subclass of integer vars.
+- Ignoring exceptions from invalid arguments/overflow.
+- Using domain propagation for `linear` indiscriminately (can be exponential).
+- Recomputing identical tuple sets/shared maps per post.
+- Repeated implicit-style unsharing patterns that create unnecessary vars/propagators.
+- Combining LDSB with unrelated static symmetry breaking without safety analysis.
+- Leaving major value/variable symmetries unbroken.

skills/gecode-modeling/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Gecode Modeling"
+  short_description: "Model Gecode CP problems and search setup"
+  default_prompt: "Guide concise Gecode modeling choices, constraints, branchings, and search configuration."

skills/gecode-propagator-implementation/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: gecode-propagator-implementation
+description: "Implement and optimize custom Gecode propagators: posting, propagate/reschedule lifecycle, propagation conditions, domain iterators, advisors, reification, and rewriting. Use when adding new constraints or improving propagation performance/safety."
+---
+
+# Gecode Propagator Implementation
+
+## Core
+- Propagator computes on views, not model variables.
+- Implement post function + actor lifecycle (`copy`, `dispose`, `cost`, `reschedule`, `propagate`).
+- Use `Home` for posting context; use fail/check macros.
+- Return honest `ExecStatus`: `ES_FAILED`, `ES_SUBSUMED`, `ES_FIX`, `ES_NOFIX`.
+- Respect obligations: correctness, checking, contracting, monotonicity (or waived), subscription completeness, update completeness.
+- Respect implementation obligations: subsumption complete, cloning conservative, subscription correct.
+- Use patterns (`Unary/Binary/Ternary/Nary`, mixed variants) to reduce boilerplate.
+
+## Key Patterns
+- Do cheap pruning in `post()`; skip posting when trivially subsumed/failed.
+- Select minimal propagation conditions (`*_VAL`, `*_BND`, `*_DOM`).
+- Prefer iterator-based domain ops (`inter_r`, `narrow_r`, `minus_r`) for domain propagation.
+- Use fixpoint reasoning deliberately: return `ES_FIX` only when justified.
+- Use `ModEventDelta` and staging to combine cheap and expensive propagation phases.
+- Use advisors for incremental change localization.
+- For advisors, maintain council lifecycle and ensure rescheduling/subscription completeness.
+- Rewrite propagators (`GECODE_REWRITE`) when state simplifies.
+- Use reified/rewriting patterns to remove reification overhead once control literals decide.
+- Template propagators on view types for reuse.
+- If decomposition is propagation-weak, prefer dedicated propagator or extensional surrogate.
+- Treat expensive support data as cacheable object, not per-post recomputation.
+
+## Pitfalls
+- Modifying a view while iterating its domain iterator.
+- Returning `ES_FIX` when not actually at fixpoint.
+- Returning `ES_NOFIX` when propagation is idempotent and could reach fixpoint inside the same `propagate()` call (causes avoidable re-scheduling).
+- Missing view updates/subscription cancellation during cloning/disposal.
+- Using external resources without `AP_DISPOSE` notice/ignore discipline.
+- Continuing execution after subsuming/disposing actor.
+- Failing to check modification-event failure after view updates.
+- Breaking subscription completeness when using advisors/dynamic subscriptions.
+- Expecting two weak propagators (`distinct` + `linear`) to match joint reasoning of one stronger constraint.

skills/gecode-propagator-implementation/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Gecode Propagator Implementation"
+  short_description: "Implement custom Gecode propagators safely"
+  default_prompt: "Provide concise implementation guidance for Gecode propagators, obligations, and optimization."