@ainova-systems/intelligence 0.11.0-rc.10 → 0.11.0-rc.13

package/packages/sync/references/conventions.md

@@ -283,7 +283,7 @@ Size limits are backstops, not quotas:
 
 Every line enters a finite context budget. Prefer subtraction, consolidation and precise scope over exhaustive prose.
 
-## Generated output
+## Generated output and version control
 
 | Target | Rules | Skills | Agents |
 |---|---|---|---|
@@ -297,22 +297,24 @@ Every line enters a finite context budget. Prefer subtraction, consolidation and
 
 `AGENTS.md` is regenerated by the `agents` adapter. Its optional static header is `targets.agents.header` in `intelligence.yaml`; generated rule, agent and skill sections follow it. Commit `AGENTS.md` when it is the project's shared canonical context.
 
-Generated IDE output may be gitignored when every collaborator can reproduce it with `intelligence sync`. Use narrow ownership patterns so hand-authored tool settings remain trackable:
+By default, commit the manifest, lock, project-owned content, `AGENTS.md`, and shared `.github/` output. Ignore the restorable package store and tool output owned by enabled adapters. `intelligence init` and `intelligence adapter enable` add these patterns without ignoring shared tool roots or settings:
 
 ```gitignore
 # CLI-managed package store
 .intelligence/
 
-# Generated Claude and Cursor content; settings remain trackable
-.claude/rules/
-.claude/agents/
-.claude/skills/
-.cursor/rules/
-.cursor/agents/
-.cursor/skills/
+# Local root instructions migrate into project rules; local preferences stay ignored
+CLAUDE.md
+.cursorrules
+
+# Generated Claude and Cursor content; shared settings remain trackable
+.claude/*
+!.claude/settings.json
+.cursor/*
+!.cursor/settings.json
 
 # Generated open-standard and Codex content
-.agents/
+.agents/skills/
 .codex/agents/
 
 # Generated Pi content
@@ -320,12 +322,27 @@ Generated IDE output may be gitignored when every collaborator can reproduce it
 .pi/extensions/intelligence-sync-rules.ts
 .pi/prompts/intelligence-agent-*.md
 
-# Generated OpenCode agents. Its commands directory may also contain
-# hand-authored files, so choose per-project ignores there.
+# Generated OpenCode agents. Commands share a directory with hand-authored
+# files, so they remain tracked unless the project chooses exact file ignores.
 .opencode/agents/
 ```
 
-Copilot output lives under `.github/`; choose whether to commit it with other repository-level GitHub configuration. Do not ignore `.github/` wholesale.
+Copilot output lives under `.github/` and is committed with other repository-level GitHub configuration. Do not ignore `.github/` wholesale. `AGENTS.md` is also committed so every clone has the shared tool-neutral entry point before sync.
+
+`AGENTS.md` is the only shared root instruction entry point. During onboarding,
+move useful repository guidance from legacy root files such as `.cursorrules`
+and instruction-bearing `CLAUDE.md` into project-owned rules, verify the
+generated tool output, then remove the legacy file. Keep a root tool-specific
+file only when it contains genuinely local configuration that an adapter cannot
+represent; keep that exception gitignored rather than maintaining a second
+committed instruction source.
+
+Before the first render, `intelligence init` preserves existing AI prompt paths
+under `<content-dir>/_backup/`. Its `manifest.tsv` labels the snapshot
+`initial-onboarding` and lists exact original paths. The context-learning skill
+first recovers or verifies CLI setup, then routes that state through
+`onboarding-migration.md` and repository learning. The backup remains until the
+user approves removal.
 
 ## Project-owned adapters
 
