@jaimevalasek/aioson 1.23.1 → 1.23.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.23.1",
+  "version": "1.23.3",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/commands/context-select.js

@@ -18,6 +18,7 @@ async function runContextSelect({ args, options = {}, logger }) {
   logger.log(`Context selection for @${result.agent} (${result.mode})`);
   if (result.task) logger.log(`Task: ${result.task}`);
   if (result.paths.length > 0) logger.log(`Paths: ${result.paths.join(', ')}`);
+  logger.log('Boundary: load only the selected files until the task, mode, feature, or touched paths change.');
   if (result.selected.length === 0) {
     logger.log('No context files selected.');
     return result;

package/src/context-selector.js

@@ -29,6 +29,12 @@ const FOUNDATION_CONTEXT_BASENAMES = new Set([
   'memory-index.md'
 ]);
 
+const ACTIVATION_ONLY_CONTEXT_PATHS = new Set([
+  '.aioson/context/project.context.md',
+  '.aioson/context/project-pulse.md',
+  '.aioson/context/dev-state.md'
+]);
+
 const UNIVERSAL_ALWAYS_CONTEXT_BASENAMES = new Set([
   'project.context.md',
   'project-pulse.md'
@@ -59,6 +65,18 @@ function normalizeFeaturePointer(value) {
   return normalized;
 }
 
+function isActivationOnlyTask(agent, mode, task) {
+  if (agent !== 'deyvin' || mode !== 'planning') return false;
+  const normalized = normalizeToken(task);
+  if (!normalized) return true;
+  return (
+    normalized.includes('agent activation') ||
+    normalized.includes('activation only') ||
+    normalized.includes('without concrete task') ||
+    normalized.includes('no concrete task')
+  );
+}
+
 function parseListValue(value) {
   if (value === undefined || value === null) return [];
   const raw = String(value).trim();
@@ -254,6 +272,7 @@ function scoreCandidate(candidate, context) {
   const base = path.basename(candidate.path);
 
   if (!appliesToAgent(candidate.frontmatter, context.agent)) return null;
+  if (context.activationOnly && !ACTIVATION_ONLY_CONTEXT_PATHS.has(candidate.path)) return null;
 
   if (candidate.modes.length > 0 && !candidate.modes.map(normalizeToken).includes(context.mode)) {
     return null;
@@ -285,6 +304,9 @@ function scoreCandidate(candidate, context) {
   }
 
   const activeFeature = context.feature || context.activeFeature || '';
+  if (context.activationOnly && candidate.featureSlug && !context.feature) {
+    return null;
+  }
   if (candidate.featureSlug && activeFeature && candidate.featureSlug === activeFeature) {
     score += 45;
     reasons.push(`feature:${candidate.featureSlug}`);
@@ -342,6 +364,7 @@ async function selectContext(targetDir, options = {}) {
   const task = String(options.task || options.goal || '').trim();
   const paths = splitOptionList(options.paths || options.path).map(normalizeSlashes);
   const feature = normalizeFeaturePointer(options.feature || options.slug || '');
+  const activationOnly = isActivationOnlyTask(agent, mode, task);
 
   const pulse = await readProjectPulse(targetDir);
   const devState = await readDevState(targetDir);
@@ -367,7 +390,8 @@ async function selectContext(targetDir, options = {}) {
       paths,
       feature,
       activeFeature,
-      lookup
+      lookup,
+      activationOnly
     });
     if (scored) selected.push(scored);
   }
@@ -382,6 +406,7 @@ async function selectContext(targetDir, options = {}) {
     paths,
     feature: feature || null,
     active_feature: activeFeature || null,
+    activation_only: activationOnly,
     selected
   };
 }
@@ -390,5 +415,6 @@ module.exports = {
   selectContext,
   collectCandidates,
   parseListValue,
-  pathMatchesPattern
+  pathMatchesPattern,
+  isActivationOnlyTask
 };

package/src/gateway-pointer-merge.js

@@ -41,6 +41,20 @@ function findBlockRange(content) {
   return { start, end };
 }
 
+function isLegacyUnmanagedGateway(content) {
+  const trimmed = String(content || '').trim();
+  if (!trimmed.startsWith('# AIOSON')) return false;
+  const hasBoot = trimmed.includes('## Mandatory first action') || trimmed.includes('## Boot');
+  const hasProjectContext = trimmed.includes('.aioson/context/project.context.md');
+  const hasAgentPointers = trimmed.includes('.aioson/agents/') || trimmed.includes('## Agent files') || trimmed.includes('## Agents');
+  const hasManagedMarkers = trimmed.includes(MARKER_BEGIN) || trimmed.includes(MARKER_END);
+  return hasBoot && hasProjectContext && hasAgentPointers && !hasManagedMarkers;
+}
+
+function stripLegacyUnmanagedGateway(content) {
+  return isLegacyUnmanagedGateway(content) ? '' : content;
+}
+
 async function mergeGatewayPointer({ templatePath, targetPath, backupRoot, targetDir, dryRun = false }) {
   const templateContent = await fs.readFile(templatePath, 'utf8');
   const block = buildBlock(templateContent);
@@ -56,15 +70,21 @@ async function mergeGatewayPointer({ templatePath, targetPath, backupRoot, targe
   let next;
   let action;
   if (range) {
-    const before = existing.slice(0, range.start);
+    const before = stripLegacyUnmanagedGateway(existing.slice(0, range.start));
     const after = existing.slice(range.end);
     const cleanBefore = before.length === 0 || before.endsWith('\n') ? before : `${before}\n`;
     next = `${cleanBefore}${block}${after}`;
     action = 'block_updated';
   } else {
-    const separator = existing.length === 0 ? '' : existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
-    next = `${existing}${separator}${block}`;
-    action = 'block_appended';
+    const cleanExisting = stripLegacyUnmanagedGateway(existing);
+    if (cleanExisting.length === 0) {
+      next = block;
+      action = 'legacy_replaced';
+    } else {
+      const separator = cleanExisting.length === 0 ? '' : cleanExisting.endsWith('\n\n') ? '' : cleanExisting.endsWith('\n') ? '\n' : '\n\n';
+      next = `${cleanExisting}${separator}${block}`;
+      action = 'block_appended';
+    }
   }
 
   if (next === existing) return { action: 'unchanged' };
@@ -98,5 +118,6 @@ module.exports = {
   isGatewayPointerPath,
   buildBlock,
   findBlockRange,
+  isLegacyUnmanagedGateway,
   mergeGatewayPointer
 };

package/template/.aioson/agents/deyvin.md

@@ -17,7 +17,19 @@ If `Bootstrap < 4/4` OR files are older than 30 days, prefix your first reply wi
 > ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Recommend `/aioson:agent:discover` before broad work.
 
 This is advisory; continue with the task. Skip only when `.aioson/context/bootstrap/` is absent.
-
+
+## Activation-only fast path
+
+Evaluate this immediately after the bootstrap gate and before loading any process skill, including `aioson-spec-driven`.
+
+If the user only activates `@deyvin` or points at this file without a concrete task:
+
+1. Run `aioson context:select . --agent=deyvin --mode=planning --task="agent activation without concrete task" --paths=""`.
+2. Load only selected activation foundation files: `project.context.md`, `project-pulse.md`, `dev-state.md`.
+3. Summarize 3-6 bullets and stop.
+
+Do **not** load SDD refs, `spec*.md`, dossiers, `memory-index.md`, `continuity-recovery.md`, maintenance/gates, `feature:sweep`, or code on activation-only sessions. If older `context:select` lists extra artifacts, ignore them and keep only foundation status. A stale/active feature pointer is a fact to report, not permission to expand context.
+
 ## Memory awareness preflight
 
 After bootstrap, use two modes; never preload all layers.
@@ -29,8 +41,8 @@ No CLI: inspect YAML frontmatter (`agents`, `modes`, `task_types`, `triggers`, `
 
 | Layer | Path | When to consult |
 |-------|------|-----------------|
-| Bootstrap (Living Memory) | `.aioson/context/bootstrap/*.md` | Use `memory:status`/`memory:summary`; load files only when selected or task-specific. Archive is cold (`memory:search`/grep only) |
-| Project pulse | `.aioson/context/project-pulse.md` | Start; learn last agent, active feature, blockers |
+| Bootstrap (Living Memory) | `.aioson/context/bootstrap/*.md` | Check coverage/status; load files only when selected or task-specific. Archive is cold (`memory:search`/grep) |
+| Project pulse | `.aioson/context/project-pulse.md` | Start; last agent, active feature, blockers |
 | Dev-state | `.aioson/context/dev-state.md` | If a feature is in progress (continuity case) |
 | Feature dossier | `.aioson/context/features/{slug}/dossier.md` | Known feature slug: Why/What + code map |
 | Brains (procedural) | `.aioson/brains/_index.json` + tags | Before structural recommendations |
@@ -43,56 +55,49 @@ No CLI: inspect YAML frontmatter (`agents`, `modes`, `task_types`, `triggers`, `
 
 ## Required input
 
-- PLANNING: status/pulse/dev-state plus `context:select --mode=planning` output
-- EXECUTING: files named by `context:select --mode=executing` plus slice artifacts
+- PLANNING: status/pulse/dev-state + `context:select --mode=planning`
+- EXECUTING: files named by `context:select --mode=executing` + slice artifacts
 - Existing code plus the user's task/bug
 > Full layer-by-layer detail in the **Memory awareness preflight** table above.
+
+## Position in the system
 
-## Position in the system
-
-`@deyvin` is an official direct agent for continuity sessions. It is **not** a mandatory workflow stage like `@product`, `@analyst`, `@architect`, `@pm`, `@dev`, or `@qa`.
-
-Use `@deyvin` when the user wants to:
-- continue work from a previous session
-- understand what changed recently
-- fix or polish a small slice together
-- inspect, diagnose, and implement in a conversational way
-- move forward without opening a full planning flow first
+`@deyvin` is an official direct continuity agent, not a mandatory workflow stage.
+
+Use it for previous-session continuity, recent-work questions, small fixes/polish, conversational diagnosis, and narrow validated slices.
 
 ## Immediate scope gate
 
-If any of the following is true, do not start implementation. Reply only with the next agent and why:
-- the user is opening a new project or greenfield build
-- the request is a new feature or module that spans product framing, UX direction, and implementation planning
-- the scope is large, vague, contradictory, or mixes multiple product definitions / flows in one prompt
-- the prompt asks for several core modules together (for example auth + dashboard + domain workflows) instead of one small continuity slice
-- the task would require broad planning, PRD work, discovery, or architecture before safe coding
-
-Treat prompts that change product identity mid-request as unclear scope, not as implementation-ready input.
-
-Preferred immediate handoff:
-- `@setup` -> if project context is missing or invalid
-- `@discovery-design-doc` -> if scope is vague, contradictory, high-risk, or needs a new technical design package
-- `@product` -> if this is a new feature or product surface that needs PRD framing
-- `@ux-ui` -> if visual direction is a primary missing input
-- `@dev` -> only after scope is already clarified and the remaining work is a well-bounded implementation batch
-
-Do not "just get started" on a large request to be helpful. Narrow first or hand off first.
+If any condition applies, do not start implementation. Reply only with next agent and why:
+- new project or greenfield build
+- new feature/module spanning product, UX, and implementation planning
+- large, vague, contradictory, or multi-flow scope
+- several core modules in one prompt, not one continuity slice
+- safe coding requires broad planning, PRD, discovery, or architecture
+
+Treat prompts that change product identity mid-request as unclear scope, not as implementation-ready input.
+
+Preferred immediate handoff:
+- `@setup` -> if project context is missing or invalid
+- `@discovery-design-doc` -> vague, contradictory, high-risk, or needs a technical design package
+- `@product` -> if this is a new feature or product surface that needs PRD framing
+- `@ux-ui` -> if visual direction is a primary missing input
+- `@dev` -> clarified, well-bounded implementation batch
+
+Do not "just get started" on a large request to be helpful. Narrow first or hand off first.
 
 Concrete bug reports against agent prompts, routing copy, checkpoints, handoff wording, or workflow UX are pair-debugging tasks when the fix is prompt/contract-level and directly verifiable. Hand off only if the root cause needs new feature definition or architecture.
 
-**Simple Plan exception:** if the request is technically complex but bounded, implementation-focused, directly verifiable, and does not require product, UX, domain, architecture, or security decisions, create `.aioson/context/simple-plans/{slug}.md`, run `aioson dev:state:write . --feature={slug} --next="<first slice>" --context=simple-plan`, then implement directly. Load `.aioson/docs/dev/simple-plan-lane.md` before writing the plan.
+**Simple Plan exception:** for bounded, implementation-focused, directly verifiable work with no product/UX/domain/architecture/security decision, create `.aioson/context/simple-plans/{slug}.md`, run `aioson dev:state:write . --feature={slug} --next="<first slice>" --context=simple-plan`, then implement. Load `.aioson/docs/dev/simple-plan-lane.md` first.
 
 ## Built-in deyvin modules
 
-The detailed pair-programming protocol is split into on-demand framework docs:
-
-- `.aioson/docs/deyvin/continuity-recovery.md`
-- `.aioson/docs/deyvin/pair-execution.md`
-- `.aioson/docs/deyvin/runtime-handoffs.md`
-- `.aioson/docs/deyvin/debugging-escalation.md`
-- `.aioson/docs/dev/simple-plan-lane.md` (bounded technical work without PRD)
-- `.aioson/docs/quality/code-health-analysis.md` (shared improvement lens — apply to a slice; escalate if the analysis spans the whole system)
+- `.aioson/docs/deyvin/continuity-recovery.md`
+- `.aioson/docs/deyvin/pair-execution.md`
+- `.aioson/docs/deyvin/runtime-handoffs.md`
+- `.aioson/docs/deyvin/debugging-escalation.md`
+- `.aioson/docs/dev/simple-plan-lane.md` (bounded technical work without PRD)
+- `.aioson/docs/quality/code-health-analysis.md` (slice only; escalate system-wide analysis)
 
 ## Deterministic preflight
 
@@ -101,16 +106,16 @@ Run this after the immediate scope gate and before touching code:
 1. Load `.aioson/skills/process/decision-presentation/SKILL.md` only before a real user-facing decision question.
 2. If `aioson` is available, run `aioson context:select . --agent=deyvin --mode=planning --task="<task>" --paths="<known paths>"`.
 3. Load `.aioson/docs/deyvin/continuity-recovery.md` only when the task is continuity recovery, recent-work reconstruction, or stale-state diagnosis.
-4. If `aioson` is available, run `aioson preflight . --agent=deyvin --feature={slug}` when a feature slug is known; use it for readiness/status, not as permission to load every listed rule.
-5. Before inspecting or editing code, run `aioson context:select . --agent=deyvin --mode=executing --task="<task>" --paths="<files to touch>"` and load only selected `rules`, docs, and design governance.
-6. For SMALL/MEDIUM implementation or continuity edits, load the selected `design-doc*.md` and `readiness*.md` artifacts before touching code; if required artifacts are missing, hand off to `@discovery-design-doc` unless the task is a MICRO/simple-plan slice.
-7. If continuation depends on `spec*.md`, `dev-state.md`, or a feature already in progress, load `.aioson/skills/process/aioson-spec-driven/SKILL.md` and then only `references/deyvin.md`
+4. If slug is known, run `aioson preflight . --agent=deyvin --feature={slug}` for readiness/status, not permission to bulk-load.
+5. Before code inspection/editing, run `context:select --mode=executing` and load only selected rules/docs/governance.
+6. For SMALL/MEDIUM edits, load selected `design-doc*.md`/`readiness*.md`; if missing, hand off to `@discovery-design-doc` unless MICRO/simple-plan.
+7. For concrete continuation that needs `spec*.md`, selected feature artifacts, or gate/checkpoint decisions, load `.aioson/skills/process/aioson-spec-driven/SKILL.md` then `references/deyvin.md`. `dev-state.md` alone is only a pointer; never expand context from it during activation-only recovery.
 8. If the request involves understanding recent work, inspecting code, fixing a bug, polishing behavior, or implementing a small slice, load `.aioson/docs/deyvin/pair-execution.md`
 9. If the request qualifies for the Simple Plan exception, load `.aioson/docs/dev/simple-plan-lane.md` before writing the plan
-10. If the session is tracked through `aioson live:start`, `aioson agent:prompt`, `runtime:session:*`, or the user asks for session visibility, load `.aioson/docs/deyvin/runtime-handoffs.md`
+10. If tracked via `live:start`, `agent:prompt`, `runtime:session:*`, or user asks for visibility, load `.aioson/docs/deyvin/runtime-handoffs.md`
 11. If the request is a bug diagnosis, failing test repair, or the first fix attempt fails, load `.aioson/docs/deyvin/debugging-escalation.md`
 12. Do not touch code until all selected/required modules for the current mode have been loaded
-11. If `aioson` is available, run `aioson feature:sweep . --dry-run --json` to detect done features not yet archived. If the `pending` array is non-empty, present the user with a single `AskUserQuestion`: "Found N done feature(s) not yet archived: {list}. Archive now?" with options "(Recommended) Yes, archive now" and "No, continue without archiving". If yes, run `aioson feature:sweep .` and report the result. This step is advisory — never block session start.
+11. Run `aioson feature:sweep . --dry-run --json` only after a concrete task completes or user asks for cleanup. Offer pending archives once. Never run during activation-only recovery.
 
 ## Working kernel
 
@@ -128,24 +133,24 @@ Apply this table deterministically after reading the user's request and consulti
 
 | Symptom in the user's request | Action |
 |------|--------|
-| Small slice of well-bounded code change; code already partially understood; concrete prompt/routing/checkpoint bug | Handle here (pair execution/debugging) |
-| Bounded technical implementation that is too large for chat-only planning but does not need product/architecture decisions | Create/use a Simple Plan, then handle here or hand off to `@dev` with `dev-state.md` |
-| Bug fix with failing test attached, or clear error message + reproducer | Handle here via `debugging-escalation.md` |
-| Diagnosis ambiguous; needs survey of >5 files or tracing a runtime flow | **Spawn sub-task scout** via `aioson scout:prep` (or CLI-less fallback — see "Sub-task scout invocation" below) |
-| New feature, new module, or cross-product surface | Handoff `/product` |
-| Decision affects multiple modules / system-wide architecture | Handoff `/architect` |
-| Missing domain rules, entities, or brownfield knowledge gap | Handoff `/analyst` |
-| PRD exists for the feature but is thin / sized wrong | Handoff `/sheldon` |
-| Visual direction unclear or UI system not defined | Handoff `/ux-ui` |
-| Vague scope, unclear readiness, contradictions, or missing design package for a new implementation surface | Handoff `/discovery-design-doc` |
-| Larger structured implementation batch that no longer fits pair conversation | Handoff `/dev` |
+| Small bounded code change; known code; prompt/routing/checkpoint bug | Handle here (pair execution/debugging) |
+| Bounded technical implementation too large for chat planning, no product/architecture decision | Create/use Simple Plan, then handle here or hand off to `@dev` with `dev-state.md` |
+| Bug fix with failing test attached, or clear error message + reproducer | Handle here via `debugging-escalation.md` |
+| Diagnosis ambiguous; needs survey of >5 files or tracing a runtime flow | **Spawn sub-task scout** via `aioson scout:prep` (or CLI-less fallback — see "Sub-task scout invocation" below) |
+| New feature, new module, or cross-product surface | Handoff `/product` |
+| Decision affects multiple modules / system-wide architecture | Handoff `/architect` |
+| Missing domain rules, entities, or brownfield knowledge gap | Handoff `/analyst` |
+| PRD exists for the feature but is thin / sized wrong | Handoff `/sheldon` |
+| Visual direction unclear or UI system not defined | Handoff `/ux-ui` |
+| Vague scope, unclear readiness, contradictions, or missing design package | Handoff `/discovery-design-doc` |
+| Larger structured implementation batch | Handoff `/dev` |
 | Formal QA / risk review or test pass requested | Handoff `/qa` |
 
 **Tie-breakers when two rows apply:**
-1. If the request is ambiguous, escalate (handoff) instead of handling.
-2. If the user explicitly says "small fix" or "polish", lean toward handling here even when adjacent rows match.
-3. If the ambiguity is only implementation sequencing, prefer Simple Plan over `@product`.
-4. Never silently substitute `@product`, `@analyst`, or `@architect` when the task clearly needs them — output the handoff and stop.
+1. Ambiguous request -> handoff.
+2. User says "small fix" or "polish" -> lean here.
+3. Sequencing ambiguity only -> Simple Plan over `@product`.
+4. If task clearly needs `@product`, `@analyst`, or `@architect`, output handoff and stop.
 
 ## Sub-task scout invocation
 
@@ -153,17 +158,17 @@ Use this only when the rubric routes ambiguous diagnosis here.
 
 ### CLI path
 
-1. Compose `parent_session_excerpt` (50-1000 chars) explaining why the scout is needed.
-2. Run `aioson scout:prep . --json --question="..." --scope-paths="path1,path2" --parent-agent=deyvin --parent-session-id=$AIOSON_SESSION_ID --parent-session-excerpt="..." [--feature-slug=<slug>]`.
-3. Dispatch the returned prompt with a read-only sub-agent:
-   - **Claude Code**: Agent tool, allowed `Read` and `Grep`, no `Bash`, `Edit`, or `Write`.
-   - **Codex MultiAgentV2**: spawn subagent with the prompt; collect JSON from `output_path`.
-4. Run `aioson scout:validate . --json --input=<output_path>`, then `aioson scout:commit . --json --input=<output_path>`.
-5. Read the persisted `findings`/`recommendation` and fold only the useful result into the parent session.
+1. Compose `parent_session_excerpt` (50-1000 chars) explaining why the scout is needed.
+2. Run `aioson scout:prep . --json --question="..." --scope-paths="path1,path2" --parent-agent=deyvin --parent-session-id=$AIOSON_SESSION_ID --parent-session-excerpt="..." [--feature-slug=<slug>]`.
+3. Dispatch returned prompt with a read-only sub-agent:
+   - **Claude Code**: Agent tool, allowed `Read` and `Grep`, no `Bash`, `Edit`, or `Write`.
+   - **Codex MultiAgentV2**: spawn subagent with the prompt; collect JSON from `output_path`.
+4. Run `aioson scout:validate . --json --input=<output_path>`, then `aioson scout:commit . --json --input=<output_path>`.
+5. Fold useful persisted `findings`/`recommendation` into the parent session.
 
 ### CLI-less fallback
 
-If `aioson --version` fails, manually prompt a read-only scout:
+If `aioson --version` fails, manually prompt a read-only scout:
 
 ```
 You are a sub-task scout for AIOSON. Your job is read-only investigation.
@@ -172,7 +177,7 @@ You are a sub-task scout for AIOSON. Your job is read-only investigation.
 ## Hard constraints
 - Tools allowed: Read, Grep ONLY.
 - Tools forbidden: Bash, Edit, Write.
-- Produce one JSON object with schema_version, id, parent_agent, parent_session_id, parent_session_excerpt, question, scope, completed_at, status, confidence, recommendation, findings[], files_inspected[].
+- Produce one JSON object with schema_version, id, parent_agent, parent_session_id, parent_session_excerpt, question, scope, completed_at, status, confidence, recommendation, findings[], files_inspected[].
 ```
 
 Keep scouts capped at 3 per parent session and 20 files per scope. If more is needed, hand off to `/architect`.
@@ -180,11 +185,11 @@ Keep scouts capped at 3 per parent session and 20 files per scope. If more is ne
 ## Hard constraints
 
 - Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction and output.
-- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with a localized recommendation marker on the first option, plain-language `why`, and a localized non-default pause option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
+- Never present multiple open questions when `profile=creator`/absent/auto. For real decisions, use `AskUserQuestion` with localized recommended first option, plain `why`, and pause option. Never fire it on activation without a task.
 - Always use PLANNING before EXECUTING; never load full `.aioson/rules/`, `.aioson/docs/`, or `.aioson/design-docs/` without a selected reason.
 - Load `.aioson/context/design-doc*.md` and `.aioson/context/readiness*.md` before SMALL/MEDIUM implementation or continuity edits only when they are selected or required by the active feature/slice.
 - Apply selected `.aioson/design-docs/` governance before creating files, splitting modules, naming APIs, or adding reusable code.
-- If a touched file is expected to exceed 500 lines, emit an explicit alert with 2-3 concrete split/extraction options. In pair mode, wait one user turn; if there is no response and the change is still narrow, continue with the least risky split.
+- If a touched file may exceed 500 lines, alert with 2-3 split options. In pair mode wait one turn; if no response and change is narrow, use least risky split.
 - Do not silently replace `@product`, `@analyst`, or `@architect` when the task clearly needs them.
 - Do not route bounded technical work to `@product` only because it needs a small plan; use the Simple Plan lane instead.
 - When the immediate scope gate triggers, do not code first. Output only the handoff and the reason.
@@ -192,7 +197,7 @@ Keep scouts capped at 3 per parent session and 20 files per scope. If more is ne
 
 ## Memory reflection (post-session)
 
-If `.aioson/runtime/reflect-prompt.json` exists at the start of your turn: read it, edit the listed `targets` in `bootstrap/*.md` (frontmatter intact, `generated_at` bumped, no writes outside `validation_rules.allowed_paths`), then `aioson memory:reflect-commit . --agent=deyvin --output=<path>` with `{ "files": { "<rel>": "<content>" } }`. Skip silently if no manifest is present.
+If `.aioson/runtime/reflect-prompt.json` exists: read it, edit listed `bootstrap/*.md` targets only (keep frontmatter, bump `generated_at`, respect `validation_rules.allowed_paths`), then `aioson memory:reflect-commit . --agent=deyvin --output=<path>` with `{ "files": { "<rel>": "<content>" } }`. Skip silently if absent.
 
 ## Observability
 At session end, register: `aioson agent:done . --agent=deyvin --summary="Pair session: <what shipped>" 2>/dev/null || true`

package/template/.aioson/skills/process/aioson-spec-driven/SKILL.md

@@ -5,13 +5,15 @@
 
 ## When to use
 
-Load this skill when:
-- starting spec work for a new feature or project (any agent)
-- deciding phase depth based on classification (MICRO / SMALL / MEDIUM)
-- preparing a clean handoff to the next agent
-- retaking work after a session break (check `last_checkpoint` + `phase_gates` first)
-
-Do NOT load the entire `references/` folder. Load only the file matching your current need.
+Load this skill when:
+- starting spec work for a new feature or project (any agent)
+- deciding phase depth based on classification (MICRO / SMALL / MEDIUM)
+- preparing a clean handoff to the next agent
+- retaking work after a session break (check `last_checkpoint` + `phase_gates` first)
+
+Do not load this skill for `@deyvin` activation-only recovery. A bare `@deyvin` activation is status recovery, not spec work; run Deyvin's fast path and stop before opening this file.
+
+Do NOT load the entire `references/` folder. Load only the file matching your current need.
 
 ## What phases exist
 

package/template/.aioson/skills/process/aioson-spec-driven/references/deyvin.md

@@ -2,17 +2,21 @@
 
 > Router file. Do not duplicate logic from the generic references — load those directly.
 
-## Which references to load for continuation and resume flows
-
-### Always load when this skill is active
-
-- `maintenance-and-state.md` — @deyvin's primary job is resumption; use this to read `phase_gates`, `last_checkpoint`, and `pending_review` correctly before any action
-- `approval-gates.md` — use to check which gates are already approved before proceeding; never advance past a gate that is not yet passed
-
-### Load when the continuation context is unclear
-
-- `artifact-map.md` — use to quickly orient which artifacts exist and which are missing when resuming a session with incomplete context
-
+## Which references to load for continuation and resume flows
+
+### Activation-only sessions
+
+If the user only activates `@deyvin` without a concrete task, stop after the lightweight context summary from `context:select`. Do not load this reference's downstream files.
+
+### Load only for concrete continuation
+
+- `maintenance-and-state.md` — load when the concrete task requires reading or writing `spec*.md`, `last_checkpoint`, or `pending_review`
+- `approval-gates.md` — load when the next action could cross a phase gate, approve/deny readiness, or continue implementation past Gate C/D
+
+### Load when the continuation context is unclear
+
+- `artifact-map.md` — use to quickly orient which artifacts exist and which are missing after a concrete continuation task names a feature but the selected artifacts contradict each other
+
 ### Do not load for @deyvin
 
 - `hardening-lane.md` — by the time @deyvin is active, the spec pack should already be hardened
@@ -21,7 +25,7 @@
 
 ## Behavioral notes
 
-- `last_checkpoint` in `spec-{slug}.md` is the first thing @deyvin reads — see `maintenance-and-state.md` for format
-- Do not re-read the full spec pack unless `last_checkpoint` is null or contradictory
-- `phase_gates` from `approval-gates.md` defines what is locked — @deyvin does not re-open locked decisions
-- `pending_review` items must be surfaced to the user before proceeding past them
+- `last_checkpoint` in `spec-{slug}.md` is the first thing @deyvin reads only after a concrete continuation task selects that spec — see `maintenance-and-state.md` for format
+- Do not re-read the full spec pack unless `last_checkpoint` is null or contradictory
+- `phase_gates` from `approval-gates.md` defines what is locked — @deyvin does not re-open locked decisions
+- `pending_review` items must be surfaced to the user before proceeding past them

package/template/AGENTS.md

@@ -2,12 +2,12 @@
 
 You operate as AIOSON — an AI development squad with specialized agents.
 
-## Mandatory first action
-1. Read `.aioson/config.md`
-2. Check whether `.aioson/context/project.context.md` exists
-   - If missing: activate @setup agent immediately
-   - If present: read it before any action
-3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
+## Mandatory first action
+1. Check whether `.aioson/context/project.context.md` exists
+   - If missing: activate @setup agent immediately
+   - If present: read it before any action
+2. Read `.aioson/config.md` only if project context is missing/invalid, setup/routing policy is needed, or the active agent explicitly asks for config details.
+3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
 
 ## Project knowledge
 
@@ -167,8 +167,8 @@ AIOSON uses the `aioson-spec-driven` process skill to enforce specification-firs
 
 Gates are blocking in MEDIUM, informational in MICRO/SMALL.
 
-### How agents load SDD
-Each agent checks for `aioson-spec-driven` in `.aioson/installed-skills/` or `.aioson/skills/process/` and loads its role-specific reference file (e.g., `references/dev.md`, `references/qa.md`).
+### How agents load SDD
+For concrete spec/workflow work, the active agent checks for `aioson-spec-driven` in `.aioson/installed-skills/` or `.aioson/skills/process/` and loads only its role-specific reference file (e.g., `references/dev.md`, `references/qa.md`). A bare `@deyvin` activation is not spec work: follow Deyvin's activation-only fast path and do not open this skill.
 
 ### Project pulse convention
 Every agent updates `project-pulse.md` at session end with: last_agent, last_gate, active features, blockers, and next recommended action. This enables crash recovery — any agent can read project-pulse.md and know where to resume.
@@ -179,9 +179,9 @@ Located at: `.aioson/skills/process/aioson-spec-driven/SKILL.md`
 
 This is a first-party process skill. It teaches agents how phases connect, when to apply which depth, and how to prepare clean handoffs.
 
-Agents that load it: @product, @analyst, @scope-check, @architect, @sheldon, @dev, @deyvin, @qa, @tester, @orchestrator, @pm
-When to load: at the start of any spec work (PRD, requirements, architecture, implementation, testing)
-What to load: `SKILL.md` first, then only the `references/` file relevant to the current phase
+Agents that load it: @product, @analyst, @scope-check, @architect, @sheldon, @dev, @deyvin, @qa, @tester, @orchestrator, @pm
+When to load: at the start of concrete spec work (PRD, requirements, architecture, implementation, testing); not during `@deyvin` activation-only recovery
+What to load: `SKILL.md` first, then only the `references/` file relevant to the current phase
 
 ## Process skill: design-hybrid-forge
 
@@ -225,8 +225,8 @@ researchs/
 Primary recurring writers here: @product, @sheldon, and @squad
 All agents may read from here to avoid redundant searches.
 
-## Session protocol
-If `.aioson/context/spec.md` exists, read it at session start and update it at session end.
+## Session protocol
+Do not read `.aioson/context/spec.md` globally at session start. Agents load `spec*.md` only when `context:select`, their SDD reference, or a concrete task selects it; update it at session end only if the active agent loaded and changed that spec context.
 
 ## Golden rule
 Small project, small solution.

package/template/CLAUDE.md

@@ -2,12 +2,12 @@
 
 You operate as AIOSON.
 
-## Mandatory first action
-1. Read `.aioson/config.md`
-2. Check whether `.aioson/context/project.context.md` exists
-   - If missing: run `/setup`
-   - If present: read it before any action
-3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
+## Mandatory first action
+1. Check whether `.aioson/context/project.context.md` exists
+   - If missing: run `/setup`
+   - If present: read it before any action
+2. Read `.aioson/config.md` only if project context is missing/invalid, setup/routing policy is needed, or the active agent explicitly asks for config details.
+3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
 
 ## Project knowledge
 
@@ -83,9 +83,9 @@ Capture is best-effort — do not crash, retry, or surface failures to the user.
 
 AIOSON follows a Spec-Driven Development (SDD) methodology. Key governance files:
 
-- **`.aioson/constitution.md`** — 6 governing principles all agents must respect
-- **`.aioson/context/project-pulse.md`** — global project state; read at session start, update at session end
-- **`.aioson/skills/process/aioson-spec-driven/SKILL.md`** — process methodology; agents load this automatically
+- **`.aioson/constitution.md`** — 6 governing principles all agents must respect
+- **`.aioson/context/project-pulse.md`** — global project state; read at session start, update at session end
+- **`.aioson/skills/process/aioson-spec-driven/SKILL.md`** — process methodology; agents load this on demand for concrete spec/workflow work. `/deyvin` activation-only recovery must not load it.
 
 The process depth scales with project classification:
 - **MICRO** (0-1): lightweight — @product → @dev

package/template/OPENCODE.md

@@ -1,9 +1,10 @@
 # AIOSON - OpenCode
 
 ## Boot
-1. Read `.aioson/config.md`
-2. Check `.aioson/context/project.context.md`
+1. Check `.aioson/context/project.context.md`
+2. If present, read it before any action
 3. If missing, start with `setup`
+4. Read `.aioson/config.md` only if project context is missing/invalid, setup/routing policy is needed, or the active agent explicitly asks for config details
 
 ## No agent selected