Sdcorejs ai agent

<!-- claude-adapter: generated from required-actions; do not edit mirror by hand -->

SDCoreJS AI Agent

Execute an approved AI-agent plan as an authoring track. This skill produces application contracts, integration code, deterministic tests, and verification evidence. It does not install a provider runtime into this skill pack and it does not perform live provider calls.

Entry Gate

Require all of the following before writing:

• an immutable approved plan with track: ai-agent;
• its immutable approved spec and shared approval_hash;
• a valid plan approval_hash whose verified parent graph includes that spec;
• an agent_architecture block that names one engine_profile, one capability_profile, target paths, trust boundaries, tool boundaries, persistence policy, approval policy, eval policy, and verification commands;
• explicit user selection of sequential or parallel execution through sdcorejs-execute-plan.

If any item is absent, ambiguous, stale, or hash-invalid, stop and return to the owning workflow gate. Do not infer a profile from prose after plan approval. Create and verify approved spec/plan identity only through _refs/shared/approved-artifact.mjs; do not use a track-local hash scheme. When a legacy portable handoff names these values approved_spec_hash and approved_plan_hash, each value must equal the corresponding shared approval_hash; the aliases do not authorize an independent hash contract.

Shared Protocols

Read _refs/shared/runtime-protocols.md, _refs/shared/system-registry.json, and _refs/ai-agent/manifest.json. Apply _refs/shared/artifact-lifecycle.md when .sdcorejs/** is written. Use _refs/shared/repository-contract.mjs for repository ownership and _refs/ai-agent/execution-identity.mjs for profile resolution, approved graph verification, runtime approval fingerprints, downstream artifact identity, and offline/live evidence classification.

Use the live Tasks section for progress. Preserve unrelated working-tree changes and fail closed on overlapping paths.

Execution Contract

1. Record branch, HEAD, status, diff summary, approved artifact paths, and verification baseline.
2. Verify the approved spec/plan graph and shared approval hashes before source edits.
3. Resolve engine_profile and capability_profile exactly once from the manifest. Record the resolved IDs and file paths in the live task record.
4. Load the common security floor, the selected engine, the selected capability, profile-contract.json, and only the shared references required by the approved plan.
5. Validate profile completeness. A capability profile may narrow behavior but must not weaken the common security floor.
6. Confirm trusted tenantId, actorId/service principal, roles, permissions, locale, correlationId, accessScope, and application session come from authenticated server/application or job context. Model/user input cannot define or override them. The executor must not author concrete tenantId, actorId, roles, permissions, session values, or trusted-context records into application source, config, or scenario inputs, or use them as runtime defaults, to satisfy this check. Clearly synthetic test-only values may exercise trust rejection and authorization boundaries but must never be promoted into runtime trust or evidence. When the trusted server or job source is absent, stop, retain the existing paths, and do not fabricate a substitute.
7. Implement only approved target paths. Keep tools business-shaped, enforce authorization server-side, and make mutation approval, idempotency, resource version, audit, and redaction behavior explicit.
8. Run the offline contract validator, deterministic evals, focused tests, then the approved broader verification. Live compatibility claims require separate current evidence and are never inferred from offline fixtures.
9. Emit ai_agent_context for downstream owners.
10. Enter the mandatory finish chain: test, review, repair when findings exist, code documentation, product traceability when user-visible, user-guide decision, relevant memory, verify-before-done, then branch-ready.

The executor must not invoke Git. Git artifacts remain owned by sdcorejs-git after the final read-only gates.

Module-owned AI-agent contracts, integration code, and evidence live in the module repository named by the approved artifacts. An unavailable/unwritable module owner blocks; portal fallback is forbidden. This repository remains a skill pack and must not add an @sdcorejs/ai runtime package.

Engine Boundary

The engine profile owns lifecycle mechanics only:

• openai-responses: the application owns the loop, tool dispatch, state, and continuation policy.
• openai-agents-sdk: the runner owns the loop while application code still owns tools, permissions, approval policy, persistence, and evidence.

Do not mix lifecycle assumptions between engine profiles. Do not create a third provider or engine without a separately approved scope change.

Capability Boundary

The capability profile owns business policy: objective, evidence rules, tool categories, approvals, state delta, token delta, scenarios, invariants, and quality thresholds. It never owns credentials, trusted identity, tenant selection, raw infrastructure tools, or a relaxation of the common floor.

Required Runtime Context

Build this immutable evidence for each downstream stage. Pass the complete context through context.pass; do not echo it to the user by default. The user projection preserves the outcome, changed paths, verification, live-provider status, findings, risks, blockers, and next action.

ai_agent_context:
  schema_version: 1
  contract_id: <shared contract id>
  requirement_id: <shared requirement id>
  track: ai-agent
  stack_profile: ai-agent
  owner_repository_id: <stable repository id>
  owner_repository_role: <repository role>
  owner_module_id: <module id>
  ownership_scope: module
  source_revision: <40-character Git revision>
  approved_spec:
    repository_id: <stable owner repository id>
    artifact_id: <approved spec artifact id>
    artifact_kind: spec
    repository_relative_path: <approved spec path>
    revision: <40-character owner-repository revision>
    approval_hash: <sha256:v1 hash>
  approved_plan:
    repository_id: <stable owner repository id>
    artifact_id: <approved plan artifact id>
    artifact_kind: plan
    repository_relative_path: <approved plan path>
    revision: <40-character owner-repository revision>
    approval_hash: <sha256:v1 hash>
  engine_profile: <resolved engine id>
  engine_profile_path: <resolved path>
  capability_profile: <resolved capability id>
  capability_profile_path: <resolved path>
  runtime_owner: <application component>
  common_security_floor: _refs/ai-agent/profiles/common.md
  manifest: _refs/ai-agent/manifest.json
  profile_contract: _refs/ai-agent/profile-contract.json
  validator: _refs/ai-agent/validate-agent-contract.mjs
  agent_contract_paths: [<path>]
  target_paths: [<path>]
  trusted_context_sources: [<server or job source>]
  authorization_and_tenant_policy: <contract reference>
  tool_contract_paths: [<path>]
  approval_bindings: <exact input/version policy>
  session_controls: <owner/isolation/concurrency policy>
  evidence_policy: <provenance/freshness/partiality policy>
  observability_and_audit_policy: <redacted policy>
  usage_and_finops_policy: <budget/pricing attribution policy>
  limits: <bounded turns/tools/handoffs/duration/tokens>
  provider_storage_policy: <disabled or approved governance reference>
  deterministic_eval_commands: [<command>]
  focused_test_commands: [<command>]
  downstream_artifacts:
    test: <test-plan identity>
    review: <review-report identity>
    repair: <repair-report identity>
    ship: <release-evidence identity>
  offline_verification:
    evidence_class: GOLDEN
    commands: [<command>]
    result: PASSED | FAILED | NOT RUN
  live_provider_verification:
    evidence_class: LIVE_AGENT
    credentials_available: false
    result: NOT RUN
    evidence: null
  context_hash: <sha256:v1 hash>
  findings: []

When provider credentials are unavailable, run the complete offline suite and record live provider verification as NOT RUN; never claim live validation passed. The executor must not author or predeclare PASSED in source, config, fixtures, or scenario inputs; an offline PASSED value may be emitted only after the listed verification commands run successfully and produce actual command evidence. Application or runtime source must never return offline_verification as PASSED unconditionally or derive it from static config or fixture data. PASSED is orchestration evidence emitted only after the listed command runs successfully with attached command evidence; it is not application runtime output. A live PASSED result requires separate current durable evidence.

Reject downstream work when this block conflicts with the approved hashes, resolved profiles, changed target paths, or current working-tree evidence.

Failure Conditions

Stop without partial claims when:

• trust identity can be model-supplied or client-authoritative;
• a generic raw data, HTTP, record mutation, or code execution tool is exposed;
• a side effect lacks exact-input approval, idempotency, resource versioning, authorization, audit, redaction, or deterministic failure behavior;
• provider storage is enabled without explicit governance approval;
• session reuse can cross tenants or users;
• evidence may be invented or material freshness/partiality is hidden;
• limits, deterministic gates, or zero-tolerance security thresholds are absent;
• validation, tests, review, or final verification fails.

Report exact failed checks, retained changes, and the next owning skill.