@@ -337,7 +354,7 @@ intelligence adapter create mytool
 intelligence adapter enable mytool
 ```
 
-Project adapters survive CLI upgrades and may override a built-in by name. `intelligence adapter enable mytool` runs a full sync so shared context stays current. `intelligence adapter disable mytool` keeps generated output for explicit, adapter-aware cleanup; a disabled project adapter can then be deleted with `intelligence adapter remove mytool`. See `adapters.md` for the function, ownership and safety contracts.
+Project adapters survive CLI upgrades and may override a built-in by name. Each adapter declares a versioned ownership contract beside its sync function; backup, rollback, dependencies and Git policy all consume it. `intelligence adapter enable mytool` runs a full transactional sync so shared context stays current. `intelligence adapter disable mytool` keeps generated output for explicit cleanup; a disabled project adapter can then be deleted with `intelligence adapter remove mytool`. See `adapters.md` for the interface and safety contract.
 
 ## Schema and command boundaries
 
@@ -346,7 +363,7 @@ The permanent applied-schema key is the top-level scalar `schema_version` in `in
 The public lifecycle is deliberately compact:
 
 - `intelligence init [--preview|--apply]` is universal: it creates a new setup, aligns an existing Intelligence project, or plans/applies conversion of an eligible legacy Intelligence Sync project.
-- `intelligence sync [adapter]` first aligns an existing Intelligence project with the installed CLI, restores a missing store strictly from `intelligence.lock`, then renders. In CI it refuses an alignment that would change tracked files and points to a local `intelligence init --apply` plus review/commit.
+- `intelligence sync [adapter] [--compact]` first aligns an existing Intelligence project with the installed CLI, restores a missing store strictly from `intelligence.lock`, then renders. Compact mode shows only final status on success and all diagnostics on failure. In CI it refuses an alignment that would change tracked files and points to a local `intelligence init --apply` plus review/commit.
 - `intelligence update [@scope/name] [--preview|--apply]` is the only update surface. It prints the CLI/project/package plan; default mode prompts, `--preview` never writes, and `--apply` does not prompt. It never moves `ref:` pins.
 - `intelligence package add|remove|list|search` owns package inventory.
 - `intelligence adapter list|create|enable|disable|remove` owns adapter inventory and target state.
