Aise capture

Capture Candidate Experience

Admission Gate

Create a candidate only when at least one source is concrete:

• the user explicitly states a preference, correction, or durable instruction;
• a repository artifact, production document, tool result, or test verifies a private fact;
• repeated real work demonstrates a reusable workflow or quality gate.

Do not capture:

• general knowledge a capable model already knows or can infer cheaply;
• one-off task state, temporary IDs, current progress, or volatile values;
• model guesses without labeling them model_inference;
• secrets, credentials, or unnecessary raw private content.

Diagnose Before Changing Memory

For a failure, distinguish:

1. missing knowledge: the AI never had the private fact;
2. retrieval failure: the fact existed but was not loaded;
3. memory-quality failure: the stored item was vague, stale, or scoped incorrectly;
4. workflow failure: the procedure or tool route was wrong;
5. execution failure: the rule was correct but the tool/action failed.

Only propose a memory or skill change when the diagnosis supports it.

Candidate Schema

Prepare one JSON object with:

• key: stable, short identifier;
• kind: preference, private_fact, project_convention, workflow, tool_route, quality_gate, or guardrail;
• summary and actionable content;
• scope and target;
• source_type and a traceable source_ref;
• triggers: phrases that should retrieve this item later;
• evidence, required_checks, and supersedes when applicable;
• valid_until for facts that can expire.

Use only these enum values:

• kind: preference, private_fact, project_convention, workflow, tool_route, quality_gate, guardrail;
• scope: global, project;
• target: user-preferences, project-knowledge, workflow, tool-routing, quality-gates, skill, evaluation;
• risk: low, medium, high;
• source_type: user_explicit, verified_artifact, tool_output, test_result, model_inference.

Run physisai schema candidate when constructing a candidate programmatically. For a durable user preference, the usual mapping is scope=global, target=user-preferences, and source_type=user_explicit.

Treat scope as a storage boundary:

• global writes to the user event store under AISE_HOME and may be retrieved from other initialized projects;
• project stays in <project-root>/.ai-self-evolution/ and must never cross project roots.

Use model_inference only to preserve a hypothesis. Such a candidate cannot pass the source gate until recaptured from a promotable source. Artifact, tool-output, and test-result sources require a separately recorded source-verification check before promotion. The CLI records that assertion and its evidence; it does not inspect the referenced source by itself.

Choose a small set of concrete triggers that are likely to appear in the user's future request. Include important domain wording or known aliases, but do not copy an entire prompt or add generic words merely to increase matches. Approved triggers appear in the generated Markdown index and drive the minimal task-context query.

Keep one memory focused. If a stable procedure needs extensive branches, scripts, templates, or reference files, use this lifecycle to govern the decision, then propose a dedicated Skill instead of growing a long workflow memory indefinitely.

Write Candidate

Write private candidate input under the ignored state directory so it cannot be accidentally committed. Pass that file to the CLI so shell quoting cannot alter content:

install -d -m 700 <project-root>/.ai-self-evolution/tmp
# Write proposal.json with the host's structured file tool, then restrict it:
chmod 600 <project-root>/.ai-self-evolution/tmp/proposal.json
physisai capture --root <project-root> \
  --from-json <project-root>/.ai-self-evolution/tmp/proposal.json

On systems without POSIX modes, create the file with user-only ACLs or use stdin. Stdin is acceptable when the host can provide it without unsafe shell interpolation. Do not leave user preferences or private project knowledge in an unignored task file. Run physisai doctor --repair if a host tool created permissive files under the private state tree.

Creating a candidate does not change active AI behavior. Return the proposal ID, storage layer, source, scope, conflicts, required checks, and recommended next action. Never call physisai promote from this skill.