@@ -382,4 +399,4 @@ Callers capture the real code with `command || rc=$?`. Do not use `if ! command;
 | `<content-dir>/{rules,agents,skills,adapters}/` | Project source of truth | Tracked |
 | `.intelligence/` | Restorable package store | Ignored |
 | `AGENTS.md` | Generated canonical project context | Normally tracked |
-| Tool output directories | Generated native content | Project policy; use narrow ignores |
+| Tool output directories | Generated native content | Built-in adapter-owned paths ignored; shared settings tracked |

package/packages/sync/references/onboarding-migration.md

@@ -0,0 +1,74 @@
+# Migrating Existing AI Instructions
+
+Read this reference only when repository onboarding finds pre-existing AI
+instructions, an `<content-dir>/_backup/` created by `intelligence init`, or a
+Git diff showing that the first sync replaced tracked tool output.
+
+## Inventory and recovery
+
+When `<content-dir>/_backup/manifest.tsv` contains
+`state<TAB>initial-onboarding`, it is the authoritative inventory from before
+the first generated write. Read each `target` and `path` record before looking
+at current adapter output. If `path<TAB>AGENTS.md` is present, the backed-up
+file is the original custom project contract; keep following it while deciding
+how to migrate its durable guidance.
+
+Treat these as migration inputs, not as current generated output:
+
+- root `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and
+  `.github/copilot-instructions.md`;
+- Claude and Cursor rules, agents, skills, and commands;
+- Copilot instructions, prompts, agents, and skills;
+- Codex/Open Agent Skills, Pi rules/prompts, and OpenCode agents/commands;
+- scripts or documentation that describe an older sync path.
+
+Prefer the copy under `<content-dir>/_backup/`. If it is absent and the first
+sync changed tracked files, inspect their pre-sync content read-only through
+Git (`git diff` and `git show HEAD:<path>`). Never restore old content directly
+into an adapter output directory.
+
+Build one conflict report before proposing changes:
+
+- `MIGRATE`: instruction-bearing files whose useful content needs a
+  project-owned destination;
+- `PRESERVE`: settings and unrelated shared files the adapters do not own;
+- `REPLACE`: adapter-owned paths that sync regenerates;
+- `STALE`: references to removed paths or commands requiring a decision.
+
+Always preserve `.claude/settings.json`, `.claude/settings.local.json`,
+`.cursor/settings.json`, Git metadata, workflows, and non-AI repository files.
+
+## Reverse mappings
+
+Migrate meaning, not tool syntax:
+
+| Existing format | Project-owned destination |
+|---|---|
+| Root `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, Copilot root instructions | Split verified guidance by topic into rules; keep local machine preferences in a gitignored root file only when no adapter representation exists |
+| `.claude/rules/*.md` | Rule; preserve valid `paths:` |
+| `.cursor/rules/*.mdc` | Rule; rename `globs:` to `paths:` and remove `alwaysApply:` |
+| Claude/Cursor/Copilot agents | Agent; map native model/readonly/tool fields back to `tier:` and `access:` |
+| Claude/Cursor/Copilot skills or commands | Skill when the procedure is repeated, multi-step, stable, and verifiable; otherwise a rule or no artifact |
+| Pi/OpenCode/Codex prompt artifacts | Rule, agent, or skill according to responsibility, after removing tool-specific wrappers |
+
+Verify every retained claim against repository code or executable
+configuration. Do not preserve stale instructions merely because they existed.
+Prefer updating an existing project-owned artifact to creating a sibling.
+
+## Apply and cleanup
+
+Obtain approval per `CREATE`, `UPDATE`, `REMOVE`, or `KEEP` proposal. Apply
+project-owned source changes first, then run `intelligence sync` and
+`intelligence status --check`. Inspect the enabled targets to prove the
+migrated guidance arrived before removing old root instructions or tool files.
+
+For every removed or renamed path, search all tracked files with `git ls-files`
+and report remaining references with file and line number. Apply an unambiguous
+replacement directly; ask about narrative or otherwise ambiguous references.
+
+The CLI owns generated-output `.gitignore` entries. Verify its patterns against
+the enabled adapters and preserve `AGENTS.md`, `.github/`, shared settings, and
+unrelated files under shared tool roots.
+
+Keep `<content-dir>/_backup/` until the user separately approves its removal
+after migration and reference checks pass. The backup remains gitignored.

package/packages/sync/skills/intelligence-install-adapter/SKILL.md

@@ -22,17 +22,24 @@ rules, agents, and skills.
    agents, skills, and whether it reads `AGENTS.md`. Record links and separate
    verified behavior from assumptions.
 
-3. Run `intelligence adapter create $ARGUMENTS`, then implement
-   `sync_to_$ARGUMENTS()` in the scaffolded project adapter. Follow
+3. Run `intelligence adapter create $ARGUMENTS`, then keep
+   `adapter_contract_$ARGUMENTS()` aligned with every path the adapter writes
+   and implement `sync_to_$ARGUMENTS()` in the scaffolded project adapter. Follow
    `<module>/references/adapters.md` and the closest built-in. Keep writes beneath
-   the configured output, make reruns idempotent, and make owned cleanup paths
-   explicit. Ignore only those owned paths; shared roots remain trackable.
+   the configured output, make reruns idempotent, distinguish exclusive
+   `owned` paths from marker-based/shared `managed` paths, and declare exact
+   legacy, preserved, dependency, ignore, and include records when applicable.
 
 4. Run `bash -n` on the project adapter, then
    `intelligence adapter enable $ARGUMENTS`. If the CLI says the adapter
    requires `agents`, enable that adapter first.
 
+   The CLI derives generated-output ignores from the adapter contract. Do not
+   edit `.gitignore` manually; correct the contract when policy is wrong, and
+   never ignore a shared output root.
+
 5. Require `IS_STATUS=ok`, inspect generated files against the researched
-   format, run the tool's validator when one exists, and finish with
+   format, deliberately fail a later test adapter to prove transactional
+   rollback when contributing a built-in, run the tool's validator when one exists, and finish with
    `intelligence status --check`. Report evidence, output paths, and any
    unsupported artifact type.

package/packages/sync/skills/intelligence-learn-from-context/SKILL.md

@@ -1,11 +1,50 @@
 ---
 name: intelligence-learn-from-context
-description: "Capture session lessons and apply to intelligence/ after approval"
-argument-hint: <optional-lesson-statement>
+description: "Finalize or recover initial Intelligence onboarding, or capture one approved session lesson later"
 ---
 
 # Learn from Context
 
+This is the safe continuation point after `intelligence init`. It first makes
+the deterministic setup healthy. When it finds an initial-state backup, it
+then follows `intelligence-learn-from-repository` to migrate repository
+knowledge. Without onboarding state, it captures a lesson from the current
+session as described below.
+
+## Recover or finish initial setup first
+
+1. Locate `<manifest>`, `<content-dir>`, and `<module>`. If the slash command
+   was not installed because the first sync failed, these instructions may
+   have been opened directly from
+   `.intelligence/packages/@ainova-systems/sync/skills/intelligence-learn-from-context/SKILL.md`.
+2. Check for `<content-dir>/_backup/manifest.tsv`. A record
+   `state<TAB>initial-onboarding` means the backup is the byte-preserved state
+   from before Intelligence first wrote adapter output. Read every `path`
+   record and treat those files as migration input, never generated output.
+   A `.intelligence/backup/config.yaml` file instead identifies a converted
+   legacy Intelligence Sync project; treat it as repository onboarding too and
+   use the converted project sources plus that config as migration evidence.
+3. Run `intelligence status --check`. If the project is missing, inconsistent,
+   or its first sync failed, run `intelligence init --preview`, show the exact
+   repair plan, and request approval. After approval run
+   `intelligence init --apply`. Do not reproduce manifest, package, adapter,
+   backup, or `.gitignore` mechanics manually.
+4. Run `intelligence sync`. Sync is transactional: a failure restores every
+   adapter-owned path. Resolve the reported cause and retry; do not continue
+   semantic migration until `IS_STATUS=ok` and `intelligence status --check`
+   is clean.
+5. If initial-onboarding or converted-legacy evidence exists, load
+   `<module>/skills/intelligence-learn-from-repository/SKILL.md` and follow its
+   complete analyze, approval, apply, sync, and verification procedure. A
+   custom original `AGENTS.md` remains authoritative migration evidence at
+   `<content-dir>/_backup/AGENTS.md`; the generated root `AGENTS.md` points to
+   it until onboarding is finalized. Keep the backup until its removal is
+   separately approved. Stop after repository onboarding; do not also invent a
+   session lesson.
+
+Continue below only when no initial-onboarding backup exists and setup is
+healthy.
+
 Use after a session where a meaningful preference, working pattern, or recurring friction emerged that should persist into future sessions. Runs in two phases — analyze (read-only) then apply (after user approval).
 
 ## Principle: positive framing
@@ -60,10 +99,12 @@ Present the proposal list to the user. User accepts or rejects per item. Only ac
    - `UPDATE` existing artifact → edit the file directly, applying the proposed change
    - `ARCHIVE` → move to `<content-dir>/_archive/` and update cross-references that point at it
 
-8. **Run `/intelligence-sync`** once all accepted items are applied.
+8. Run `intelligence sync` once all accepted items are applied. Require
+   `IS_STATUS=ok`, then run `intelligence status --check`.
 
 ## Related skills
 
+- `intelligence-learn-from-repository` — initial onboarding, legacy instruction migration and generated-output policy
 - `intelligence-extract-skill` — when the lesson is a multi-step workflow to be made reusable
 - `intelligence-review-skills` — broader audit across existing intelligence/ artifacts
 - `intelligence-add-rule`, `intelligence-add-skill`, `intelligence-add-agent` — each authors one artifact; Phase B delegates to them

package/packages/sync/skills/intelligence-learn-from-repository/SKILL.md

@@ -12,24 +12,52 @@ mechanical setup; this skill adds only repository-specific judgement.
 
 1. Run `intelligence status --check`. If setup is missing or incomplete, stop
    and ask the user to run `intelligence init`; do not reproduce CLI mechanics.
+   A clean check proves only that the mechanical setup is healthy; do not call
+   repository onboarding complete while legacy instruction migration or other
+   proposed tailoring still awaits approval.
 2. Read `<manifest>` and resolve `<content-dir>` and the configured source
    directories. Load `<module>/references/conventions.md` and the bundled
    `intelligence-add-rule`, `intelligence-add-skill`, and
    `intelligence-add-agent` skills before proposing authored content.
+   When existing AI instructions, `<content-dir>/_backup/`, or overwritten
+   tracked tool output is present, also read
+   `<module>/references/onboarding-migration.md` and use its inventory,
+   reverse-mapping, and stale-reference procedure.
+   When `<content-dir>/_backup/manifest.tsv` declares
+   `state<TAB>initial-onboarding`, treat each `path` record as the exact
+   pre-Intelligence state. Never infer that files beside the backup are the
+   originals after sync.
 3. Inspect repository evidence: its README and contributor instructions,
    language and package manifests, build and test entry points, source layout,
    CI, existing agent instructions, and existing project-owned rules, agents,
-   and skills. Treat documentation as a claim and verify important behavior in
-   code or executable configuration.
-4. Inventory what initialization already preserved or installed. Do not
+   and skills. Detect submodules and treat them as separate repositories unless
+   the user explicitly includes them. Treat documentation as a claim and
+   verify important behavior in code or executable configuration.
+4. Inventory what initialization preserved or installed. Do not
    recreate package-owned content, duplicate existing instructions, or convert
-   generated target output into source content.
+   current generated target output into source content. Treat committed legacy root
+   instruction files such as `.cursorrules` and instruction-bearing `CLAUDE.md`
+   as migration sources, not permanent parallel entry points: propose moving
+   still-valid guidance into project-owned rules and removing the legacy file
+   after the generated output is verified. Keep one only for genuinely local,
+   gitignored configuration that an adapter cannot represent. `AGENTS.md`
+   remains the only shared root instruction entry point.
+   Review `.gitignore` against the enabled adapters and the generated-output
+   ownership table in the conventions. Treat missing CLI-managed patterns as a
+   setup correction, not as a new repository convention; preserve shared
+   settings and never ignore `.github/` or `AGENTS.md`.
 5. Propose the smallest useful project-owned layer. Prefer updating an existing
    artifact over creating a sibling. Each proposal must state:
-   - `CREATE`, `UPDATE`, or `KEEP`;
+   - `CREATE`, `UPDATE`, `REMOVE`, or `KEEP`;
    - the source path;
    - the repository evidence supporting it;
    - the concise content or responsibility it would add.
+   When `targets.agents.header` is absent or generic, also propose a concise
+   manifest header with the project name, verified stack summary, and a link to
+   its canonical context rule. Keep it to 3-5 lines.
+   When the header says Intelligence onboarding is pending, replacing that
+   transitional backup pointer is part of the proposal; do not leave it after
+   the original `AGENTS.md` guidance has been migrated and verified.
 
 Analysis is read-only. Present the proposal and request approval per change.
 It is valid to recommend no new artifacts when the repository already explains
@@ -40,12 +68,17 @@ itself well.
 6. Apply only accepted proposals. Delegate new artifacts to
    `intelligence-add-rule`, `intelligence-add-skill`, or
    `intelligence-add-agent`; update an existing project-owned artifact directly
-   when that is the smaller change. Never edit installed package content or
-   generated tool output.
-7. Run `intelligence sync`, then `intelligence status --check`. Completion
-   requires `IS_STATUS=ok` and a clean consistency check.
+   when that is the smaller change, and edit an accepted manifest header
+   directly. Never edit installed package content or generated tool output.
+7. Run `intelligence sync`, then `intelligence status --check`. Inspect the
+   relevant generated `AGENTS.md`, Cursor rules, and Claude rules to verify that
+   the migrated guidance reached each enabled target. Only then remove each
+   separately approved legacy root instruction file and rerun the consistency
+   check. Completion requires `IS_STATUS=ok`, a clean final check, and no
+   `onboarding is pending` header after migrated guidance is accepted.
 8. Report what was created, updated, or deliberately left unchanged. Remind the
-   user to review and commit generated and source changes according to project
+   user to commit source, manifest, lock, `AGENTS.md`, and shared `.github/`
+   changes; generated local adapter output should match the reviewed ignore
    policy.
 
 ## Related skill

package/packages/sync/skills/intelligence-review-skills/SKILL.md

@@ -82,5 +82,5 @@ The user accepts items individually; bulk-accept for low-impact tweaks is fine.
 
 ## Related skills
 
-- `intelligence-learn-from-context` — single-lesson capture; this skill's apply phase delegates to its Phase B
+- `intelligence-learn-from-context` — setup recovery or single-lesson capture; this skill delegates accepted edits to its Phase B
 - `intelligence-extract-skill` — when the audit surfaces a workflow that should become a skill